Agent Plugins 1.0.0 とは何か。plugin.json、MCP、Agent Skills、JSON 配置

読む前の早見

ファイル	仕様が求めること	それがしないこと
plugin.json	ルートの唯一のマニフェスト。$schema と name が必須。フィールド表は閉じている	MCP を内嵌できず、コンポーネントのパスも動かせない
skills/	直下の子ディレクトリの SKILL.md だけ。形式は Agent Skills 仕様	再帰しない。ディレクトリがなくても誤りではない
mcp.json	トップレベルは $schema と mcpServers だけ。各サーバに type が要る	ツールは実行しない。1.0.0 に可搬な資格情報フィールドはない
拡張ディレクトリ	com.example.client/ のような逆ドメイン。extensions も名前空間	他のクライアントは無視できなければならない

事実は Agent Plugins 1.0.0 仕様、Vercel の公開ノート、同日の Google Developers Blog。いずれも 2026-08-06。注文 A-1042 と orders.example.com は架空。

スキルと MCP サーバを、運べる一つのディレクトリに収める

Agent Plugins 1.0.0 は 2026 年 8 月 6 日に公開された。当時のコアメンテナは Amazon、Cursor、Microsoft、OpenAI、Vercel だった。同日の Google Developers Blog は、Kevin Hou を代表に Google がそのグループへ参加し、自社製品への対応を始めると書いた。これは Google が単独で出した私有形式ではない。仕様が定義する可搬コンポーネントは二つ、Agent Skills と MCP サーバ である。導入、配布、ポリシー、画面は各クライアントに残る。クライアントはコンポーネントを探す前に、ルートの plugin.json を検証する。プラグインの読み込み中に、Schema をネットワークから取得してはならない。

• マニフェスト：$schema は https://agent-plugins.org/schemas/1.0.0/plugin.schema.json。name は必須。
• スキル：skills/<名前>/SKILL.md。直下だけ。再帰しない。
• MCP：ルートの mcp.json。各エントリは stdio、streamable-http、または任意の古い sse。

MCP が回線上でどう呼ばれるかは Coding Agent が MCP を呼ぶ方法。MCP Tool Schema と Function Calling の差は MCP Tool Schema と Function Calling。本篇はあの二本を書き直さない。プラグインディレクトリの二つの JSON が何を持つかだけを書く。

plugin.json のフィールド表は閉じている

許されるトップレベルは $schema、name、version、description、author、homepage、repository、license、keywords、extensions だけである。必須は先頭の二つ。名前は 1 から 64 文字、小文字、数字、ハイフン、ピリオドだけ。先頭と末尾は英数字。連続する -- と .. は不可。version はセマンティックバージョンを勧めるが、SemVer でないことだけでは拒否理由にならない。author は name、email、url だけ。架空の注文プラグイン：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "orders-plugin",
  "version": "1.0.0",
  "description": "Look up fictional order A-1042. No refunds.",
  "license": "Apache-2.0",
  "keywords": ["orders"]
}

未知のトップレベルフィールドは報告して無視し、残りが正しければ読み込みを続ける。必須の欠落、型の誤り、不正な名前はパッケージ全体を拒む。コンポーネントは発見も実行もしない。クライアント固有のデータは extensions へ。鍵は逆ドメイン、値はオブジェクト。他のファイルがルートマニフェストの中核フィールドを上書きすることはできない。

スキルと MCP はマニフェストに書けない

仕様は位置を固定する。skills/ の直下の子で、ちょうど SKILL.md という通常ファイルを持つものが一つのスキルである。前文と scripts/、references/、assets/ は Agent Skills 仕様の担当。本仕様は発見の仕方だけを定め、クライアントがモデルへどう渡すかは定めない。MCP は plugin.json に内嵌できず、別パスへも動かせない。mcp.json のトップレベルは $schema と mcpServers だけ。空の mcpServers は合法。二つの $schema の版は一致しなければならない。1.0.0 の MCP 識別子は https://agent-plugins.org/schemas/1.0.0/mcp.schema.json。stdio は type と command が必須。args、env、cwd は任意。./ で始まるパスはプラグインルート相対。../ でルートの外へ出てはならない。クライアントは PLUGIN_ROOT と PLUGIN_DATA を展開する：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "orders": {
      "type": "stdio",
      "command": "./bin/orders",
      "args": ["--data", "${PLUGIN_DATA}/orders"],
      "cwd": "${PLUGIN_ROOT}"
    }
  }
}

リモートは streamable-http で、url が必須。sse は非推奨の任意トランスポート。失敗したあとの代替は定義しない。適合クライアントは stdio と streamable-http の少なくとも一方を支え、両方を支えるのが望ましい。1.0.0 に可搬な OAuth や資格情報参照はない。認証はクライアントが持つ。パス規則はパッケージ内のファイルに限り、子プロセスのサンドボックスではない。ツール引数は別の Schema の門が要る。AI が JSON Schema を要する理由。

壊れた部分は自分の境界で止まる

仕様は失敗を分ける。一つの悪い JSON を、パッケージ全体の死と読まない：

クライアントは未対応のコンポーネント種別を無視する。com.example.client/ のような逆ドメインは、あるクライアントの拡張である。他は見なかったことにできなければならない。extensions の未知の名前空間も同様に無視する。すでに送られた tools/call をサンドボックスがどう止めるかは別層。OpenShell と Sentry。

プラグインを出す前の六つの確認

MCP サーバの URL を plugin.json に貼るところから始めない：

1. 先にルートの plugin.json を書く。閉じたフィールド表の鍵だけ。orders-plugin のような小文字の名前。
2. スキルは直下の子に置く。skills/lookup-order/SKILL.md。さらに深いディレクトリは発見されない。
3. MCP は mcp.json にだけ書く。各エントリに type。ローカルは stdio と ./bin/orders。../ は使わない。
4. 二つの $schema を同じ 1.0.0 にする。一致しなければスキルは残れて、MCP は残らない。
5. 資格情報はクライアントに残す。1.0.0 の mcp.json に可搬な秘密フィールドはない。トークンを env や headers に書いてコミットしない。
6. ツール引数は別の Schema。マニフェストはサーバの場所だけを示す。A-1042 は宿主が検証してから実行する。

skills/ も mcp.json もないプラグインでも合法でありうる。必須ファイルは plugin.json だけである。

マージする前に二つの JSON を広げる

読み込みの失敗は、パッケージ拒否か、一台の MCP サーバのスキップか。プロンプトの前に分ける。

• plugin.json と mcp.json を 整形 し、Schema 検証 でトップレベルに余分な鍵がないか、$schema が欠けていないかを見る。
• JSONPath 抽出 で $.name、$.mcpServers.orders.type、$.mcpServers.orders.command を抜く。
• 前の版と JSON Diff する。パスがプラグインルートの外へ出ていないかを先に見る。
• skills/lookup-order/SKILL.md が直下の子の通常ファイルであり、より深いファイルではないことを確認する。
• 設定のトークンは先に 伏せ字。秘密を含む mcp.json を公開の整形サイトに貼らない。JSONSort はブラウザのローカルで動く。

二つの JSON が閉じたフィールド表で組み立て直せ、ディレクトリが固定位置にあれば、そのプラグインは 1.0.0 に乗っている。照会を実行するかはマニフェストが決めない。

よくある誤り

• Google の私有プラグイン形式と書く。2026-08-06 の公開文はベンダー横断の仕様である。Google はその日にコアメンテナとして参加した。
• mcpServers を plugin.json に書く。仕様は内嵌を禁じ、パスの移動も禁じる。クライアントが読むのはルートの mcp.json だけ。
• オブジェクトの形からトランスポートを推測する。各サーバに type が要る。URL に見えるから HTTP、という規則はない。
• API 鍵を mcp.json に書く。1.0.0 に可搬な資格情報フィールドはない。認証はクライアント。例は架空の注文だけ。
• 一台のサーバが起動しないので全スキルを捨てる。一台の失敗はそのエントリだけ。トップレベルの mcp.json が無効なら MCP 全体が止まる。スキルは読み続ける。
• 本篇で MCP と Function Calling の対比を書き直す。ここは、既存の MCP 設定を固定ファイルへどう置くかだけを書く。

FAQ

plugin.json だけで、スキルも MCP もないディレクトリは合法か？

合法である。必須ファイルは plugin.json だけ。skills/ や mcp.json がなくても、クライアントは在るものを読み、誤りにはしない。必須の欠落か不正な名前で、パッケージ全体を拒む。

二つの $schema が一致しないとどうなるか？

MCP 設定が無効になる。スキルと他のコンポーネント種別は有効なまま。1.0.0 では両方とも仕様の 1.0.0 識別子を使い、版は一致しなければならない。

SKILL.md を skills/orders/extra/ に置けるか？

発見されない。クライアントは skills/ の直下だけを見て、再帰しない。発見されるには skills/lookup-order/SKILL.md のような直下の通常ファイルでなければならない。

stdio と streamable-http の両方を書く必要があるか？

ない。一台のサーバは一つの type。stdio は command、streamable-http は url。sse は非推奨で、クライアントは支えなくてよい。一つの接続が失敗したとき別のトランスポートへ替える定義はない。

この JSON は自分で注文を調べるか？

調べない。plugin.json はプラグインに名前を付け、mcp.json はサーバの場所をクライアントに示す。tools/call は宿主が実行する。A-1042 のような引数は別の Schema で検証する。マニフェストに可搬な秘密フィールドはない。

結論

Agent Plugins 1.0.0 は、Agent Skills と MCP サーバを一つのルートディレクトリに収めて運べるようにする。plugin.json が固定するのは仕様バージョンと名前。コンポーネントの位置はマニフェストで変えられない。

orders-plugin が plugin.json に、./bin/orders が mcp.json に、SKILL.md が直下の子にあることを先に確認する。三箇所が固定位置にあれば、クライアントは設定の隠し場所を推測しなくてよい。

あわせて読む

• Coding Agent は MCP をどう呼ぶか tools/call の回線上の形。本篇は書き直さない
• MCP Tool Schema と Function Calling プロトコルの対比であり、プラグインディレクトリではない
• AI はなぜ JSON Schema を要るか サーバを見つけたあとも、引数は門を通る
• OpenShell と Sentry すでに送られた tools/call をサンドボックスがどう止めるか
• JSONSort のローカル道具 整形、検証、Diff、Schema
• すべての記事 JSON と AI 開発のほかのノート

更新記録： 2026-10-12 初出