AIエージェントの skill / tool を複数PCへ配布する時の罠と回避策

社内の複数PCに AIコーディングエージェント（Claude Code 等）の skill・共通ツールを 配布・自動更新する仕組みを運用する際に、必ず踏む3つの罠と回避手順。

前提とする構成

• 配布元: 公開 Git リポジトリ（<配布リポジトリ>）に tools/*.mjs と skills/<name>/SKILL.md を置く
• 各PC: ~/<配布物ディレクトリ> にgit clone ではなく raw からのファイルコピーとして展開
• 同期: セッション開始フックが同期スクリプトを1日1回実行し、skill を ~/.claude/skills/ へ配る

罠1: 配布物ディレクトリは git リポジトリではない

「最新化して」と言われて git pull しようとすると fatal: not a git repository になる。 配布はファイルコピーなので、更新経路は同期スクリプト自身。

ls -la ~/<配布物ディレクトリ>   # .git が無いことを確認 → git 系コマンドは使わない

罠2: 同期スクリプト自体が古いと、自己更新に必要なファイルが存在しない

同期スクリプトを新形式（.mjs）に移行した後、旧形式（.ps1 等）のまま止まっているPCが残る。 その状態では指示されたコマンドがそもそも実行できない（ファイルが無い）。

先にブートストラップする。CDN キャッシュを外すため必ずキャッシュバスターを付ける:

node -e "
const fs=require('fs'),path=require('path'),os=require('os');
const dir=path.join(os.homedir(),'<配布物ディレクトリ>','tools');
const base='https://raw.githubusercontent.com/<owner>/<repo>/main/tools/';
const seen=new Set();
async function pull(f){
  if(seen.has(f))return; seen.add(f);
  const r=await fetch(base+f+'?cb='+Date.now());
  if(!r.ok){console.log('MISS',r.status,f);return;}
  const t=await r.text(); fs.writeFileSync(path.join(dir,f),t); console.log('wrote',f,t.length);
  for(const m of t.matchAll(/from\s+['\"]\.\/([^'\"]+)['\"]/g)) await pull(m[1]);
  for(const m of t.matchAll(/import\(\s*['\"]\.\/([^'\"]+)['\"]/g)) await pull(m[1]);
}
(async()=>{ await pull('<同期スクリプト>.mjs'); })();
"

要点は「再帰取得」。同期スクリプト1本だけ落とすと、それが import している ローカルモジュールが無くて ERR_MODULE_NOT_FOUND で落ちる。 正規表現で from './x.mjs' と動的 import('./x.mjs') の両方を辿り、依存を全部引く。

罠3: skill は「配布した瞬間」ではなく「セッション開始時」に読み込まれる

配布直後に /<skill名> を打つと Unknown command が返る。 SKILL.md の frontmatter が壊れていると誤診しやすいが、原因はロードのタイミング。 エージェントからホットリロードはできない（MCP サーバや権限モードと同じハーネス側の制御）。

• 検証は1回だけ: head -12 ~/.claude/skills/<name>/SKILL.md で frontmatter の name: と description: が読めれば配布は成功している。
• 利用者に「再起動してください」と作業を振らない。 「次にウィンドウを開き直せば自動で有効になります」と伝えるだけでよい。
• 待たせない。 skill の実体はただの Markdown 手順書なので、 cat ~/.claude/skills/<name>/SKILL.md を読んでエージェントが手動で同じ手順を実行すればよい。

罠の外: 配布URLをコミットSHAで固定しない

?cb=<timestamp> 付きの /main/ を使う。SHA 固定すると改修のたびに利用者へ 「新しいURLに貼り替えて」と手作業を作り込むことになる。 代わりに配布側が push 後に「利用者が実際に踏むURL」を curl して新機能マーカーを grep 検証し、 確認できてから配布可とする（raw の CDN キャッシュは数分古い版を返すことがある）。

完了判定

ls ~/.claude/skills/                       # 期待する skill が並ぶ
head -12 ~/.claude/skills/<name>/SKILL.md  # frontmatter が読める

同期スクリプトの実行ログ（~/.claude/hooks/<sync>.log 等）に skills updated: ... が出ていれば配布は完了している。 /<skill名> が使えるようになるのは次のセッションから。

鍵配布が絡む場合の切り分け

同期時に鍵配布サーバから HTTP 401 が返ることがある。 クライアント設定を疑う前にログの時系列を見る。同一の秘密で 「401 → しばらく後に成功」ならサーバ側の問題（秘密が未登録／環境変数の反映待ち）で、 各PCの設定変更は不要。ログに「どの秘密を使ったか」の1行を必ず残しておくと切り分けが即終わる。