グラレコ

はじめに

Agent Plugins は、AI エージェントを拡張する部品を1つのディレクトリにまとめて、複数のクライアント間で持ち運べるようにする仕様です。バージョン 1.0.0 が 2026年8月6日に公開されました。

対象は2種類だけです。Agent Skills（SKILL.md で書かれた再利用可能な手順書）と、MCP サーバー（ツールやデータへの接続）。この2つをフォルダに置いて plugin.json を1枚添えれば、VS Code でも Cursor でも GitHub Copilot でも ChatGPT でも Kiro でも、同じものが読み込めます。

提案したのは Vercel で、そこに AWS、Anysphere（Cursor）、GitHub、Microsoft、OpenAI が加わって 1.0.0 に仕上げました。Technical Steering Committee には Amazon・Cursor・Microsoft・OpenAI・Vercel のコアメンテナが入っています。

この記事で扱うのは次の内容です。

📦 なぜ「同じ部品を毎回詰め直す」ことになっていたのか
🗂️ ディレクトリ構造とマニフェスト plugin.json の全フィールド
🧠 skills/ に置く Agent Skills の探索ルール
🔌 mcp.json の3つのトランスポートと、${PLUGIN_ROOT} / ${PLUGIN_DATA} の展開規則
🏷️ 逆ドメイン名前空間によるクライアント独自拡張
🧯 「どこで失敗したら、どこまで壊れるか」の失敗境界
✅ 対応クライアント9種と、それぞれのサポート範囲
🚧 v1 にあえて入れなかったもの（権限モデル・署名・シークレット）
🤝 Claude Code の独自形式との関係

⚠️ 本記事は 2026年8月19日時点の情報です。 仕様 1.0.0 のステータスは Published ですが、公式サイトの一部ページには Working Draft の表記が残っています。正典は spec リポジトリの spec/1.0.0.md です。対応クライアントの一覧も今後増えていきます。

📦 何が問題だったのか：同じ部品を、クライアントの数だけ詰め直す

AI エージェントのクライアントは、それぞれ独自のプラグイン形式を持つようになりました。困るのは、中身が同じでも入れ物が違うことです。

同じ SKILL.md と同じ MCP サーバーを配りたいだけなのに、マニフェストの場所が違い、ファイル名が違い、探索されるディレクトリが違う。だから作者は、クライアントごとに部品を並べ替えるか、まるごと複製することになります。

AWS のブログは、この状況を JavaScript のパッケージマネージャ以前の時代に例えています。

packaging it means adapting for one client, re-writing for another, and repeating that for every tool your team uses.
（あるクライアント向けに調整し、別のクライアント向けに書き直し、チームが使うツールの数だけそれを繰り返す）

Agent Plugins が目指すのは、この繰り返しをなくすことです。公式サイトの表現では "a small interoperability floor"（移植可能な部分だけの、小さな相互運用の床）を定めます。

重要なのは、床だけを定めていることです。配布・インストール・権限・UX・クライアント固有の機能は、あえて標準化していません。各クライアントの裁量のまま残されます。

これが従来の構図です。中身は同じなのに、出口の数だけ変換が要ります。

Agent Plugins を挟むと、変換が1回で済みます。

作者が管理するのは1つのディレクトリだけになります。各クライアントは、この可搬フォーマットを自分のネイティブ設定にマッピングして読み込みます。

🗂️ パッケージの形：zip でもレジストリでもなく、ただのディレクトリ

Agent Plugin は、単一のファイルシステム位置にルートを持つディレクトリです。.zip でも .tar.gz でもなく、レジストリから取ってくるバンドルでもありません。

仕様の Design Decisions には、その理由が書かれています。

ls や cat や git といった普通のツールで中身が見える
開発中にその場で編集できる
特別なツールなしでバージョン管理に載る

標準的なレイアウトはこうなります。

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       │   └── analyze.sh
│       └── references/
│           └── checklist.md
├── mcp.json
├── com.example.client/
│   └── hooks/
├── LICENSE
└── CHANGELOG.md

各要素の役割は次のとおりです。

パス	必須	役割
`plugin.json`	○	プラグインの識別子と、対象とする仕様バージョン
`skills/`		Agent Skills 仕様に沿ったスキル群
`mcp.json`		MCP サーバーの接続設定
`com.example.client/`		クライアント固有のファイル（逆ドメイン名前空間）

skills/ と mcp.json の位置は固定です。plugin.json でこの場所を変えることはできませんし、コンポーネントの設定をマニフェストにインラインで書くこともできません。

これは窮屈に見えるかもしれませんが、意図的な設計です。位置を固定すると、探索の間接参照、別ソースとの優先順位、マニフェストによる設定上書きといった仕組みを、すべてのクライアントが実装する必要がなくなります。

パスの封じ込め

プラグインが供給するファイルは、解決後のパスがプラグインルート内に留まらなければなりません。シンボリックリンクでルートの外を指すようなパッケージは、クライアント側で拒否されます。

設定フィールドのうち「プラグイン相対パス」と定義されたものは、./ で始まる必要があります。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "server": {
      "type": "stdio",
      "command": "./bin/server",
      "cwd": "./data"
    }
  }
}

こちらは有効です。両方 ./ で始まっていて、ルートの中に収まっています。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "server": {
      "type": "stdio",
      "command": "../bin/server",
      "cwd": "data"
    }
  }
}

こちらは無効です。../bin/server はルートの外に出ますし、data はプラグイン相対パスの形をしていません。

📄 マニフェスト：フィールドは10個だけ

plugin.json はプラグインルートに置きます。最小構成は2行です。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "minimal-plugin"
}

これだけで有効なマニフェストになります。書ける項目をすべて使うと、こうなります。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/example/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "extensions": {
    "com.example.client": {
      "setting": true
    }
  }
}

この10個がすべてです。 マニフェストのスキーマはクローズドで、これ以外のトップレベルフィールドは仕様違反になります。

フィールド	必須	型	説明
`$schema`	○	string	対象とする仕様バージョンの正規識別子
`name`	○	string	プラグイン名
`version`		string	バージョン（SemVer 推奨）
`description`		string	短い説明
`author`		object	`name` / `email` / `url` のみ
`homepage`		string	ドキュメントやホームページのURL
`repository`		string	ソースリポジトリのURL
`license`		string	ライセンス識別子（SPDX 推奨）
`keywords`		string[]	検索用のタグ
`extensions`		object	クライアント固有データ（逆ドメイン名前空間）

`name` の制約

name には具体的な文字ルールがあります。

制約	内容
長さ	1〜64文字
文字種	`a-z` `0-9` `-` `.` のみ
先頭と末尾	英数字であること
連続禁止	`--` と `..` は不可

有効な例は my-plugin / hoge.tools / lint3r / a。無効な例は My-Plugin（大文字）、-start（先頭ハイフン）、has--double（連続ハイフン）、too.many..dots（連続ピリオド）です。

ピリオドが使えるので、hoge.tools のような名前空間っぽい命名もできます。

メタデータの検証は緩い

ここは実装者にとって大事な点です。version が SemVer でなくても、homepage が URL の形をしていなくても、license が SPDX 識別子でなくても、author.email がメールアドレスの形でなくても、それだけを理由にマニフェストを拒否してはいけません。型が合っていれば通ります。

一方で author オブジェクトは厳格です。name / email / url 以外のフィールドが入っていると、マニフェスト全体が無効になります。

スキーマは取りに行かない

$schema は「どのバージョンの検証ルールを使うか」を選ぶための識別子であって、URL を取得するためのものではありません。仕様には クライアントはプラグイン読み込み時にスキーマを取得してはならない と明記されています。

オフラインでも動きますし、ネットワーク越しにスキーマが差し替わる心配もありません。ちなみに、仕様本文と機械可読スキーマが食い違った場合は仕様本文が優先します。

🧠 skills/ — 中身は Agent Skills 仕様に丸投げ

Agent Plugins はスキルの形式を再定義しません。SKILL.md の書き方は Agent Skills specification が source of truth です。

Agent Plugins が定めるのは、どこを探すかだけです。

skills/
└── deploy/
    ├── SKILL.md
    ├── scripts/
    │   └── rollback.sh
    ├── references/
    │   └── runbook.md
    ├── assets/
    └── examples/

探索ルールは2行で言えます。

skills/ の直下の子ディレクトリで、SKILL.md が通常ファイルとして存在するものが1スキル
より深い階層を再帰的に探してはいけない

skills/a/b/SKILL.md は見つかりません。1階層だけです。

参考までに、SKILL.md のフロントマターはこうなっています。

---
name: greet
description: Greet the user and offer help.
---

Greet the user and offer help.

必須は name と description の2つで、任意で license / compatibility / metadata / allowed-tools が使えます。name は親ディレクトリ名と一致していなければなりません（上の例なら skills/greet/）。

description は最大1024文字で、「何をするか」だけでなく「いつ使うか」を書くことが推奨されています。エージェントはこの1文でスキルを呼ぶかどうかを判断するので、ここが雑だと呼ばれません。

一番小さいプラグイン

公式の Quick Start に載っている最小構成が、この関係をよく表しています。

hello-plugin/
├── plugin.json
└── skills/
    └── greet/
        └── SKILL.md

plugin.json は2行、SKILL.md はフロントマター2行と本文1行。これで有効なプラグインです。MCP サーバーは要りません。

🔌 mcp.json — 3つのトランスポートを明示する

MCP サーバーの設定は、プラグインルートの mcp.json に置きます。plugin.json にインラインで書くことはできません。

トップレベルは $schema と mcpServers の2つだけで、他のフィールドは許されません。mcpServers が空オブジェクトでも有効です。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "env": {
        "CONFIG": "${PLUGIN_ROOT}/config.json"
      },
      "cwd": "${PLUGIN_ROOT}"
    },
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp",
      "headers": {
        "X-Tenant": "public-tenant"
      }
    },
    "legacy-events": {
      "type": "sse",
      "url": "https://legacy.example.com/sse"
    }
  }
}

各サーバーは type を持ち、3つのバリアントのちょうど1つに一致しなければなりません。他のバリアントのフィールドが混ざっていると、そのエントリは無効です。

type	必須フィールド	任意フィールド	備考
`stdio`	`type` `command`	`args` `env` `cwd`	ローカルプロセスを起動
`streamable-http`	`type` `url`	`headers`	現行のリモート MCP トランスポート
`sse`	`type` `url`	`headers`	非推奨の HTTP+SSE。対応は任意

既存のクライアントは MCP 設定の形がまちまちで、トランスポートの推測方法も違っていました。Agent Plugins が明示的なクローズドユニオンを定義したのはそのためです。type が書いてあるので、最初の接続でどのトランスポートを使うかが曖昧になりません。

なお、接続に失敗したときのフォールバックは仕様の範囲外です。

`command` は1トークン

stdio の command は、シェルコマンド文字列ではなく単一の実行可能トークンです。

ベアな実行ファイル名（プラットフォームの検索規則で解決される）
または ./ で始まるプラグイン相対パス

command にはプレースホルダ展開が適用されません。理由は Design Decisions に書かれていて、「ユーザーが書いたシェルコマンド文字列をクライアントがパースしてエスケープする必要をなくすため」です。

実行ファイルをパッケージに同梱するなら、プラグイン相対パスを使う必要があります。設定した PATH がベア名の解決に効くかどうかはクライアント定義なので、そこに依存するプラグインは適合を主張できません。

`${PLUGIN_ROOT}` と `${PLUGIN_DATA}`

stdio サブプロセスを起動するクライアントは、2つの環境変数を必ず渡します。

変数	中身	使いどころ
`PLUGIN_ROOT`	プラグインルートの絶対パス	同梱したスクリプト・バイナリ・設定ファイルの参照
`PLUGIN_DATA`	このプラグイン専用の永続データディレクトリ	依存パッケージ（node_modules、venv）、生成コード、キャッシュ

実際に渡される値はこんな形です。

PLUGIN_ROOT=/home/alex/.agents/plugins/devtools
PLUGIN_DATA=/home/alex/.agents/plugins/data/devtools

PLUGIN_DATA の場所を決めるのはクライアントですが、起動前に作成すること、書き込み可能にすること、そしてプラグインの更新をまたいで中身を保持することが義務づけられています。ここが実務では効いてきます。パッケージの中身は更新で丸ごと入れ替わるので、npm install した結果を残したいなら PLUGIN_DATA に置くことになります。

展開の規則は厳密です。

展開されるのは ${PLUGIN_ROOT} と ${PLUGIN_DATA} の2つだけです。それ以外のプレースホルダ風のテキストはリテラルのまま残りますし、シェルのような環境変数展開も行われません。

また env に PLUGIN_ROOT や PLUGIN_DATA という名前のエントリを書くと、そのサーバー設定は無効になります。この2つはクライアントが供給するものだからです。

リモート接続とシークレット

streamable-http と sse の url には制約があります。

絶対 HTTP/HTTPS URL であること
ユーザー情報とフラグメントを含まないこと
非ループバックのエンドポイントは HTTPS であること（HTTP が使えるのはホストがちょうど localhost かループバック範囲の IP リテラルのときだけ）

そして、ここは太字で書いておきたいところです。

⚠️ headers も env も「可視のパッケージデータ」であって、可搬なシークレット機構ではありません。 仕様は「プラグインは認証情報やシークレットを埋め込んではならない」と明記しています。

Agent Plugins 1.0.0 には、OAuth の設定も、認証情報を参照する可搬なフィールドもありません。認可の発見、ユーザー操作、認証情報の保管はすべてクライアント任せです。認可に失敗した場合は「そのサーバーの接続失敗」として扱われ、プラグインの設定エラーにはなりません。

MCP サーバーに API キーが要る場合、v1 の範囲でそれをポータブルに配る方法はありません。現状はクライアント側の仕組みに乗る必要があります。

🏷️ クライアント拡張：逆ドメインで場所を分ける

「標準は小さく保ちたい。でもクライアント独自の機能も置きたい」。この2つを両立させるのが逆ドメイン名前空間です。

置き場所は2種類あります。

マニフェストデータは extensions の下に置きます。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "example-plugin",
  "extensions": {
    "com.example.client": {
      "setting": true
    }
  }
}

ファイルは同名のトップレベルディレクトリに置きます。

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       └── SKILL.md
└── com.example.client/
    └── hooks/
        └── hooks.json

両方使ってもいいですし、片方だけでも構いません。

ここで重要なのは、Agent Plugins が拡張の中身に一切意味を与えないことです。名前空間の中で何をするかは、その名前空間を持つクライアントが決めます。そして、実装していない名前空間のエントリは中身を検証せずに無視します。

つまり、com.anthropic.claude-code のような名前空間に Claude Code 用の設定を書いておいても、VS Code はそれを無視するだけで、エラーにはなりません。1つのディレクトリを複数クライアントに配りながら、それぞれ独自の味付けを足せます。

逆ドメインを採用した理由は、中央のクライアント名レジストリを作らずに衝突を避けられるからです。

🧯 失敗境界：どこが壊れたら、どこまで壊れるか

仕様を読んでいて一番おもしろかったのが、この設計です。失敗の影響範囲が明示的に、狭く決められています。

致命的なのは plugin.json の不正だけです。それ以外は、壊れた部分だけが落ちて、残りは動きます。

Design Decisions の説明が的確でした。

スキルと MCP サーバーを持つプラグインが、1つのサーバーが利用不能になっただけで丸ごと使えなくなるべきではない。

そして仕様は、非致命的な失敗に対して診断の要件をセットで課しています。「報告すべき（SHOULD report）」が各所に書かれていて、失敗が沈黙しないようになっています。

未知のトップレベルフィールドの扱いも、この思想の表れです。スキーマ違反ではあるものの、報告して無視するだけで、プラグインは読み込まれます。タイポで全部が動かなくなるのは行き過ぎだ、という判断でしょう。

🔢 バージョニング：3つのバージョンを1つにまとめた

仕様・plugin スキーマ・mcp スキーマは、同じバージョン番号を共有します。スキーマの検証ルールが前のリリースから1文字も変わっていなくても、リリースごとに同じバージョンで publish されます。

一見むだに見えますが、理由があります。

作者とクライアントが理解すべき「可搬フォーマットのバージョン」が1つで済む
バージョンが混ざったパッケージを防げる
$schema 1つで、JSON Schema では表現できない要件も含めた検証ルール一式を選べる

その代わり、mcp.json の $schema は plugin.json のバージョンと一致していなければなりません。不一致の場合は MCP だけが無効になり、スキルは読み込まれます。ここでも失敗境界が狭く保たれています。

公開済みの正規識別子を別の内容に再割り当てすることは禁止されています。一度 1.0.0 として出した URL の中身は変わりません。

プラグイン自身の version は SemVer が推奨ですが、強制ではありません（前述のとおり、SemVer でないことを理由に拒否できません）。クライアントは version を更新チェックやキャッシュの鮮度判定に使えます。

✅ 対応クライアント（2026年8月19日時点）

公式サイトが公開しているデータによると、現時点で9つのクライアントが対応しています。

クライアント	skills	stdio	streamable-http	sse
VS Code	✅	✅	✅	✅
Cursor	✅	✅	✅	✅
GitHub Copilot	✅	✅	✅	✅
ChatGPT & Codex	✅	✅	✅	—
Kiro	✅	✅	✅	✅
Hermes Agent	✅	✅	✅	—
OpenClaw	✅	✅	✅	✅
Grok Bot	✅	✅	✅	✅
NanoClaw	✅	✅	✅	—

全9クライアントが skills に対応しています。sse に対応していないクライアントがいくつかありますが、sse の対応は仕様上 OPTIONAL なので適合性の問題にはなりません。

仕様は段階的な採用を認めています。スキルだけ対応するクライアントも、要件を満たしていれば適合クライアントです。MCP を実装する場合は stdio か streamable-http の少なくとも一方が必要で、両方が推奨されています。

AWS 側の対応も具体的です。Kiro Powers が Agent Plugins にネイティブ対応し、AWS Agent Toolkit として公式サポートの MCP サーバー・スキル・プラグインが公開されています。こちらは30以上のキュレーション済みスキルを複数のプラグインに分けて提供しているとのことです。

🚧 v1 に入らなかったもの

ここは正直に書いておきたいところです。Agent Plugins 1.0.0 には、権限モデルもサンドボックスも署名検証もシークレット機構もありません。

リポジトリの FUTURE_CONSIDERATIONS.md に、検討事項として列挙されています。ただし冒頭に「非規範であり、いずれの項目も将来のリリースへの収録が確約されたものではない」と明記されています。

領域	v1 にないもの
権限・承認 UX	マニフェストでの権限宣言、クライアントによる能力制限、インストール時の同意フロー、段階的な信頼レベル
来歴検証	署名検証、ソースとビルドを結ぶ attestation chain、信頼できる発行者の要求
シークレット	`secrets` フィールド、クライアント仲介のシークレット注入、プラグイン間のスコープ分離
企業統制	名前・発行者・署名による許可/拒否リスト、組織スコープのレジストリ、集中設定の上書き
監査証跡	install / enable / update などの標準イベントスキーマ、SIEM 連携
依存解決	`dependencies` フィールド、推移的依存の解決順
テスト	標準リンタ、クライアント実装の適合テストスイート

つまり、プラグインを信頼してよいかどうかの判断は、いまのところ完全に利用者とクライアント側の責任です。mcp.json の stdio サーバーは任意のコマンドを起動できるので、素性のわからないプラグインをそのまま入れるのは、素性のわからないシェルスクリプトを実行するのと変わりません。

企業で配る場合は、ここを自前で埋めることになります。社内リポジトリに限定する、レビューを通してから配る、といった運用面の設計が必要です。

コンポーネント型が skills と MCP の2つに絞られているのも、同じ「小さく始める」思想からです。Design Decisions によれば、この2つはプロジェクトの外に確立した仕様があり、クロスクライアントの採用実績があることが理由です。commands / hooks / agents / rules / LSP サーバーは、まだクライアント固有すぎて可搬な契約として安定しない、と判断されています。

AWS のブログでは、hooks とカスタムエージェントがロードマップ項目として挙げられています。

🤝 Claude Code の独自形式との関係

普段 Claude Code を使っている方にとっては、ここが気になるところだと思います。

2026年8月19日時点で、Anthropic は Technical Steering Committee に入っておらず、Claude Code のプラグインドキュメントにも agent-plugins.org への言及はありません。Claude Code は独自のプラグイン形式を持っています。

両者を並べるとこうなります。

	Agent Plugins 1.0.0	Claude Code
マニフェスト位置	`plugin.json`（ルート）	`.claude-plugin/plugin.json`（マニフェスト自体が任意）
マニフェストのスキーマ	クローズド（10フィールド）、`$schema` 必須	`name` のみ必須
スキル	`skills/<name>/SKILL.md`	`skills/<name>/SKILL.md`
MCP 設定	`mcp.json`	`.mcp.json`
その他のコンポーネント	なし（v1）	`commands/` `agents/` `hooks/` `.lsp.json` `workflows/` など

注目したいのは、スキルのレイアウトが完全に同じことです。どちらも skills/<スキル名>/SKILL.md で、中身は Agent Skills 仕様に従います。

つまり、スキルだけのプラグインなら、実質的に両対応にできます。plugin.json と .claude-plugin/plugin.json の両方を置いておけば、Agent Plugins 対応クライアントは前者を、Claude Code は後者を読みます。skills/ は共有されます。

MCP を含める場合は、mcp.json と .mcp.json の2つを置くことになります。中身の書式が違うので単純なコピーではありませんが、変換自体は機械的です。

図の緑の部分が、書き直さずに済むところです。スキル資産を持っているなら、そこは無駄になりません。

💡 Anthropic が TSC に入っていないことをどう読むかは、正直まだ判断材料が足りないと思っています。ただ、標準の土台になっている Agent Skills 仕様も SKILL.md という形式も、もともと Anthropic 発です。フォーマットの実質的な共通部分は、すでにかなり大きいと言えます。

🛠️ 作ってみる：最小プラグインから MCP 付きまで

実際に手を動かすと、思ったより短時間で終わります。段階的に見ていきます。

段階1：スキル1つだけのプラグイン

まずディレクトリを作ります。

mkdir -p hello-plugin/skills/greet

plugin.json を置きます。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}

スキルを書きます。ディレクトリ名と name を一致させるのを忘れないでください。

---
name: greet
description: Greet the user and offer help.
---

Greet the user and offer help.

これで完成です。スキル対応のクライアントなら読み込めます。

段階2：メタデータを足す

配布するなら、識別できる情報を足します。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hoge.devtools",
  "version": "1.0.0",
  "description": "HOGE 社内向けのデプロイ支援スキル集",
  "author": {
    "name": "HOGE Platform Team",
    "url": "https://github.com/hoge"
  },
  "repository": "https://github.com/hoge/devtools-plugin",
  "license": "MIT",
  "keywords": ["deploy", "hoge"]
}

keywords はクライアント側の検索・発見に使われます。

段階3：MCP サーバーを足す

mcp.json をルートに置きます。バージョンは plugin.json と揃えてください。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "deploy-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp"
    }
  }
}

同梱したバイナリを stdio で起動する場合は、プラグイン相対パスにします。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-index": {
      "type": "stdio",
      "command": "./bin/indexer",
      "args": ["--cache", "${PLUGIN_DATA}/cache"],
      "env": {
        "CONFIG": "${PLUGIN_ROOT}/config.json"
      }
    }
  }
}

cwd を省略しているので、作業ディレクトリはプラグインルートになります。キャッシュを PLUGIN_DATA に置いているので、プラグインを更新しても消えません。

つまずきやすい点

私が仕様を読みながら「これは間違えそうだな」と思ったところを挙げておきます。

つまずき	何が起きるか	対処
`$schema` を書き忘れる	必須フィールド欠落でプラグイン全体が拒否される	最小構成でも2行必要
`mcp.json` の `$schema` バージョンがずれる	MCP だけ丸ごと無効になる	`plugin.json` と揃える
`SKILL.md` の `name` とディレクトリ名が違う	そのスキルだけスキップされる	揃える
`command` にシェルコマンドを書く	1トークンとして解決されるので動かない	実行ファイル1つ + `args` に分ける
`command` に `${PLUGIN_ROOT}` を書く	展開されずリテラル扱いになる	`./bin/...` のプラグイン相対パスを使う
`env` に API キーを書く	可視のパッケージデータなので漏れる	v1 に可搬な解決策はない。クライアント側の仕組みを使う
`skills/a/b/SKILL.md` に置く	再帰探索されないので見つからない	直下の1階層に置く
マニフェストに独自フィールドを足す	報告のうえ無視される（プラグインは動く）	`extensions.<逆ドメイン>` の下に置く

command の2行は特に間違えやすいと思います。command はプレースホルダ展開の対象外で、代わりに ./ から始まるパスがプラグインルートを起点に解決されます。

失敗境界と適合要件を1枚にまとめると、上のようになります。

🧭 クライアント実装側から見た最低ライン

自分でクライアントを実装する側の要件も、8項目に整理されています。

ディレクトリパスからプラグインを読み込める
$schema からローカル対応のスキーマを選び、クローズドスキーマを検証する
未実装の extensions メンバは中身を検証せず無視する
サポートする各コンポーネント型を固定位置から探索する
MCP をサポートするなら stdio か streamable-http の少なくとも一方
サブプロセスを起動するなら PLUGIN_ROOT / PLUGIN_DATA を提供し、args env cwd で展開する
stdio の command を単一トークンとして解決し、既定の作業ディレクトリはプラグインルートにする
少なくとも1つのコンポーネント型をサポートする

読み込みの順序も決まっています。

ポイントは、マニフェストの検証がすべてに先立つことと、サーバーごとに個別で検証することです。仕様は mcp.schema.json に #/$defs/server を公開していて、クライアントが各サーバーを独立に検証できるようにしています。失敗境界を保つための配慮です。

✅ まとめ

Agent Plugins について、この記事で一番お伝えしたかったのは「この仕様は、あえて小さいことに価値がある」ということです。

やっているのは、ディレクトリの形とマニフェストの形を決めることだけです。配布方法もインストール方法も権限モデルも決めていません。決めていないからこそ、性格の違う9つのクライアントが同時に対応できたのだと思います。

一方で、その「決めていない部分」は使う側の責任として残ります。mcp.json の stdio サーバーは任意のコマンドを起動できて、v1 には署名検証も権限宣言もありません。素性のわからないプラグインを入れる前に、ls と cat で中を見る。ディレクトリ形式を選んだ設計が、ちょうどそれを可能にしています。

次の一歩としては、この順で触ってみるのが早いと思います。

plugin.json 2行 + SKILL.md 1つの最小プラグインを作って、手元のクライアントで読み込ませてみる（10分あれば終わります）
すでに書いた SKILL.md があるなら、skills/<名前>/ に移して plugin.json を添える
MCP サーバーを持っているなら mcp.json を足し、${PLUGIN_DATA} にキャッシュを寄せる

そして、社内で配ることを考えるなら、v1 が持っていないもの（署名・権限・シークレット）をどう埋めるかを先に決めておくことをおすすめします。フォーマットが標準化されても、信頼の設計は自分たちの仕事として残ります。

参考

Agent Plugins 公式サイト
Agent Plugins Specification 1.0.0（Status: Published）
plugin.schema.json / mcp.schema.json
FUTURE_CONSIDERATIONS.md
Agent Skills Specification
Model Context Protocol Specification
Introducing Agent Plugins — Vercel（2026-08-06）
AWS Supports Agent Plugins — AWS Open Source Blog（2026-08-06）
Claude Code plugins reference（比較用）