update-project-skills

プロジェクトのスキルを更新する

対象プロジェクトにインストールされているすべてのスキルを、現行の skills.sh CLI で最新の公開バージョンに更新し、その後 https://github.com/toy-crane/skills の Toycrane セットと照合して整合させ、インストール済みのスキルに含まれるカスタムエージェントを Claude Code と Codex の両方で利用できるようにします。

.agents/skills をプロジェクトの正規スキルコピーとして扱います。CLI は .claude/skills の相対リンクを通じて、同じスキルファイルを Claude Code に公開します。skills-lock.json には CLI がインストールしたすべてのスキルとそのソースが記録されています。source が toy-crane/skills のエントリーを Toycrane 管理対象、それ以外のエントリーをサードパーティ製として扱います。ロックエントリーのないスキルとエージェントはプロジェクトローカルのため、ユーザーが名前の採用を明示的に承認しない限り、そのまま保持します。

CLI を実行する

以下の各コマンドでは、現在公開されている CLI を <runner> skills@latest として実行します。対象プロジェクトのパッケージマネージャーに応じて <runner> を選びます。bun の場合は bunx、pnpm の場合は pnpm dlx、それ以外の場合は npx -y を使用します。package.json で別のパッケージマネージャーが devEngines を通じて指定されていると、CLI の起動前に npm が npx を EBADDEVENGINES で中断します。

インストール済みのすべてのスキルを更新する

1. 指定されたパスまたは現在のディレクトリから対象の Git リポジトリを特定します。変更を加える前に、その指示を読み、ステータスを確認します。

2. インストール済みのスキル一覧と上流のスキル一覧を確認します。

   <runner> skills@latest list --json
   <runner> skills@latest add toy-crane/skills --list
   

   プロジェクトの skills-lock.json を読みます。上流の一覧は、現在公開されている Toycrane セットです。ソースリポジトリの .agents/skills にある、開発専用の依存関係は無視します。

3. すべてのソースから、ロックされているスキルをすべてプロジェクトスコープの 1 回の呼び出しで、その場で更新します。

   <runner> skills@latest update -p -y
   

   CLI は、skillPath が記録された各ロックエントリーを更新し、ソースごとに 1 回クローンし、現在のクライアント用と汎用の .agents コピー用に再インストールします。既存の .claude/skills リンクは相対リンクのため、そのまま参照できます。出力のうち、以下の 3 点を最終レポートに含めます。スキルごとの結果、skillPath の追跡が始まる前にインストールされたためその場で更新できないエントリー（表示される再インストールの案内も含む）、および上流で削除されたと報告されたスキルです。最後の 2 つのグループは報告どおりに扱います。再インストールするか削除するかは、ユーザーが決めます。

Toycrane セットを照合して整合させる

公開されている Toycrane の一覧をロックと照らし合わせて分類します。

• 新たに公開され、ローカルに同名のものがない汎用スキルをインストールします。
• expo グループの新しいスキルは、package.json が expo または react-native に依存している場合にのみインストールします。スタックの検出は新規インストールの可否のみを制御します。すでに管理対象のスタック固有スキルは、スタックが検出されなくなっても更新を続けます。
• 公開された Toycrane のスキル名がローカルに存在し、一致するロックエントリーがない場合は、名前の衝突として扱います。パスを表示し、採用前に確認を求めます。
• 公開されなくなった、ロック済みの Toycrane スキルをすべて廃止します。

スタックによる除外と未承認の名前衝突を除外した状態で、新しいスキルを明示的な 1 回の呼び出しでインストールし、その後、廃止する名前をプロジェクト全体から削除します。

<runner> skills@latest add toy-crane/skills \
  --skill <new-skill-name> [<new-skill-name> ...] \
  --agent codex claude-code \
  -y
<runner> skills@latest remove <retired-skill-name> [<retired-skill-name> ...] -y

廃止時はスコープを指定せずに削除します。エージェントをスコープに指定して削除すると、正規の .agents コピーとロックエントリーが残る場合があります。

コンパニオンエージェントを同期する

新しく更新されたプロジェクト内のこのスキルから、同期スクリプトを実行します。

python3 .agents/skills/update-project-skills/scripts/sync_companion_agents.py \
  --project <project-root> \
  [--retired-skill <retired-skill-name> ...]

直前の同期処理で削除された、Toycrane が管理するスキルごとに --retired-skill を 1 つ追加します。これにより、skills-lock.json にスキルが記載されなくなった後、プロジェクトレベルのエージェントマニフェストでそのスキルの宣言を廃止できます。

スクリプトがスキャンするのは、skills-lock.json によって Toycrane 管理であることが確認されたインストール済みのスキルのみです。スキルは companion-agents/manifest.json でコンパニオンを宣言します。スクリプトはそのネイティブ定義を .claude/agents/<name>.md と .codex/agents/<name>.toml にコピーし、.agents/toycrane-agents-lock.json に所有権を記録します。また、プロジェクトに .agent-sync/manifest.json がすでにある場合は、shared_skills と shared_agents の両方を同期します。

所有権ロックにより、後から該当するエージェント名を更新および廃止できます。それ以外のエージェントファイルとマニフェスト項目は、引き続きプロジェクトの所有物です。スクリプトが未所有の競合を報告した場合は、競合するすべてのパスを示し、その名前の採用について承認を求めます。承認後は、承認された名前のみを採用します。

python3 .agents/skills/update-project-skills/scripts/sync_companion_agents.py \
  --project <project-root> \
  --adopt <approved-agent-name>

個別に承認された名前が複数ある場合は、それぞれに対して --adopt を繰り返します。内容が同一であることや、マニフェストにすでに宣言があることから承認を推測してはいけません。競合チェックでは、ファイル名だけでなく、すべてのネイティブエージェント定義の内部で宣言された名前を使います。採用時は、承認された名前と同一のエージェント定義が別のパスにあれば削除してから、Claude Code と Codex の正規の組み合わせを書き込みます。

結果を確認する

• <runner> skills@latest list --json を再実行します。

• 現在の Toycrane スキルがそれぞれ .agents/skills に存在し、skills-lock.json でソースが toy-crane/skills と記録されていることを確認します。また、.claude/skills/<name> が ../../.agents/skills/<name> への相対リンクであることも確認します。

• 廃止された Toycrane スキルがロックファイルと両方のスキルパスから削除されていること、サードパーティのロック項目で元のソースが維持されていること、プロジェクトローカルのスキルが変更されていないことを確認します。

• コンパニオンチェックを実行します。

  python3 .agents/skills/update-project-skills/scripts/sync_companion_agents.py \
    --project <project-root> \
    --check
  

• .agent-sync/manifest.json が存在する場合は、コンパニオンチェックの後にリポジトリのエージェント同期チェックを実行します。現在管理されている Toycrane スキルがすべて shared_skills に、すべてのコンパニオンが shared_agents に記載されていることを確認します。

• Git の差分全体を確認します。スキルごとに、変更の有無と変更量（git diff --stat で十分です）を報告し、その後に更新でスキップされた項目と、警告された上流での削除を報告します。その後、リポジトリのコミットポリシーに従います。

• 現在の Claude Code または Codex のセッションで、新しくインストールされたカスタムエージェントを利用できない場合は、更新を完了し、エージェントのルーティングをテストするには新しいセッションが必要であることを報告します。

制約事項

• すべての変更をプロジェクト内に限定します。--global または -g は決して使わないでください。
• サードパーティのスキルは、その場での更新によってのみ変更します。新しいサードパーティスキルのインストールや、上流から消えたスキルの削除は、ユーザーがスキル名を指定して依頼するまで保留します。
• 所有権を維持できるよう、skills-lock.json、存在する場合は .agents/toycrane-agents-lock.json、更新されたスキル、管理対象のエージェントファイルをまとめてコミットします。
• ロックによって Toycrane の所有であると確認できない成果物は、名前を指定した明示的な承認なしに削除または上書きしてはいけません。
• ユーザーから依頼がない限り、プッシュしないでください。