agent-skill-management

エージェントスキルの管理

この機能を使用して、2層構成のプロジェクトでエージェントスキルを管理し、スキルの検出と有効な読み込みを確認するか、アクター単位の取得、保持、復旧を確立します。管理には、スキルの追加、編集、名前変更、移動、削除が含まれます。ほかのプロジェクトにインストールできる移植可能な機能である配布可能なスキルは、ソースディレクトリ（慣例的には skills/。信頼できる唯一の情報源）で作成し、vercel-labs/skills CLI（npx skills）を使ってスキルルート（エージェントが実際に読み込むディレクトリ。Claude Code では .claude/skills/、Codex などでは .agents/skills/）にインストールします。skills-lock.json ファイルにはインストールされた内容が記録されます。単一プロジェクト独自のプロセスを定義し、サーフェスの編集中に発動する必要があり、プロジェクト独自の指示からオンデマンドで振り分けられるドキュメントではない機能を提供するリポジトリローカルスキルは、スキルルート直下に直接コミットし、CLI では決して変更しません。

どちらの層でも、スキルへの振り分けを行うのは検出機能です。各スキルは、それぞれの description を通じて適用される状況を示すため、記述されたインデックスは不要です。ホストによっては独自のインデックス（例：AGENTS.md の表）を管理している場合もあり、その場合は最新の状態に保つべき第2の記録となります。

このスキルは自己完結型です。リポジトリ固有のファイルやレイアウトを指定せず、リポジトリルートのインデックスも参照しないため、単独でインストールしても機能します。以下のディレクトリ名は慣例的なデフォルトです。ソースには skills/、スキルルートには Claude Code で .claude/skills/、Codex で .agents/skills/ を使います。異なる場合は、ホストプロジェクトで選択したパスに置き換えてください。また、両方のホストを対象とするプロジェクトではルートが2つあり、そのうち一方がもう一方へのシンボリックリンクになっている場合があることに注意してください。

ガイドライン：

• ホストプロジェクトがスキルの記述されたインデックスを管理している場合、どちらかの層でスキルを追加、名前変更、移動、削除するたびに、プロジェクトのスキル作成規約に従ってインデックスを必ず同期してください。インデックスを管理していない場合は、各スキルの description フロントマターが検出に関するすべてであり、インデックスを作成する必要はありません。

この文書で使われている「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」というキーワードは、RFC 2119 に記載されているとおりに解釈してください。

その内容はスキルですか？

スキルがどの階層に属するかを判断する前に、そもそもその内容をスキルにすべきかを確認してください。スキルがドキュメントに対して持つ機能上の利点は、見つけてもらえることだけです。該当する箇所を編集中に、誰かが参照を思い出さなくても、尋ねられる前に呼び出されます。そして、その利点は繰り返し発生するコストのすべてでもあります。どのタスクに必要かどうかに関係なく、すべてのセッションの一覧で、すべてのスキルの description がスペースを取り合います。尋ねられる前に呼び出される必要のない内容は、常時読み込まれる指示ファイルから必要に応じて参照できるため、そのコストを払っても意味がありません。

一つの事例から、複数の種類のガイダンスが明らかになることがあります。エージェントが誰を割り当てなければならないかというプロジェクトの選択、割り当てを確認するための汎用的な手順、ホストに設定された権限には、それぞれ異なる所有者がいます。移動先を決める前に、それらの記述を分けてください。段落全体をまとめて移動する必要はありません。

内容	移動先
プロダクトの正体、意味、動作、制約	プロジェクトが管理するプロダクトの最新ドキュメント
エージェントのみに対するプロジェクト固有の義務	AGENTS.md など、プロジェクトのエージェント向け指示
人間のコントリビューターやエージェントがプロジェクトの構成、執筆、ビルド、運用、実行を行う方法	プロジェクトのコントリビューター向けドキュメント
実際の個人設定、ホスト設定、環境設定、または設定済みの値	その所有者がサポートする設定方法とワークフロー
該当するタスクや箇所の作業中に見つけてもらう必要がある機能	既存のスキルの所有者、または新しいスキルが妥当な場合は、以下の階層の選択

設定に関する行が対象とするのは設定そのものであり、その設定を利用する再利用可能な手順ではありません。ホスト固有の運用手順書でそのワークフローを説明することはできますが、汎用的なルールを個人設定ごとにコピーしても、環境固有になるわけではなく、所有者が増えるだけです。プロジェクトが明示する配置ポリシーと、現在のホストにおける指示の優先順位は、引き続き適用されます。

以下の移植性に関する問いでは、この判断はできません。リポジトリ構成に関する_ドキュメント_は、リポジトリ構成に関する_スキル_と同じ程度に移植できません。そのため、どちらも移植性に関する答えは「いいえ」です。先に移植性を問うと、まずスキルにすべきかを検討しないまま、その内容はリポジトリ固有のスキルでなければならないと読者が結論づけてしまいます。

ガイドライン：

• 新しい内容の場合も、既存のスキルに変更で追加しようとしている内容の場合も、階層の選択より先に、必ずこの問いに答えてください。
• 各記述の所有者を決める前に、プロジェクトの範囲、想定する行為者、実際の環境への依存度に応じて、混在したガイダンスを必ず分割してください。
• 再利用可能な手順は、適用される機能の所有者のもとに置き、プロジェクトの指示や個人設定にコピーしないでください。実際の設定には、サポートされている設定ワークフローを使用してください。
• 常時読み込まれる指示ファイルから必要に応じて参照できる内容については、スキルを作成しないでください。その参照にかかるコストは、その指示ファイルに一行分だけであり、他のすべてのセッションの一覧には影響しません。
• この問いによって分類し直された既存のスキルは、必ず廃止してください。適用される変更要件に従って、その内容を所有者となる指示、ドキュメント、またはサポート対象の設定に移し、両方を残すのではなく、スキルを削除してください。

ティアの選択

各スキルは、次の1つの問いによって決まる、ちょうど1つのティアに属します。変更を加えずに別のプロジェクトへインストールしても、そのスキルは機能しますか？

• 自己完結していて移植可能なスキル、つまり特定のリポジトリ固有のファイル、ワークフロー、レイアウトを参照しないスキルは、配布可能です。ソースディレクトリ（skills/<name>/）に作成し、CLI でインストールします。
• あるプロジェクト固有のプロセスを機能として定義するスキル、つまりプロジェクトに合わせて調整されたスキル作成ルール、プロジェクト独自の変更サイクル、プロジェクト固有の差分に基づいて記述されたレビューポリシーは、リポジトリローカルです。スキルのルート（.claude/skills/<name>/、またはそのパスを読み取るホストでは .agents/skills/<name>/）の直下に直接コミットします。

ガイドライン：

• その内容はスキルか？でスキルに該当すると判断した後、SKILL.mdを書く前に、上記の移植性に関する問いに基づいて、必ずすべての新しいスキルをちょうど1つのティアに配置してください。
• リポジトリローカルのスキルをソースディレクトリに保存したり、npx skillsで管理したりしてはいけません。skills-lock.jsonには表示されません。
• スキルの対象範囲が変わった場合は、必ず意図的にティアを変更してください。リポジトリローカルのスキルを後に共有用として一般化した場合は、そのソースをskills/<name>/へ移し、CLI で再インストールします。両方にコピーを残してはいけません。
• skills-lock.jsonを確認してスキルのティアを判断してもかまいません。そこに記載されているスキルは配布可能でインストール済みであり、記載されていないスキルはリポジトリローカルです。

リポジトリローカルのスキル

リポジトリローカルのスキルでは、スキルのルートにコミットされたコピーが信頼できる唯一の情報源です。インストール済みコピーを手動編集してはいけないという規則は、ここには適用されません。これらのファイルをその場で編集するのが正しいワークフローです。

ガイドライン：

• リポジトリローカルのスキルは、スキルのルート（.claude/skills/<name>/、またはホストが読み取る同等のパス）の直下で、SKILL.md、references/、および必要なscript/を直接編集し、これらのファイルをコミットしてください。別のソースディレクトリやインストール手順はありません。
• フロントマター、命名、検出用メタデータ、段階的な情報開示など、プロジェクトのスキル作成規約に従い、他のスキルと同じ基準で必ず作成してください。
• リポジトリローカルのスキルの名前を変更する場合は、ディレクトリに対してgit mvを実行し、対応するフロントマターのnameを更新するとともに、同じ変更内ですべての旧名への参照を更新してください。

配布可能なスキル：インストールと更新

配布可能なスキルは skills/<name>/SKILL.md（その隣に references/ を配置）として作成し、CLI でインストールします。CLI は npx 経由で実行します。環境がシンボリックリンクをサポートしない場合は、--copy を指定してインストールします（コピーはスキルルート内に実ディレクトリとして配置されます）。

コマンド：

• 管理対象のすべてのスキルをインストールまたは更新します：

  npx skills add ./skills --agent claude-code --skill '*' --yes --copy
  

• 名前を指定して単一のスキルを更新します：

  npx skills add ./skills --agent claude-code --skill <name> --yes --copy
  

• 複数の名前付きスキルを更新します — --skill フラグをそれぞれに指定します：

  npx skills add ./skills --agent claude-code --skill <name> --skill <other-name> --yes --copy
  

• インストール済みスキルを一覧表示します：npx skills list

• インストール済みスキルを削除します：npx skills remove <name>（その後、ソースの skills/<name>/ を削除し、ホストがスキルの一覧を記録している場合は更新します）。

ガイドライン：

• 配布可能なスキルは、必ずソースディレクトリ（skills/<name>/）の下に作成してください。スキルルートの直下に作成してはいけません。
• ソースを管理している場合、スキルルート内のインストール済みコピーを直接編集してはいけません。ソースを編集してから再インストールしてください。
• ソーススキルを編集した後は、必ずインストールを再実行し、コミット対象のインストール済みコピーと skills-lock.json をソースに一致させてください。
• すべてのインストール済みスキルルート（.claude/skills/<name>/、.agents/skills/<name>/、または両方）と skills-lock.json は、skills/ ソースとともに必ずコミットしてください。これらは追跡対象の成果物であり、gitignore の対象ではありません。
• シンボリックリンクがサポートされていない場合は、必ず --copy を指定してください。シンボリックリンクによるインストールでは、その環境のスキルルートが空になるか、リンク切れになります。
• 広範囲な変更の後は、すべての管理対象スキルを更新するために必ず --skill '*' を使用してください。対象を絞る場合は --skill <name> を使用します。--skill フラグで指定できるスキルは1つだけなので、複数をインストールする場合はリストを渡すのではなく、--skill <name> --skill <other-name> のように繰り返してください。
• No matching skills found という応答（インストールの概要が表示されるべきところに、ソースで利用可能なスキル一覧が CLI から返される）は、何もインストールされなかった実行として扱う必要があります。スキルルートにスキルは配置されず、ロックファイルも書き込まれません。よくある原因は、カンマ区切りの --skill a,b,c です。CLI は値を分割しないため、どのスキルにも一致せず、利用可能なスキル一覧がエラーではなく通常のヘルプのように表示されます。
• ./skills を解決でき、skills-lock.json がそこに書き込まれるよう、npx skills add はリポジトリのルートから実行することを推奨します。
• コミット前に、インストールの概要ですべての想定スキルが copied と表示されていることを確認することを推奨します。この確認により、何も一致せず、何もインストールされなかった実行を検出できます。
• npx skills が could not determine executable to run で中断した場合は、明示的なバージョン指定（npx --yes skills@latest …）で再試行することを推奨します。上記の通常形式を標準とし、バージョン指定は npx がパッケージ名だけでは解決できない環境での代替手段です。

検出とアクティブな読み込み

次の内容については、active-loading.md を参照してください。

• インストールまたは更新を、インストール、ソースとの一致、検出、アクティブなコンテンツのそれぞれについて個別に確認する
• 同名の優先順位、古いセッション、利用できないソースの証拠など、検出されない場合や予期しないコンテンツが読み込まれる場合の診断
• 許可されたインストール変更を行う前の診断

アクターごとの取得と復旧

次の内容については、actor-local-acquisition.md を参照してください。

• 管理下にある各内部アクターの現在のコンテキストで、該当する本文と参照をすべて確保する
• タスクに応じた開発または内部レビューの選定と、出力評価の担当を適用する
• ネイティブ読み込み、直接取得、保持されたテキストを区別し、網羅性を完全、一部、不明、不一致、利用不可として扱う
• 親や再利用された割り当て識別子から取得を推測せず、想定した資料と観測された資料を照合する
• 完全な保持済みテキストを重複して読み直すことなく、検証済みの1つのリビジョンから切り詰めや保持データの消失を復旧する
• 取得を出力の検証および検証証拠の評価から切り分け、外部レビューの証明を追加しない

オプションのセーフガードに関する主張の参照

オプションのセーフガードが取得を妨げずに監視する、または依存する変更を防止するという主張を評価する場合は、該当する取得セーフガードの適格性確認プラクティスがあれば参照してください。その担当者がいない場合は、適格性評価が未実施であると報告してください。取得範囲だけでは、セーフガードやその監査フォールバックの適格性を確認できません。取得の意味を明確にすること自体に、ガードの適格性確認や、同じ質問について適格性確認の呼び出し元を再読み込みする必要はありません。

インストール済みスキルへの変更提案

installed-rule-changes.mdを参照してください。内容は次のとおりです。

• スキルの階層に応じて、誤りのあるルール、古いルール、読み込まれていないルールを実際のソースに差し戻す方法
• 追加的なローカル規約、承認済みの限定的な逸脱、未採用の上流提案を区別する方法
• 専用の台帳を用意せずに、人による採用、ホスト側の優先順位、適用範囲、再評価を確認する方法
• 適用される変更ゲートに従って担当するソースを修正するか、承認済みのサードパーティーへの要望を公開する方法

ロックファイル

skills-lock.jsonはインストール用のロックファイルで、package-lock.jsonに相当します。各配布可能なスキルのsource、sourceType、インストール済みコンテンツのcomputedHashを記録し、インストール状態を再現可能にし、差異を検出できるようコミットされます。リポジトリ内のローカルスキルはこのファイルには記載されません。

[email protected]以降、CLIはlocalのsourceを絶対パスではなく、ロックファイルのディレクトリを基準とするパスとして書き込みます。パス区切りには/を使用するため、チェックアウトやプラットフォームをまたいでも可搬性が保たれます。相対パスが存在しない場合、たとえばソースが別のファイルシステムのルートにある場合に限り、絶対パスにフォールバックします。いずれか1つのスキルを更新すると、更新したスキルだけでなく、すべてのlocalエントリーのsourceが同じ正規化方式で書き換えられます。そのため、編集していないスキルのエントリーまで変更されたロックファイルの差分は、差異ではなく、この正規化処理によるものです。1.5.22より古いCLIは引き続き絶対パスを書き込むため、チェックアウトのロックファイルには、インストール時に最後に実行されたバージョンに応じて、どちらの形式も含まれる可能性があります。

2026-08-05公開のv1.5.22リリースノートで確認済みです。

ガイドライン：

• skills-lock.jsonは必ずコミットし、手動編集ではなく、インストールコマンドを実行して再生成してください。
• 対応するソース編集がないcomputedHashの変更は、調査すべきインストールの差異として扱い、確認せずにコミットしないでください。
• computedHashに変更がなく、localのsourceフィールドだけに触れる差分は、差異ではなく上記の正規化処理として扱うことを推奨します。ロックファイルが2つの形式の間で交互に変わる場合は、インストール時に最後に実行されたCLIのバージョンを確認してください。

インストール済みコピーのドリフトチェック

インストール済みコピーは追跡対象の成果物であり、ビルド出力ではないため、手作業で編集しても防ぐものがなく、次回のインストールで何も通知されずに変更が破棄されます。このスキルには、依存関係を最小限に抑えた Node のチェック（標準ライブラリのみ）である scripts/check-installed-copies.mjs が含まれています。各ソーススキルとインストール済みコピーをファイル単位、バイト単位で比較するため、再インストール忘れや手作業による編集を、後で発覚するのではなくマージ前に検出できます。

例：

# Substitute the skill root the host reads (.claude/skills, .agents/skills, …).
node skills/agent-skill-management/scripts/check-installed-copies.mjs skills .claude/skills

両方のルートを指定する必要があり、デフォルト値はありません。ディレクトリ構成はプロジェクトごとに異なり、推測したルートが何にも一致しなければ、ドリフトは報告されません。その結果は、実際に問題がない場合と見分けがつかない成功扱いになります。このチェックでは、4 種類の差異を報告します（インストール済みコピーにないファイル、コピーにのみ存在するファイル、内容の不一致、インストール済みコピーが存在しないソーススキル）。さらに、ソースもリポジトリ内ローカルの指定もないインストール済みスキルも報告します。リポジトリ内ローカルの各スキルには、繰り返し指定できる --local <name> を付けてください。付けない場合、チェックはそのスキルをドリフトとして扱います。このチェックでは意図的に skills-lock.json を無視します。ロックファイルはインストール時にのみ書き込まれるため、現在ディスク上にある状態ではなく、最後のインストールで行われたことを記録します。そのため、インストール済みコピーの編集後に発生した変更を検出できません。まさにこのチェックが検出しようとしているドリフトです。また、source フィールドが示すのはスキルの取得元であり、インストール済みコピーの場所ではないため、比較対象のどちらのルートも特定できません。正しい状態を示すのはディレクトリの内容です。

すべてのインストール済みコピーが一致する場合は 0、ドリフトがある場合は 1、呼び出し方に誤りがある場合、またはルートがディレクトリでない場合は 2 で終了します。

ガイドライン：

• 配布対象のスキルを変更した後は必ずこのチェックを実行し、終了コード 1 はインストール忘れや手作業でのコピー編集とみなし、インストール済みツリーを編集する理由として扱わないでください。
• チェックでは指定されていないディレクトリ構成を推測できないため、プロジェクト独自のゲートを含め、呼び出す箇所では必ず両方のルートを明示してください。
• すべてのリポジトリ内ローカルのスキルを --local（またはプロジェクト独自のコピー内のセット）で必ず登録してください。ソースのないインストール済みスキルをそのまま通すと、削除されたソースと意図的なスキルを区別できなくなります。
• オフラインで決定論的に実行でき、ゲートに適しているため、プロジェクトのマージゲートに組み込むことを推奨します。

検証

スキルの変更はドキュメントの変更です。形式、リント、相対リンクの整合性に加え、プロジェクトに用意されている場合はスキル構造バリデーターも通過する必要があります。

ガイドライン：

• スキルを変更した後（直接編集した場合も、再インストールした場合も）は必ずプロジェクトのドキュメントチェック（形式、リント、相対リンクの整合性）を実行し、コミット前にすべての失敗を修正してください。
• スキルのファイルやリンクを移動した場合は必ず相対リンクチェックを実行してください。インストール済みコピー内のリンク切れも、ソースと同じチェックで検出されます。
• スキルや参照ファイルの追加、名前変更、移動、削除を行った後は必ず、変更がディスカバリーメタデータと親ルーティングに反映されていることを確認してください。これらのルールはスキル作成規約に従ってください。階層の移動によって、ディスカバリーとルーティングが依存するパスが変わるためです。
• スキル作成規約に構造バリデーターが含まれている場合は、変更したスキルを検証することを推奨します。
• 再インストールしたコピーとソースの差分を確認し（git diff --stat）、再インストールで変更されたファイルが想定どおりであることを確かめることを推奨します。