agent skillを複数リポジトリで共有する方法

リポジトリ間で agent skill を共有する方法

ファイルのコピーをやめ、依存関係として管理すると、リポジトリ間で agent skill を共有できます。skills 用のリポジトリを1つに集約してタグを付け、各プロジェクトでタグを固定します。次に、各 skill にスモークテストを追加し、依存関係の更新と同じ手順で更新内容をレビューします。

必要なのは、共有する信頼できる唯一の情報源、リポジトリごとに固定したバージョン、skill ごとのスモークテスト、レビュー手順の4つです。以下では、それぞれが必要な理由、2026年に提供されるツールでの対応、外部サービスを使わずにセルフホストの git リモートで全体を構築する方法を説明します。

agent skill は、SKILL.md ファイルと、必要なスクリプトおよび参照ファイルを格納したフォルダーです。この単位について初めて学ぶ場合は、先に agent skill とは何か、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 spec で使用できるキーは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 repoの誤った指示を修正しても、残りの7個には反映しません。別の誰かがordersにページネーションのルールを追加します。すると、同じskill名でも、agentがどのディレクトリから起動したかによってレビュー結果が異なります。しかも、どの開発者もその違いに気付きません。

この問題は、エラー状態が存在しないため、気付かないまま発生します。skillは文章です。古い指示は、自信に満ちた誤った回答を生成します。これは、対応コストが高い種類の問題です。agentが自分のコピーを他のコピーと比較する仕組みはありません。そのため、唯一の兆候は、2つのrepoで内容が食い違っていることに誰かが気付くことです。

問題 2: バージョンを固定する仕組みがない

チームがスキルを 1 か所で管理していても、一般的な共有方法はコピーです。セットアップスクリプト、オンボーディングドキュメント内の curl 行、またはフォルダーを同期する shell alias を使います。これらはすべて、その時点でブランチの先頭にある内容をインストールします。

そのため、同じアプリケーションの同じ commit を使っている 2 人の開発者でも、異なる指示を実行する可能性があります。同期を実行した日が異なるためです。また、agent の実行に問題が起きた後に重要になる「この処理を生成したスキルのバージョンは何か」という問いにも答えられません。記録された revision がなければ実行を再現できず、バグレポートを有効な調査につなげられません。

問題 3: そのスキルがまだ機能するか誰にも分からない

スキルにはコンパイラーがありません。モデルに向けた指示であるため、ファイルが 1 バイトも変わっていなくても機能しなくなることがあります。モデルをアップグレードすると、長い指示にどの程度忠実に従うかが変わります。スキルが呼び出すコマンドラインツールでフラグの名前が変更されることもあります。参照ファイル内の URL が 404 を返すようになると、エージェントがエラーページを基に処理することもあります。

このような場合でも、明確な失敗は発生しません。エージェントは回答を返し続けます。ただし、その回答は先月より悪くなっています。これを pull request 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 回記録されます。このプロジェクトの未解決のリクエスト（issue 283）では、ロックファイルに記録されたすべてのスキルを再インストールする skills install コマンドが求められています。これにより、2 台目のマシンでも同じセットを構成できます。このリクエストは、現在の状況を示しています。ロックファイルという考え方は定着しています。プロジェクト単位で管理する部分は、まだ開発中です。

仕様とテスト。 SkillSpec は別の方向から取り組みます。SKILL.md を信頼する文章ではなく、検証対象の契約として扱い、スキルを「実行可能、テスト可能、証明可能」にすることを目標に掲げています。skillspec doctor <path> は、エージェントが処理の流れを失いそうな箇所を報告します。skillspec boundary map <path> は、スキルが到達できる対象を報告し、skillspec boundary assess <path> はその結果をリスク順に評価します。これは MIT または Apache 2.0 のデュアルライセンスで提供される Rust crate で、2026 年 7 月 29 日時点のバージョンは 0.2.2 です。最新バージョンではなく、指定されたバージョンをインストールしてください。

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked は、crate の公開時に使用された依存関係のバージョンでビルドします。そのため、ビルド中に依存関係のバージョンが変わりません。skillspec --version の出力は 0.2.2 になるはずです。異なる番号が表示される場合は、PATH 内にある古いバイナリが優先されています。

ベンダーの実践。 Google は、google/skills のスキルを エージェントスキルの構築、テスト、スケーリング方法 に関する記事で説明しています。規模を除けば、その仕組みは通常の継続的インテグレーション（CI）です。すべてのスキルは、マージ前に frontmatter のメタデータ、行数、ディレクトリ構成、命名を対象とする linter を通過します。リンクチェッカーは、404 を返す URL が 1 つでもあるとビルドを失敗させます。これにより、エージェントが作成した、もっともらしいリンクを検出できます。作成者は、スキルとともに評価用のプロンプトセットと採点基準を提供する必要があります。スケジュールされた評価ジョブは、リグレッションを検出するため、ライブラリ全体を対象に毎週実行されます。また、すべてのスキルには担当者が割り当てられ、品質が低下した場合に修正することが求められます。

3 つの回答に共通するパターン

これらのいずれかを選ぶ必要はありません。3 つの回答の下には 1 つの構造があり、plain git だけでその全体を扱えます。

1. 信頼できる唯一の情報源。skill には 1 つだけの本体があり、各リポジトリはコピーを保持せず、その本体を参照します。
2. リポジトリごとに固定したバージョン。各プロジェクトは使用する正確な revision を記録します。そのため、アップグレードは作成者と日付を持つ、そのプロジェクト内の commit になります。
3. skill ごとのスモークテスト。skill が約束した結果を引き続き生成できることを示す、実行可能なチェックを 1 つ用意します。
4. レビューの経路。共有 skill への変更はレビューを経由し、各利用側は取り込む前に差分を確認できます。

これが dependency の構造です。skill は tooling が整備されるよりも早く共有 artifact になりました。そのため、すでに信頼している tooling を使うのが最も安全です。

小規模チーム向けの self-hosted git remote の構成

1 つのリポジトリにスキルを集約します。ほかのファイルは置かないため、その履歴が手順の変更履歴になります。

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

リリースにはタグを使用します。メッセージと日付を保持できるため、annotated tag を使用してください。メッセージには、利用者が更新を適用する理由を記載します。

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 は、別のリポジトリの特定のコミットをリポジトリ内に記録します。この記録が pin です。各利用プロジェクトで、次のように設定します。

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 内に保持されます。

pin を確認します。

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 が空のままとなり、エラーも表示されないためです。

アップグレードは意図的に行います。これが submodule を使う目的です。

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 plugin system を使うと配布を自動化できます。self-hosted remote にも対応します。skills repository の .claude-plugin/marketplace.json に catalog を配置します。

{
  "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つの source が使われています。これらを混同するのがよくある誤りです。marketplace source は、catalog 自体を取得する場所を指定します。branch または tag には ref を指定できますが、sha は指定できません。catalog 内の plugin source では、両方を指定できます。両方を設定した場合は、sha が実際の固定値になります。したがって、exact-commit pin は catalog entry に記述します。

各 consuming repository では、コミット対象の .claude/settings.json に marketplace を指定します。

{
  "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
  }
}

project folder を信頼するチームメイトには、marketplace のインストールが提示されます。wiki ページで手順を案内しなくても、そのユーザーに plugin が有効になります。skills は /team-skills:api-review として扱われます。plugin skill は plugin name によって名前空間が分けられるため、同じ名前の project skill と衝突しません。新しい tag を push した後、利用側では /plugin marketplace update acme-agents で更新します。その後、インストール概要で求められた場合は /reload-plugins を実行します。

1 つの skill のスモークテストを作成する

スモークテストは、既知の障害を含む fixture に対して agent をスクリプトで実行し、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/null

fixtures/orders-api.md は、意図的な障害を 1 つだけ含む短いファイルです。アサーションでは、skill がその障害を指摘することを確認します。jq -e は、フィルターの結果に null が含まれると、ゼロ以外の終了ステータスで終了します。そのため、埋め込んだ障害を検出できなくなった skill はスクリプトで失敗します。claude 自体も実行に失敗するとゼロ以外の終了ステータスで終了し、set -euo pipefail によってどちらの失敗もテスト失敗になります。

モデルは実行ごとに回答の表現を変えるため、文全体をアサーションの対象にしないでください。skill が出力する想定の識別子、または指定した schema のフィールドを検証します。実行コストを抑えるため、fixture も小さく保ちます。

CI では --bare を追加します。これがない場合、claude -p は対話セッションと同じコンテキストを読み込みます。これには hook、plugin、実行マシン上の CLAUDE.md も含まれるため、チームメンバー個人の設定によって結果が変わる可能性があります。bare mode では自動検出をすべてスキップするため、テスト対象の skill も読み込まれません。その skill だけを明示的に読み込んでください。bare mode では subscription login も読み込まれないため、先に環境変数で 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 が報告され、読み込まれなかった plugin については plugin_errors 配列が含まれます。plugin_errors が空でない場合は CI ジョブを失敗させます。これにより、存在しなくなった revision を指す pin を検出できます。これを検出できないと、agent が組織のルールを静かに無視しているように見えてしまいます。

共有スキルは実行可能な命令です

この命令が文字どおり実行されることには、2 つの機能が関係します。ファイルが別のチームから提供された場合は、どちらも重要です。

1 つ目は、モデルが何も読み取る前に SKILL.md がシェルコマンドを実行できることです。本文に次のような行がある場合、これは前処理として扱われます。

- Current branch: !`git rev-parse --abbrev-ref HEAD`

コマンドはスキルを読み込むマシン上で実行され、その出力がモデルに渡されるテキスト内のプレースホルダーを置き換えます。3 個のバッククォートに続けて ! を記述して開始したフェンス付きブロックも、同じ方法で複数のコマンドを実行します。実行時に誰かが承認することはありません。共有スキルを読むことは、コマンド置換の内容を読むことでもあります。

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 を実行したり設定ファイルを開いたりするスキルは、そこで見つかった内容をモデルのコンテキストに取り込みます。これは 実行するエージェントから秘密情報を除外する で扱った問題です。ページを取得したりクエリを実行したりするスキルでは、この露出が外部へ向かいます。取得したテキストは、ユーザーが記述した命令とまったく同じようにコンテキストへ入るためです。これは、Web 検索用に自分の SearXNG インスタンスをエージェントへ指定する 前に確認しておくべき境界です。

バージョン更新時に確認する内容

• すべての SKILL.md 本文の差分。これはエージェントが従う指示だからです。
• すべてのコマンド置換。skill の読み込み時にローカルマシンで実行されるためです。
• allowed-tools の変更。プロンプトなしでツールを許可する行だからです。
• タグに紐づくテスト実行結果。共有リポジトリが CI で独自のスモークテストを実行する場合、固定するタグには成功した実行結果が付いている必要があります。

レビュアーが 10 分で差分全体を読めない場合、その skill は大きくなりすぎています。分割してください。同じことは、エージェントが読むリポジトリのドキュメントにも当てはまります。永続的なルールは AGENTS.md と HUMAN.md の分割 で説明されているファイルに置き、アーキテクチャ上の判断理由は エージェント向けに作成した DESIGN.md に記載してください。skill は限定的な手順に絞ります。

モデルまたはツールの変更によって skill が機能しなくなる場合

skill を編集していなくても、その内部の複数の要素が変わることがあります。モデルのアップグレードによって長い指示への追従性が変わると、9 番目の手順まで到達することを前提にした skill は、そこまで進まなくなる可能性があります。コマンドラインツールがフラグ名を変更すると、agent は古いフラグを実行し、エラーを読み取って独自に対応します。参照先の URL が 404 を返し始めることもあります。agent harness が skill の選択方法を変更すると、以前はマッチに成功していた description が選ばれなくなる場合もあります。このように手順が途中で終了するようになった場合、バージョンを上げても解決しません。最後の手順まで強制的に進める構造を指示に組み込む必要があります。unlazy skill とその Depth Tree 手法は、この考え方に基づいています。

この構成では、smoke test が重要な役割を担います。各 skill のテストは push 時だけでなく、スケジュールでも実行してください。Google がライブラリ全体を対象に評価ジョブを毎週実行しているのも、このためです。skill が 10 個あるチームであれば、小規模な VPS 上の週次 cron job で十分です。開発者が問題に気付く前に、破損を知る唯一の方法です。

移植性も役立ちます。Agent Skills spec では frontmatter のキーを 6 個に限定しているため、その spec に従って作成した skill は、作成時に使用したツール以外でも読み込めます。一方、harness 固有のキーを追加するたびに、特定のベンダーに依存することになります。モデルを変更しても動作する skill の作成には、独自の技術が必要です。詳細は 任意のモデルで skill を動作させる方法で説明しています。

FAQ

1 つのエージェントスキルを複数のリポジトリで共有するにはどうすればよいですか？

スキルを専用の git リポジトリに配置し、そこでリリースにタグを付けます。各利用プロジェクトでは、ファイルをコピーせずにタグを参照します。利用できる仕組みは 2 つあります。git submodule は正確な commit を記録し、.claude/skills/<name> から submodule への symlink によって、通常のプロジェクトスキルとして読み込めます。plugin marketplace では /plugin を使って同じことを行い、利用側リポジトリの .claude/settings.json で pin を宣言します。どちらもバージョンを git の履歴に記録するため、特定のエージェント実行でどの指示が使われたかを確認できます。

エージェントスキルを特定のバージョンに固定できますか？

SKILL.md の内部からは固定できません。この frontmatter には version key がないためです。pin はファイルを取り囲む層で指定する必要があります。git submodule は仕組み上、正確な commit に固定されます。Claude Code plugin marketplace では、plugin source がブランチまたはタグ用の ref と、正確な commit 用の sha を受け付けます。両方がある場合は sha が優先されます。marketplace source 自体が受け付けるのは ref だけです。タグは確認後に移動される可能性があるため、commit による pin を推奨します。

スキルの smoke test では何を検証すべきですか？

安定した値を検証します。既知の不具合を含む fixture に対してスキルを非対話的に実行し、スキルが報告するはずのルール ID など、特定の識別子が出力に含まれることを確認します。--output-format json と --json-schema で構造化出力を要求すると検証を厳密にでき、jq -e によって値がない場合にスクリプトを失敗させられます。完全な文章は検証しないでください。モデルは実行ごとに回答を言い換えるためです。

他チームのリポジトリから共有スキルをインストールしても安全ですか？

実行可能な指示であるため、コード依存関係として扱います。SKILL.md は、! の command substitution 形式によって、読み込み時に shell command を実行できます。また、frontmatter の allowed-tools field は、確認なしで使用を許可する tool を事前承認できます。更新のたびに diff を確認し、ブランチではなく正確な commit に固定してください。自チームが管理する source を優先します。管理対象マシンでは、settings の "disableSkillShellExecution": true により command substitution の実行を完全に停止できます。

Claude Code 以外のエージェントでも共有スキルは動作しますか？

使用する frontmatter によって異なります。Agent Skills spec は 6 つの key、name、description、license、compatibility、metadata、allowed-tools を定義しています。これらだけを使うスキルは、spec を実装するツール間で読み込めます。また、変更なしで Claude Code でも読み込めます。Harness 固有の key や spec 外の body 機能は、他の環境では無視または拒否されます。そのため、広く共有するスキルには含めないでください。