著者 リポジトリ間でエージェントスキルを共有する方法
8つのリポジトリにスキルをコピーすると内容が分岐します。共有用の正本を1つに集約し、各プロジェクトでタグ付きバージョンを固定してレビューする方法を解説します。
リポジトリ間でエージェントスキルを共有する方法
リポジトリ間でエージェントスキルを共有するには、ファイルのコピーをやめ、そのファイルを依存関係として扱います。スキル用のリポジトリを1つに集約してタグを付け、各プロジェクトではタグを固定します。次に、各スキルにスモークテストを追加し、依存関係の更新と同じ方法で更新内容を毎回レビューします。
必要なのは、共有する唯一の正本、リポジトリごとの固定バージョン、スキルごとのスモークテスト、レビュー手順の4つです。以下では、それぞれが必要な理由、2026年に提供されるツールがこの運用をどう扱うか、外部サービスを使わずにセルフホストのgitリモートで全体を構築する方法を説明します。
エージェントスキルは、SKILL.mdファイルと、それが必要とするスクリプトおよび参照ファイルを格納したフォルダーです。この単位の概念が初めての場合は、先にエージェントスキルとは何か、SKILL.mdがどのように動作するかを読んでください。このページでは、その単位を取り巻くサプライチェーンについて説明します。
スキルの配置場所と、共有が難しい理由
Claude Code は 3 か所からスキルを読み込みます。各パスは スキルのドキュメント に記載されています。
~/.claude/skills/<skill-name>/SKILL.mdは個人用です。自分のすべてのプロジェクトで読み込まれますが、他のユーザーのプロジェクトでは読み込まれません。.claude/skills/<skill-name>/SKILL.mdはプロジェクトレベルです。そのリポジトリをチェックアウトしたユーザー全員の環境で読み込まれます。<plugin>/skills/<skill-name>/SKILL.mdはプラグインに含まれます。そのプラグインが有効な環境で読み込まれます。
チームで使う場合に有用なのは 2 つ目の方法です。コミットされるため、リポジトリをクローンした全員が利用できます。ただし、ここから問題が始まります。.claude/skills/ にあるスキルは、1 つのリポジトリに属します。リポジトリが 8 つある場合、スキルも 8 つコピーすることになります。
frontmatter も役に立ちません。Agent Skills の仕様で使用できるキーは 6 つです。別のキーを使うと、その配布パスを検証する仕組みが次の一覧を表示します。
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameここで欠けているものに注目してください。version キーはありません。ファイル内には、どのコピーが新しいかを記録する情報がありません。スキルはパッケージではなくドキュメントなので、これは合理的です。ただし、バージョン管理はファイルの周辺にある仕組みで行う必要があり、その仕組みは自分で用意しなければなりません。
問題 1: 気付かないうちに分岐する 8 つのコピー
初日はコピー＆ペーストで問題ありません。60 日目には破綻します。誰かが payments リポジトリの誤った手順を修正しても、他の 7 つは更新しません。別の誰かが orders にページネーションのルールを追加します。その結果、同じスキル名でも、エージェントがどのディレクトリから起動したかによってレビュー内容が異なります。そして、どちらの開発者もそのことに気付きません。
この問題が気付かれにくいのは、エラー状態が存在しないためです。スキルは文章です。古い手順があると、エージェントは自信を持って誤った回答を返します。これは、発見が遅れるほどコストが大きくなる種類の問題です。エージェントは、自分のコピーと他のコピーを比較しません。そのため、唯一の兆候は、2 つのリポジトリの内容が一致しないことに誰かが気付くことです。
バージョンを固定していない
チームがスキルを 1 か所で管理していても、通常の共有方法はコピーです。セットアップスクリプト、オンボーディングドキュメント内の curl 行、またはフォルダーを同期する shell alias を使います。これらはすべて、その時点でブランチの先頭にある内容をインストールします。
そのため、同じアプリケーションの同じコミットを使っている 2 人の開発者でも、異なる指示を実行することがあります。同期を実行した日が異なるためです。また、エージェントの実行に問題が発生した後に重要になる「どのバージョンのスキルがこれを生成したのか」という質問にも答えられません。記録されたリビジョンがなければ実行を再現できず、バグ報告を具体的な対応につなげられません。
問題 3: スキルがまだ機能するか誰にも分からない
スキルにはコンパイラーがありません。モデルを対象とした指示であるため、ファイルがバイト単位で完全に同一でも、機能しなくなることがあります。モデルをアップグレードすると、長い指示にどれだけ忠実に従うかが変わります。スキルが呼び出すコマンドラインツールで、フラグ名が変更されることもあります。参照ファイル内の URL が 404 を返すようになり、エージェントがエラーページを基に動作することもあります。
このような場合でも、通常は明確なエラーは発生しません。エージェントは引き続き回答します。ただし、その回答は先月より悪くなっています。プルリクエストを 1 件ずつ確認するだけでは、この変化に気付くのは困難です。
2026 年に提供されるツールが解決する問題
現在、いくつかの回答が出そろいつつあります。ただし、バージョンをどこで管理するかについては意見が分かれています。
ロックファイル。 Vercel Labs の skills コマンドラインツール（vercel-labs/skills、MIT ライセンス、2026 年 8 月 5 日時点で v1.5.22）は、git リポジトリからスキルをエージェントが想定するディレクトリへインストールします。70 を超えるエージェントのディレクトリ構成にも対応しています。npx skills add <repo> はインストール、npx skills update はアップグレード、npx skills list はインストール済みの内容の表示に使用します。インストール済みの内容は、リポジトリごとではなくユーザーごとに 1 つの記録として保持されます。このプロジェクトでは、ロックファイルで追跡しているすべてのスキルを再インストールし、2 台目のマシンでも同じ構成にする skills install コマンドを求めるリクエスト（issue 283）が公開されています。このリクエストは現状を示すものです。ロックファイルという考え方は定着しています。一方、プロジェクト単位で管理する部分はまだ開発中です。
仕様とテスト。 SkillSpec は別の方向から取り組みます。SKILL.md を信頼する文章ではなく、検証する契約として扱います。目標は、スキルを「追跡可能、テスト可能、証明可能」にすることです。skillspec doctor <path> は、エージェントが処理の流れを失いそうな箇所を報告します。skillspec boundary map <path> は、スキルがアクセス可能な対象を報告し、skillspec boundary assess <path> はその結果をリスク順に分類します。これは MIT または Apache 2.0 のデュアルライセンスで提供される Rust クレートで、2026 年 7 月 29 日時点のバージョンは 0.2.2 です。最新バージョンではなく、指定されたバージョンをインストールしてください。
cargo install skillspec --version 0.2.2 --locked
skillspec --version--locked は、クレートの公開時に使用された依存関係のバージョンでビルドします。そのため、ビルド時に依存関係のバージョンが意図せず変わりません。skillspec --version は 0.2.2 を出力するはずです。異なる番号が表示される場合は、PATH 内のより古いバイナリが優先されています。
ベンダーの実践。 Google は、エージェントスキルの構築、テスト、スケーリング方法に関する記事で、google/skills のスキルをどのように構築しているかを説明しています。規模の部分を除けば、仕組みは一般的な継続的インテグレーション（CI）です。各スキルは、マージ前に frontmatter のメタデータ、行数、ディレクトリ構成、命名を対象とするリンターを通過します。リンクチェッカーは、404 を返す URL が 1 つでもあるとビルドを失敗させます。これにより、エージェントがもっともらしいリンクを生成した場合も検出できます。作成者は、スキルと併せて評価用のプロンプトスイートと採点基準を用意する必要があります。スケジュール実行される評価ジョブは、リグレッションを検出するため、ライブラリ全体を対象に毎週実行されます。また、各スキルには担当者が割り当てられており、品質が低下した場合はその担当者が修正します。
3 つの回答に共通するパターン
この 3 つの方法から 1 つを選ぶ必要はありません。これらの下には 1 つの構造があり、素の git ですべてを実現できます。
- 信頼できる唯一の情報源。skill には 1 つだけの保存場所があり、各リポジトリはコピーを保持せず、その場所を参照します。
- リポジトリごとに固定されたバージョン。各プロジェクトは使用する正確なリビジョンを記録します。そのため、アップグレードは作成者と日付を持つ、そのプロジェクト内のコミットになります。
- skill ごとのスモークテスト。skill が約束した結果を引き続き生成できることを確認する、1 つの実行可能なチェックを用意します。
- レビューの経路。共有 skill への変更はレビューを経由し、すべての利用側が取り込む前に差分を確認できます。
これが依存関係の構造です。skill は、それを支えるツールが整うよりも早く共有アーティファクトになりました。そのため、すでに信頼しているツールを使うのが最も安全です。
小規模チーム向けの自己ホスト Git リモート構成
1 つのリポジトリにスキルを集約します。それ以外の内容は置かないため、履歴を手順の変更履歴として利用できます。
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdリリースにはタグを使用します。メッセージと日付を保持できるため、注釈付きタグを使用してください。メッセージには、利用者が更新を望む理由を記述します。
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0リモートが Gitea、Forgejo、GitLab、または自分の VPS 上で SSH 経由でアクセスする bare repository のいずれであっても、以下の内容は変わりません。ここで使用するのは git と symlink だけです。
git submodule によるバージョン固定
submodule は、別のリポジトリの特定のコミットを、現在のリポジトリ内に記録します。この記録が固定先です。各利用プロジェクトで、次のように設定します。
git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"この構成を成立させるのはシンボリックリンクです。プロジェクトレベルの skill エントリは、ディスク上の別の場所にあるディレクトリへのシンボリックリンクにできます。Claude Code はそのリンクをたどり、リンク先から SKILL.md を読み取ります。そのため、skill は通常のプロジェクト skill として読み込まれます。一方、実体のファイルは、選択したコミットの submodule 内に置かれます。
固定先を確認します。
git submodule status正常な行は、先頭にスペース、その後にコミット、パス、最も近いタグの順で表示されます。
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)先頭の - は、submodule が初期化されていないことを示します。そのため .claude/skills/api-review は何も指さず、skill はエラーを表示せずに読み込まれません。git submodule update --init で修正します。先頭の + は、チェックアウト済みのコミットが記録されたコミットと異なることを示します。その開発者だけが、他の開発者にはない指示で実行している状態です。新しく clone した場合は git clone --recurse-submodules が必要です。この手順は README に記載してください。通常の clone では vendor/agent-skills が空のままになり、エラーも表示されないためです。
アップグレードは意図的に行います。これがバージョンを固定する目的です。
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"diff の行がレビューの基準になります。すべての利用リポジトリに適用される同じ変更を確認でき、pull request に含めることもできます。
プラグインマーケットプレイスで固定する方法
すべての開発者に submodule を覚えてもらう必要がない場合は、Claude Code のプラグインシステムで配布できます。自己ホスト型のリモートも利用できます。skills リポジトリの .claude-plugin/marketplace.json にカタログを配置します。
{
"name": "acme-agents",
"owner": { "name": "Platform team", "email": "platform@example.com" },
"plugins": [
{
"name": "team-skills",
"description": "Shared review and release skills",
"version": "1.4.0",
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0",
"sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
}
}
]
}ここでは、異なる 2 つのソースを使用しています。この 2 つを混同することが、よくある間違いです。マーケットプレイスソースは、カタログ自体の取得元を示します。ブランチまたはタグには ref を指定できますが、sha は指定できません。カタログ内のプラグインソースでは、両方を指定できます。両方を設定した場合は、sha が実際の固定値になります。したがって、正確なコミットへの固定はカタログエントリに記述します。
各利用リポジトリでは、コミット済みの .claude/settings.json でマーケットプレイスを宣言します。
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}プロジェクトフォルダーを信頼するチームメイトには、マーケットプレイスのインストールを促すメッセージが表示されます。wiki ページで手順を案内しなくても、プラグインが有効になります。プラグインのスキルはプラグイン名で名前空間が分けられるため、/team-skills:api-review に応答します。同名のプロジェクトスキルとも衝突しません。新しいタグを push した後、利用者は /plugin marketplace update acme-agents で更新します。インストール概要で求められた場合は、その後に /reload-plugins を実行します。
1 つの skill のスモークテストを作成する
スモークテストは、既知の障害を含む fixture に対してエージェントをスクリプトで実行し、1 つのアサーションを検証するものです。Claude Code は -p により非対話的に実行できます。ユーザーが呼び出す skill もこの方法で動作するため、プロンプト文字列に /skill-name を含めると、実行開始前に展開されます。
#!/usr/bin/env bash
set -euo pipefail
claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--allowedTools "Read" \
--output-format json \
--json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
| jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/nullfixtures/orders-api.md は、意図的な障害を 1 つだけ含む短いファイルです。skill がその障害を指摘することをアサーションで検証します。jq -e は、フィルター結果が null の場合に非ゼロで終了します。そのため、埋め込んだ障害を検出できなくなった skill はスクリプトに失敗します。claude 自体も実行に失敗すると非ゼロで終了し、set -euo pipefail によってどちらの失敗もテスト失敗になります。
モデルは実行ごとに回答の表現を変えるため、文全体をアサーションで検証しないでください。skill が出力すべき識別子、または指定したスキーマのフィールドを検証します。実行コストを抑えるため、fixture は小さくしてください。
CI では --bare を追加します。これがない場合、claude -p は対話セッションと同じコンテキストを読み込みます。そこには、実行元マシンのフック、プラグイン、CLAUDE.md も含まれます。そのため、チームメンバーの個人設定によって結果が変わる可能性があります。bare mode では自動検出をすべてスキップします。そのため、テスト対象の skill もスキップされるので、その skill だけを明示的に読み込んでください。bare mode ではサブスクリプションのログイン情報も読み込まれません。先に環境変数で ANTHROPIC_API_KEY を設定します。
claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--plugin-dir vendor/agent-skills \
--allowedTools "Read" \
--output-format json--output-format stream-json を指定すると、実行の最初のイベントで読み込まれたプラグインが報告され、読み込まれなかったプラグインについては plugin_errors 配列が含まれます。plugin_errors が空でない場合は CI ジョブを失敗させてください。これにより、存在しなくなったリビジョンを指す pin を検出できます。これを検出できないと、エージェントが組織のルールを静かに無視しているように見えます。
共有スキルは実行可能な命令です
この挙動を文字どおりにする機能が2つあります。ファイルが別のチームから提供された場合は、どちらも重要です。
1つ目は、SKILL.md がモデルによる読み取り前に shell コマンドを実行できることです。本文に次のような行がある場合、これは前処理として扱われます。
- Current branch: !`git rev-parse --abbrev-ref HEAD`コマンドはスキルを読み込むマシン上で実行され、その出力がモデルに渡されるテキスト内のプレースホルダーを置き換えます。3つのバッククォートに続けて ! を記述して開いた fenced block も、同じ方法で複数のコマンドを実行します。実行時にこれらを承認する人はいません。共有スキルを読むことは、コマンド置換も読むことを意味します。
2つ目は、frontmatter でツールを事前承認できることです。allowed-tools は、スキルを呼び出したターン中、一覧にあるツールを権限確認なしで許可します。プロジェクトスキルの場合、この許可は、対象フォルダーに対する workspace trust ダイアログを誰かが承認すると有効になります。Claude Code のドキュメントは、この結果を明確に説明しています。リポジトリを信頼する前にプロジェクトスキルを確認してください。スキルによって広範なツールアクセスが付与される可能性があるためです。
そのため、スキルの更新は依存関係の更新と同じように扱ってください。仕組み上可能な場合は、正確な commit に固定してください。tag は変更でき、branch は定義上移動するためです。ロックダウンされたマシンでは、設定の "disableSkillShellExecution": true により、すべてのコマンド置換が実行されず、文字列 [shell command execution disabled by policy] に置き換えられます。これを managed settings で適用した場合、ユーザーは上書きできません。Bundled skill と managed skill は、この設定の対象外です。
同じ注意は、スキルが読み取る内容にも必要です。env を実行したり設定ファイルを開いたりするスキルは、見つかった内容をモデルのコンテキストに取り込みます。これは 実行する agent から Secret を除外する で扱っている問題です。ページを取得したり query を実行したりするスキルでは、同じ露出が外部に向かいます。取得したテキストは、作成した命令とまったく同じようにコンテキストへ入るためです。これは、Web 検索用に独自の SearXNG instance を agent に指定する 前に確認すべき境界です。
バージョン更新時に確認する内容
- すべての
SKILL.md本文の差分。本文はエージェントが従う指示だからです。 - すべてのコマンド置換。スキルの読み込み時にマシン上で実行されるためです。
allowed-toolsの変更。プロンプトなしでツールを使用できる権限を付与する行だからです。- タグの背後にあるテスト実行結果。共有リポジトリが CI で独自のスモークテストを実行する場合、固定するタグには成功した実行結果が紐付いている必要があります。
10 分で差分全体を確認できない場合、そのスキルは大きくなりすぎています。分割してください。同じことは、エージェントが読むリポジトリのドキュメントにも当てはまります。永続的なルールは AGENTS.md と HUMAN.md の分割 で説明されているファイルに保持し、アーキテクチャ上の判断理由は エージェント向けに記述した DESIGN.md にまとめ、スキルは限定的な手順にしてください。
モデルやツールの変更でスキルが壊れる場合
スキルを誰も編集していなくても、その下で複数の要素が変化します。モデルのアップグレードによって長い指示への追従性が変わるため、モデルが step nine まで到達することを前提にしたスキルは、そこまで実行されなくなる可能性があります。コマンドラインツールがフラグ名を変更すると、エージェントは古いフラグを実行し、エラーを読み取って独自に処理します。参照先の URL が 404 を返し始めることもあります。エージェントハーネスがスキルの選択方法を変更すると、以前はマッチに勝っていた description が選択されなくなる場合もあります。
このため、この構成ではスモークテストが重要です。各スキルのテストを push 時だけでなく、スケジュールでも実行します。Google がライブラリ全体に対して毎週評価ジョブを実行しているのも、このためです。スキルが 10 個あるチームであれば、小規模な VPS 上の weekly cron job で十分です。開発者が気付く前に障害を知るには、これが唯一の方法です。
移植性も役立ちます。Agent Skills spec は frontmatter を 6 個のキーに限定しているため、その仕様に従って作成したスキルは、作成時に使用したツール以外のツールでも読み込めます。一方、ハーネス固有のキーを追加するたびに、特定のベンダーに依存することになります。モデルを交換しても動作するスキルの作成には、独自の技術が必要です。詳細は 任意のモデルでスキルを動作させる を参照してください。
FAQ
複数のリポジトリで 1 つのエージェントスキルを共有するにはどうすればよいですか？
スキルを専用の git リポジトリに配置し、そこでリリースにタグを付けます。各利用プロジェクトでは、ファイルをコピーせずにタグを参照します。方法は 2 つあります。git submodule は正確なコミットを記録します。.claude/skills/<name> から submodule へのシンボリックリンクを作成すると、通常のプロジェクトスキルとして読み込まれます。plugin marketplace でも同じことができます。/plugin を介して参照し、利用側リポジトリの .claude/settings.json で固定します。どちらもバージョンを git の履歴に記録するため、特定のエージェント実行でどの指示が使われたかを確認できます。
エージェントスキルを特定のバージョンに固定できますか？
SKILL.md の内部からはできません。この frontmatter には version キーがないためです。固定情報はファイルを取り囲むレイヤーで指定する必要があります。git submodule は仕様上、正確なコミットに固定します。Claude Code plugin marketplace では、プラグインソースの ref でブランチまたはタグを指定し、sha で正確なコミットを指定できます。両方がある場合は sha が優先されます。marketplace ソース自体で受け付けるのは ref だけです。タグはレビュー後に移動される可能性があるため、コミットによる固定を推奨します。
スキルのスモークテストでは何を検証すべきですか？
安定した値を検証します。既知の障害を含む fixture に対してスキルを非対話的に実行し、出力に特定の識別子が現れることを確認します。たとえば、スキルが報告するルール ID を検証します。--output-format json と --json-schema で構造化出力を要求すると検証を厳密にでき、jq -e によって値がない場合にスクリプトを失敗させられます。文全体を検証してはいけません。モデルは実行ごとに回答の表現を変えるためです。
別チームのリポジトリから共有スキルをインストールしても安全ですか？
実行可能な指示であるため、コード依存関係として扱います。SKILL.md は ! のコマンド置換形式を使い、読み込み時に shell コマンドを実行できます。また、frontmatter の allowed-tools フィールドは、プロンプトを表示せずにツールを事前承認できます。更新のたびに差分を確認し、ブランチではなく正確なコミットに固定してください。自チームが管理するソースを優先します。管理対象のマシンでは、設定の "disableSkillShellExecution": true によりコマンド置換の実行を完全に停止できます。
共有スキルは Claude Code 以外のエージェントでも動作しますか？
使用する frontmatter によって異なります。Agent Skills 仕様では、6 つのキーとして name、description、license、compatibility、metadata、allowed-tools を定義しています。これらだけを使用するスキルは、仕様を実装する各種ツールで読み込めます。また、Claude Code でも変更なしで読み込めます。ハーネス固有のキーや仕様外の本文機能は、他の環境では無視されるか拒否されます。そのため、広く共有するスキルには含めないでください。