Agent Plugins 1.0とは？梱包仕様とクライアント準拠要件を実装目線で解説

Agent Plugins 1.0.0は、Agent SkillsとMCPサーバを1つのディレクトリへ詰めてクライアント間で持ち運ぶための梱包仕様です。2026年8月6日に公開され、Amazon・Cursor・Microsoft・OpenAI・Vercelの5名がCore Maintainerとして技術運営委員会を構成しています。中身は小さい。plugin.jsonという1枚のマニフェストと、skills/ディレクトリ、任意のmcp.jsonだけです。この記事では必須フィールドと命名制約、3つのトランスポート、PLUGIN_ROOTとPLUGIN_DATAの予約規則、権限・署名・秘密情報が仕様外である前提での設計を整理します。

まとめ：Agent Plugins 1.0対応で最初に決める梱包構成と移行順序

手を動かす順番は決まっています。plugin.jsonに$schemaとnameの2つだけ書いて読み込ませ、skills/へSKILL.mdを持つディレクトリを置き、MCPサーバが要る場合だけmcp.jsonを足す。この3段で最小のプラグインが成立します。クライアント固有のフック定義をplugin.jsonへ書き足すと、スキーマが閉じているため読み込み自体が拒否されかねません。固有機能は拡張名前空間へ隔離してください。

移行の緊急度については立場を明確にします。既存のClaude形式やCopilot形式を今すぐ書き換える必要はありません。VS Codeは4種類の形式をマニフェストから自動で見分けており、旧形式が即座に動かなくなる状況ではないためです。優先すべきは、複数クライアントへ同じスキルを配る場合の可搬コアの切り出し。権限宣言・署名検証・秘密情報の受け渡しはv1.0.0の範囲外なので、そこは自社の配布ラッパーで埋める前提で設計します。

Agent Plugins 1.0が定めた梱包の範囲とMCPとの役割分担

この仕様が何を決めて何を決めていないのかを最初に切り分けます。誤解が起きやすいのは、通信プロトコルの新標準だと受け取られる点です。

plugin.jsonを1つ持つディレクトリという最小単位の定義

§3の用語定義では、プラグインは「マニフェストと任意のコンポーネントを持つ自己完結したディレクトリ」です。単一ファイルでもアーカイブ形式でもなく、ルート直下にplugin.jsonが無ければクライアントは受け付けません。

この単位には副作用があります。§4.1は、解決後のパスがルート内へ留まることを要求しました。シンボリックリンクはルート内を指す限り許容され、外へ抜けるパスは拒否されます。node_modulesを外部へリンクする梱包は、ここで弾かれます。

skills/とmcp.jsonの固定配置とplugin.jsonへ設定を書けない制約

探索先は§6.1で固定です。スキルはskills/直下、MCPサーバはルートのmcp.json。plugin.jsonから配置を上書きすることも、設定をインラインで書くこともできません。package.jsonがexportsでエントリを指すのとは逆の設計です。

スキルの数え方も規定されました。skills/直下の子ディレクトリのうちSKILL.mdという通常ファイルを含むものが1スキルで、深い階層を再帰的に探してはならない。中間ディレクトリで分類すると発見されません。書式自体はAgent Skills仕様の管轄で、Claude SkillsのSKILL.mdの書き方で扱ったフロントマター設計がそのまま通用します。

通信規格ではなく梱包規約という位置づけとMCP・Skillsとの境界

§7は境界線を丁寧に引いています。SKILL.mdの書式はAgent Skills仕様が正、MCPのワイヤ挙動とライフサイクル意味論はModel Context Protocol仕様が正。Agent Pluginsが新たに決めたのはmcp.jsonの形式と発見方法だけです。

MCPの置き換えではありません。サーバ実装もtool定義も認可設計も従来どおりで、変わるのは配り方。MCPで外部ツールを接続する実装手順で組んだサーバがあれば、mcp.jsonへ接続情報を書くだけで梱包対象になります。v1のコンポーネント種別はちょうど2つで、他は「形式外であり準拠に影響しない」と明記されました。

plugin.jsonの必須2項目とクローズドスキーマで分かれる検証結果

マニフェストは10フィールドだけを許す閉じたスキーマです。この性質が、実装時のエラーの出方を左右します。

$schemaとnameだけが必須というメタデータ7項目の型検証

§5.3の必須は$schemaとnameの2つ。$schemaの値は canonical identifier に固定され、agent-plugins.orgのschemas/1.0.0/plugin.schema.jsonを指すURL文字列でなければなりません。見落とされがちな規定がもう1つ。クライアントは読み込み中にスキーマを取得してはならない、という禁止です。ローカルの検証ルールを選ぶ識別子として使われます。

任意フィールドは version・description・author・homepage・repository・license・keywords の7つ。検証はJSONの型のみで、内容の妥当性は問われません。versionがセマンティックバージョニングでない、licenseがSPDX識別子でないことを理由に拒否するのは禁じられています。authorだけは例外で、name・email・url以外を含むと無効です。

name の1〜64文字・小文字英数・連続ハイフン禁止という制約

§5.5の命名規則は具体的です。長さ1〜64文字、使える文字はa-z・0-9・ハイフン・ピリオドのみ、先頭と末尾は英数字、連続するハイフンと連続するピリオドは禁止。有効例はmy-plugin・acme.tools・lint3r、無効例はMy-Plugin・-start・has–doubleと仕様書が挙げています。

大文字が使えない点は移植時に効きます。既存のリポジトリ名から機械的に流用すると、キャメルケースやアンダースコアで引っかかる。AWS_Deployのような名前は変換が必要です。ピリオドは許されるので逆ドメイン風のacme.internal.deployは通ります。名前の一意性やレジストリでの衝突回避は仕様の管轄外です。

不明フィールドは無視して継続、他の違反はプラグイン全体を拒否

失敗の扱いが二段構えです。§5.2は、未知の最上位フィールドを見つけたクライアントに対し、報告したうえで無視し、他の条件を満たすなら読み込みを続けるよう求めました。extensionsがオブジェクトでない場合も非致命です。

それ以外のスキーマ違反はすべて致命的。§11.3では、クライアントはプラグインを拒否し、いかなるコンポーネントも発見・実行してはならないとされます。nameが空文字列、versionに数値——こうした軽微に見えるミスでスキルもMCPサーバもまとめて落ちる。前方互換は未知フィールドの側にだけ用意されました。

mcp.jsonのトランスポート3種とサーバ単位で切り離される失敗境界

MCPサーバの記述形式は、既存のクライアント設定と似ていながら制約が強めです。写経で済ませると起動しない設定を量産します。

stdio・streamable-http・sseの必須項目と最低実装要件

mcp.jsonの最上位は$schemaとmcpServersの2つだけで、他のフィールドは置けません。各サーバ設定はtypeを持ち、閉じた3バリアントのいずれか1つへ正確に一致する必要があります。別バリアントのフィールドが1つ混ざるだけで、そのエントリは無効です。

stdioはcommandが必須でargs・env・cwdが任意、streamable-httpとsseはurlが必須でheadersが任意。urlは絶対HTTPまたはHTTPSで、フラグメントを含めてはならず、ループバック以外の宛先はHTTPS必須です。sseは2024-11-05版MCP仕様の非推奨トランスポートを指し、Streamable HTTP内部のSSEストリームではないと注記されました。

commandは単一トークンで相対パスはドット始まりという解決規則

commandの規定は特に厳格でした。シェルコマンド文字列ではなく単一の実行可能トークンで、書けるのはbareな実行ファイル名か、ドットとスラッシュで始まる相対パスの2択です。npx -y some-serverのように引数を混ぜる書き方は無効。引数はargsへ分離します。

bare名はプラットフォームの実行ファイル探索規則で解決されますが、環境変数PATHが探索に関与するかはクライアント定義とされ、準拠プラグインはその挙動に依存してはならないと但し書きが付きました。実行ファイルを同梱するなら相対パス表記が正解です。

$schemaのバージョン不一致でMCPだけ無効化される部分故障

mcp.jsonにも$schemaが必須で、値はschemas/1.0.0/mcp.schema.jsonを指すURLです。plugin.jsonが宣言したバージョンと食い違うと、§7.2.2によりMCP設定だけが無効化され、スキルの読み込みは継続します。この部分故障の設計は仕様全体で一貫しており、どこで壊れたとき何が生き残るかを整理しておくとデバッグが速くなる。

最下段は運用で効く区別です。認可の失敗はプラグイン設定の不備ではなく、接続の失敗として扱われます。

PLUGIN_ROOTとPLUGIN_DATAの予約と単一・非再帰の置換規則

可搬性の実務を支えるのがこの2つの予約環境変数です。§9はここだけ妙に細かく、そのぶん踏み抜きやすい。

依存物はPLUGIN_DATA・同梱物はPLUGIN_ROOTという置き場の分担

stdioサーバを起動するクライアントは、サブプロセス環境へPLUGIN_ROOTとPLUGIN_DATAを必ず与えます。前者は解決済みプラグインルートの絶対パス、後者はそのインストール済みインスタンス専用の永続データディレクトリです。

使い分けも仕様書が明示しました。PLUGIN_DATAへ置くのは依存物（node_modulesや仮想環境）・生成コード・キャッシュなど更新をまたいで残す状態、PLUGIN_ROOTが指すのは同梱したスクリプト・バイナリ・設定ファイル。クライアントはPLUGIN_DATAを起動前に作成し、更新をまたいで保持する義務を負います。npm installをルートで走らせる設計はここで破綻します。

args・env値・cwdだけが展開対象という単一・非再帰の置換規則

プレースホルダ展開の適用範囲は3か所です。argsの各文字列要素、envの各文字列値、cwdの文字列。envのキー、command、固定のコンポーネント配置には適用されません。置換は単一かつ非再帰で、置換によって現れた文字列をさらに走査してはならない。$HOMEを書いても展開されずそのまま渡ります。

最も踏みやすい罠がその先にあります。envオブジェクトにPLUGIN_ROOTまたはPLUGIN_DATAという名前のエントリを含めると、そのサーバ設定は§7.2.2により無効になる。予約変数はクライアント自身が供給するもので、プラグイン側から上書きする経路は塞がれました。処理は次の順序です。

1. クライアントが基底の環境を決める（継承・省略・サニタイズは任意）
2. プレースホルダ展開後のenvを基底環境へ重ねて同名を置き換える
3. 最後にPLUGIN_ROOTとPLUGIN_DATAを設定し、同名エントリを上書きする

基底環境の扱いがクライアント任せである以上、準拠プラグインは仕様が要求する変数か設定で明示した変数以外に依存できません。ローカルで動くのに配布先で起動しないMCPサーバは、この暗黙の環境依存が原因であることが多いはずです。

権限・署名・秘密情報が仕様外である前提で組む配布と運用の設計方針

決めなかった領域を把握しないまま配布へ進むと、標準準拠を安全性の担保と取り違えます。

FUTURE_CONSIDERATIONSに退避した7領域と自前で埋める範囲

仕様リポジトリのFUTURE_CONSIDERATIONS.mdは、将来版で扱いうる領域を非規範として列挙しました。権限・承認UX、来歴検証、秘密情報の扱い、企業統制、監査証跡、依存解決、テスト検証の7領域です。文書自体が「いずれも準拠に必須ではなく、将来版への収録が確約されたものでもない」と断っています。

実務上の含意は明快です。プラグインは他プラグインへの依存を宣言できず、署名で発行元を検証する経路も無く、インストールや更新のイベントスキーマも標準化されていません。標準に準拠したという事実は、形式が揃ったことだけを意味します。

headersとenvは可視データという制約下での資格情報の扱い

秘密情報については踏み込んだ禁止が書かれました。headers値は「可視のパッケージデータであり可搬な秘密機構ではない。資格情報その他の秘密を埋め込んではならない」。envにも同趣旨の禁止が§9.2にあります。

ではAPIキーが要るMCPサーバをどう梱包するか。現時点で可搬な解はありません。クライアント固有の秘密管理へ寄せるか、サーバ側の認可をクライアントの認可機構へ任せるか、資格情報を要する部分をプラグインの外へ出すかの3択です。リダイレクト経由で別オリジンへ設定済みヘッダを転送してはならない、という規定も併せて置かれました。

拡張名前空間で各社固有機能を隔離する可搬コアと配布層の三層分離

クライアント固有の機能は§8の拡張名前空間へ逃がします。マニフェスト内はextensions配下に逆ドメイン名のキーで、ファイルは同名の最上位ディレクトリへ。com.example.clientなら設定はextensions.com.example.client、ファイルはcom.example.client/以下です。実装していない名前空間は、値を検証せず無視することが求められています。

これを踏まえると、社内配布は3層に分けるのが扱いやすい。第1層が可搬コア（plugin.json・skills/・mcp.json）、第2層がクライアント固有の拡張ディレクトリ、第3層が署名・許可リスト・監査を担う配布ラッパーです。npm方式で配布層を先に整えた例としてはAPM（Agent Package Manager）の仕組みが参考になる。エージェント基盤ごとスキル設計や運用体制を外部と組み立てるなら、生成AI開発・AI受託開発の相談窓口から要件整理に入るのが早い進め方です。

Claude形式・Copilot形式と併存する現況と移行を見送ってよい条件

標準が出たからといって既存資産を全部書き換える話にはなりません。クライアント実装の実態から緊急度を判断します。

VS Codeが4形式を自動判別する実装から読む移行の緊急度の低さ

VS Codeの公式ドキュメントは、プラグイン形式をマニフェストから自動判別すると明記しています。判別対象はAgent Plugins 1.0（$schemaで識別）、Copilot形式、Claude形式（.claude-plugin配下のplugin.json）、Legacy OpenPluginの4つです。

制約も書かれました。「VS Codeは現在、Agent Plugins 1.0パッケージ内のクライアント拡張データとディレクトリを無視する」。標準形式で梱包してもVS Code固有のカスタムエージェントやフックは読まれず、Copilot形式の構成が引き続き必要です。移行は可搬部分の獲得であって固有機能の統合ではない。書き換えを急ぐ理由は薄いというのが結論です。

Core Maintainer 5社体制とMAINTAINERS.md未反映という現況

ガバナンスの現況も確認しておきます。仕様リポジトリのMAINTAINERS.mdは、2026年8月10日時点でClare Liguori（Amazon）・Roshan Sadanani（Cursor）・Harald Kirschner（Microsoft）・Gav Verma（OpenAI）・Jonathan Hefner（Vercel）の5名を記載し、Leadは Jonathan Hefner。Googleは8月6日にKevin Hou（Google DeepMind）名義で参加を表明しましたが、MAINTAINERS.mdへは反映されていません。

ローンチ時点の対応クライアントはChatGPTとCodex、Cursor、GitHub Copilot、Kiro、VS Code。Anthropicはこの一覧にもCore Maintainerにも含まれず、Claude Codeは独自形式を維持しています。AWS Labsが2026年2月に公開したAgent Plugins for AWSの設計は4種のアーティファクトを統合する構成でしたが、標準のv1が扱うのは2種だけ。最小公倍数ではなく最大公約数として引かれています。

単一クライアント運用と秘密情報が必須のMCPで見送る判断基準

採用しない判断をはっきり書きます。次に当てはまるなら移行は見送って構いません。

• 配布先が単一クライアントに固定されている場合。可搬性という利得が生まれず、固有形式のほうが機能面で有利です
• MCPサーバがAPIキーを前提とし、クライアント固有の秘密管理へ依存している場合。設定の一部が非可搬のまま残ります
• フック・サブエージェント・スラッシュコマンドが中核を占める場合。中核部分が拡張名前空間へ落ちます
• 署名検証や許可リストによる統制が先に必要な場合。将来検討の領域で、標準準拠では満たせません

逆に、社内の共通スキル（コーディング規約、レビュー観点、定型ワークフロー）を複数のエディタやCLIへ同じ内容で配りたいなら移行の価値は高い。判断軸は導入クライアント数と秘密情報への依存度の2点です。

よくある質問

Agent Plugins 1.0の導入検討で問い合わせの多い論点をまとめました。

Agent Plugins 1.0はMCPを置き換えるものですか？

置き換えません。§7.2は、MCPのワイヤ挙動とライフサイクル意味論をModel Context Protocol仕様が定義すると明記しており、Agent Pluginsが決めたのはmcp.jsonの形式だけです。既存のMCPサーバ実装に変更は要らず、接続情報の書き方が1つ増えたと捉えるのが実態に近い。SKILL.mdの書式も同様です。

plugin.jsonにMCPサーバ設定を直接書けますか？

書けません。§7.2.1が「MCP設定はplugin.json内でインライン宣言してはならず、代替のコアパスから読み込んでもならない」と規定しています。§6.1でも、plugin.jsonは固定配置を上書きできないと明記されました。スキーマが閉じているため、mcpServersという最上位フィールドを書いても未知フィールドとして無視されます。

Claude Code向けのプラグインはそのまま使えますか？

クライアント次第です。VS Codeは.claude-plugin配下のplugin.jsonをClaude形式として自動判別するため、この経路では既存資産が動きます。ただし形式が違えば持ち運べる範囲も変わるので、複数クライアントへ同じスキルを配る目的があるならskills/以下を標準形式へ切り出す価値がある。Anthropicは2026年8月10日時点でCore Maintainerに含まれていません。

プラグインに認証トークンを同梱してもよいですか？

仕様が明確に禁じています。mcp.jsonのheaders値とenv値はいずれも「可視のパッケージデータであり可搬な秘密機構ではない」と位置づけられ、資格情報その他の秘密を埋め込んではならないと規定されました。v1.0.0はOAuth設定も可搬な資格情報参照フィールドも定義していません。

skillsだけのクライアントでも準拠を名乗れますか？

名乗れます。§11.2が段階的な採用を認めており、スキル専用のクライアントはMCPサーバをサポートしなくても、他の適用要件をすべて満たせば準拠します。最低要件はコンポーネント種別を少なくとも1つサポートすること。MCPサーバに対応する場合のみ、stdioとstreamable-httpの一方の実装が要ります。

関連記事

• 開発者が押さえるべきAgent Plugins for AWSの基本概念と登場背景：先行したベンダー実装の束ね方
• APM（Agent Package Manager）とは：配布層をnpm方式で整えた別解
• Claude Skillsとは？SKILL.mdの書き方：skills/へ入れる中身の書式設計
• AIエージェントにMCPで外部ツールを接続する実装手順とは：サーバ側の実装と認可
• Codex Skillsとは？SKILL.mdの作り方と配置場所：クライアントごとの配置差