Agent Plugins 1.0への移行手順｜plugin.json・skills・mcp.jsonの新構成

Agent Plugins 1.0への移行は強制ではありません。現在のGitHub Copilot形式で作成されたプラグインは、Agent Plugins 1.0へ変更しなくても引き続き利用できます。

ただし、同じスキルやMCPサーバーをVS Code、GitHub Copilot CLI、GitHub Copilotアプリなどで共通利用したい場合は、Agent Plugins 1.0へ移行するメリットがあります。移行の要点は、plugin.jsonに$schemaを追加し、スキルをskills/、MCP設定をmcp.json、Copilot固有機能をcom.github.copilot/へ整理することです。(The GitHub Blog)

Agent Plugins 1.0とは

Agent Plugins 1.0は、AIエージェント向けのスキルとMCPサーバーを、特定の製品に依存しない形で配布するためのオープンな仕様です。

従来は、同じスキルやMCPサーバーであっても、VS Code、Copilot CLI、ほかのエージェントクライアントごとにmanifestやディレクトリ構成を調整する必要がありました。

Agent Plugins 1.0では、次の2種類が共通コンポーネントとして標準化されています。

コンポーネント	配置場所	役割
Agent Skills	`skills/`	手順、専門知識、スクリプト、参考資料などを提供する
MCPサーバー	`mcp.json`	外部システムやツールとの接続を定義する

一方、カスタムエージェント、スラッシュコマンド、ルール、フックなどはGitHub Copilot固有の機能です。これらはcom.github.copilot/に分離します。

対応していないクライアントはcom.github.copilot/を無視し、共通部分であるskills/とmcp.jsonだけを読み込めます。これにより、1つのパッケージで移植性とCopilot固有機能を両立できます。(Visual Studio Code)

Agent Plugins 1.0へ移行すべきか判断する

既存のCopilotプラグインは、すぐに移行する必要はありません。GitHubは、Agent Plugins 1.0を対象としていない既存プラグインについて、移行不要で引き続きサポートすると案内しています。(The GitHub Blog)

判断の目安は次のとおりです。

状況	推奨する対応
GitHub Copilotだけで利用しており、問題なく動作している	現行形式のまま継続してもよい
新しいプラグインを開発する	Agent Plugins 1.0で作成する
VS CodeとCopilot CLIの両方で配布したい	Agent Plugins 1.0への移行を推奨
複数のエージェント製品向けに同じ内容を重複管理している	共通パッケージ化のため移行を推奨
エージェント、フック、MCPを多数含む大規模プラグイン	段階的に移行し、旧版をすぐ削除しない
現行版の安定運用を最優先したい	新旧を別ブランチまたは別パッケージで検証する

特に、複数クライアント向けにmanifestやMCP設定をコピーしている場合は、Agent Plugins 1.0へ移行する効果が大きくなります。

Agent Plugins 1.0のmanifest構成：VS Code・Copilot CLI共通化の考え方

既存のCopilot形式における代表的な構成

既存のGitHub Copilotプラグインでは、次のような構成が使われます。

my-plugin/
├── plugin.json
├── agents/
│   └── reviewer.agent.md
├── skills/
│   └── code-review/
│       └── SKILL.md
├── hooks.json
├── .mcp.json
└── lsp.json

実際の配置はプラグインによって異なり、plugin.jsonのagents、skills、hooks、mcpServersなどから任意の場所を指定している場合もあります。(GitHub Docs)

Agent Plugins 1.0へ移行した後の構成

Agent Plugins 1.0では、共通コンポーネントの配置場所が固定されます。

my-plugin/
├── plugin.json
├── skills/
│   └── code-review/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── mcp.json
└── com.github.copilot/
    ├── agents/
    │   └── reviewer.agent.md
    ├── commands/
    ├── rules/
    └── hooks/
        └── hooks.json

変更点を整理すると、次のようになります。

既存形式の要素	Agent Plugins 1.0での配置	注意点
`plugin.json`	プラグインルート	正規の`$schema`を追加する
`skills`フィールド	原則として削除	`skills/`から自動検出される
スキル	`skills/<スキル名>/SKILL.md`	`skills/`直下の子ディレクトリに置く
`.mcp.json`	`mcp.json`	ファイル名だけでなく内部形式も確認する
`mcpServers`フィールド	原則として削除	MCP設定はルートの`mcp.json`に分離する
カスタムエージェント	`com.github.copilot/agents/`	Copilot固有コンポーネントとして扱う
コマンド	`com.github.copilot/commands/`	他クライアントでは無視される
ルール	`com.github.copilot/rules/`	Copilot対応クライアント向け
フック	`com.github.copilot/hooks/hooks.json`	旧形式のルート直下とは場所が異なる
LSPやUI固有機能	クライアント固有領域または互換パッケージ	Agent Plugins 1.0の共通コンポーネントではない

Agent Plugins 1.0のplugin.jsonは、記述できるトップレベルフィールドが限定された「閉じたスキーマ」です。skills、agents、commands、hooks、mcpServers、lspServersなどを従来どおりトップレベルに残す構成は、標準のmanifestにはなりません。(GitHub)

Agent Plugins 1.0への移行手順

現在のプラグインを分類する

最初に、既存ファイルを「共通化できるもの」と「Copilot固有のもの」に分けます。

分類	主な対象
Agent Plugins 1.0の共通部分	Agent Skills、MCPサーバー
GitHub Copilot固有部分	カスタムエージェント、コマンド、ルール、フック
個別判断が必要な部分	LSP、UI、キャンバスなどの拡張、マーケットプレイス固有情報

作業前に移行用ブランチを作成し、旧構成を削除せずに新構成を追加する方法が安全です。

公式の移行例でも、最初に新しいplugin.jsonを追加し、スキルとMCPを移した後、各クライアントでテストしてから旧ファイルを削除する段階的な移行が推奨されています。(GitHub)

plugin.jsonに$schemaを追加する

プラグインルートのplugin.jsonを、Agent Plugins 1.0のmanifestとして書き換えます。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-dev-tools",
  "version": "1.0.0",
  "description": "Development skills and MCP tools for project teams.",
  "author": {
    "name": "Example Team"
  },
  "repository": "https://github.com/example/my-dev-tools",
  "license": "MIT",
  "keywords": [
    "copilot",
    "development",
    "mcp"
  ]
}

Agent Plugins 1.0へ準拠する場合、$schemaとnameが必要です。version、description、author、repository、license、keywordsなどは任意です。

プラグイン名は1～64文字で、小文字の英字、数字、ハイフン、ピリオドを使用します。先頭と末尾は英数字にし、--や..を含めないようにします。

有効な例は次のとおりです。

my-plugin
acme.tools
deployment-helper

次のような名前は避けます。

My-Plugin
-start-plugin
my--plugin
acme..tools

また、スキルやMCPサーバーの場所は固定されているため、Agent Plugins 1.0のplugin.jsonにskillsやmcpServersのパスを書く必要はありません。(Agent Plugins)

スキルをskills/へ配置する

各スキルは、skills/直下の子ディレクトリに配置します。

skills/
├── code-review/
│   ├── SKILL.md
│   ├── scripts/
│   │   └── check.sh
│   ├── references/
│   │   └── review-policy.md
│   └── assets/
└── release-notes/
    └── SKILL.md

重要なのは、SKILL.mdを深い階層に置かないことです。

次の構成では、code-reviewがスキルとして検出されます。

skills/code-review/SKILL.md

一方、次のように余分な階層を挟むと、クライアントがスキルを再帰的に探さないため、検出されない可能性があります。

skills/development/code-review/SKILL.md

SKILL.mdというファイル名は大文字・小文字を含めて正確に記述します。スクリプト、参考資料、画像、サンプルなどは、各スキルのディレクトリ内に追加できます。(Agent Plugins)

MCP設定をmcp.jsonへ移す

従来の.mcp.jsonやplugin.json内のmcpServers設定は、プラグインルートのmcp.jsonへ移します。

ローカルプロセスを起動するMCPサーバーの例は次のとおりです。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "project-tools": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${PLUGIN_ROOT}/server/index.js"
      ],
      "cwd": "${PLUGIN_ROOT}"
    }
  }
}

Agent Plugins 1.0のmcp.jsonでは、トップレベルに記述するのは$schemaとmcpServersです。

利用できる主な接続方式は次のとおりです。

`type`	用途	主な必須項目
`stdio`	ローカルの実行ファイルやNode.jsプログラムなどを起動する	`command`
`streamable-http`	リモートのMCPエンドポイントに接続する	`url`
`sse`	従来のHTTP＋SSE方式に接続する	`url`

新しいリモート接続では、基本的にstreamable-httpを使用します。sseは非推奨の従来方式であり、クライアント側の対応も任意です。

stdioでは、commandにシェルコマンド全体を書くのではなく、1つの実行ファイル名を指定します。引数はargsへ分離します。

{
  "type": "stdio",
  "command": "python",
  "args": [
    "${PLUGIN_ROOT}/server/main.py",
    "--config",
    "${PLUGIN_ROOT}/config.json"
  ]
}

${PLUGIN_ROOT}はプラグインのルート、${PLUGIN_DATA}は更新後も保持される書き込み可能なデータ領域を表します。

なお、mcp.jsonは配布物の一部です。アクセストークン、APIキー、パスワードなどをheadersやenvへ直接書き込まないでください。Agent Plugins 1.0では、認証情報を参照する共通フィールドや共通OAuth設定は定義されておらず、認証は各クライアント側で管理されます。(Agent Plugins)

Copilot固有ファイルをcom.github.copilotへ移す

カスタムエージェント、コマンド、ルール、フックは、プラグインルートのcom.github.copilot/へ移します。

com.github.copilot/
├── agents/
│   ├── reviewer.agent.md
│   └── planner.agent.md
├── commands/
│   └── create-release.md
├── rules/
│   └── coding-standards.md
└── hooks/
    └── hooks.json

Agent Plugins 1.0におけるフック設定の標準的な配置場所は、次のパスです。

com.github.copilot/hooks/hooks.json

既存のCopilot形式でルート直下に置いていたhooks.jsonとは場所が異なるため、単純に$schemaだけを追加するとフックが読み込まれなくなる可能性があります。

VS Code、Copilot CLI、GitHub Copilotアプリはcom.github.copilot名前空間を認識します。一方、名前空間に対応していないクライアントはこのディレクトリを無視するため、スキルやMCPサーバーの共通利用には影響しません。(Visual Studio Code)

Copilot固有のmanifestデータをextensionsへ分ける

クライアント固有のmanifestデータが必要な場合は、plugin.jsonのextensionsへ格納します。

基本形は次のとおりです。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-dev-tools",
  "extensions": {
    "com.github.copilot": {
    }
  }
}

ただし、空のcom.github.copilotオブジェクトを形式的に追加する必要はありません。GitHub Copilotが定義している固有設定を使用する場合だけ、その仕様に従って記述します。

独自に考えたプロパティを追加しても、クライアントが認識しなければ機能しません。Copilot固有ファイルを配置するだけで足りる場合は、com.github.copilot/ディレクトリのみを作成します。(Agent Plugins)

ローカル環境で移行後のプラグインをテストする

Copilot CLIからインストールする

Copilot CLIでは、ローカルディレクトリを指定してプラグインをインストールできます。

copilot plugin install ./my-plugin

絶対パスでも指定できます。

copilot plugin install /path/to/my-plugin

インストール状態は次のコマンドで確認します。

copilot plugin list

変更後に確認する項目は次のとおりです。

プラグインがエラーなく読み込まれる
skills/内のスキルが認識される
mcp.jsonのMCPサーバーが起動または接続される
com.github.copilot/agents/のエージェントが表示される
コマンド、ルール、フックが従来どおり動作する

Copilot CLIは、GitHubリポジトリ、リポジトリ内のサブディレクトリ、Git URL、ローカルパスからプラグインをインストールできます。(GitHub Docs)

VS Codeでローカルプラグインを読み込む

VS Codeでは、settings.jsonのchat.pluginLocationsにローカルディレクトリを登録できます。

{
  "chat.pluginLocations": {
    "/path/to/my-plugin": true
  }
}

Windowsでは、JSON内のバックスラッシュをエスケープします。

{
  "chat.pluginLocations": {
    "C:\\development\\my-plugin": true
  }
}

読み込み後は、スキル一覧、MCPサーバー一覧、カスタムエージェント、スラッシュコマンド、フックの実行状況を確認します。

プラグインが表示されない場合は、次を確認してください。

chat.plugins.enabledが有効になっている
plugin.jsonがプラグインルートにある
$schemaのURLに入力ミスがない
nameが小文字、数字、ハイフン、ピリオドの規則を満たしている
スキルのディレクトリ名とSKILL.md内のnameが一致している
更新を配布する場合はplugin.jsonのversionを上げている

VS Codeは、正規の$schemaが設定されたルートのplugin.jsonを検出すると、Agent Plugins 1.0形式として扱います。$schemaのない既存プラグインについては、従来のCopilot形式として読み込みます。(Visual Studio Code)

Agent Plugins 1.0移行で失敗しやすいポイント

失敗例	起こり得る問題	対応
既存の`plugin.json`へ`$schema`だけを追加する	エージェントやフックなどが期待どおり読み込まれない	ファイル配置も同時に変更する
`skills`フィールドをそのまま残す	Agent Plugins 1.0の標準フィールドとして扱われない	スキルを`skills/`の固定位置へ移す
`SKILL.md`を深い階層へ置く	スキルが検出されない	`skills/<スキル名>/SKILL.md`にする
MCP設定を`.mcp.json`のままにする	標準のMCP設定として検出されない	ルートに`mcp.json`を作る
MCPサーバーの`type`を書かない	接続方式を判定できない	`stdio`または`streamable-http`を明示する
`plugin.json`に独自フィールドを直接追加する	スキーマ違反として無視される	クライアント固有データは`extensions`へ移す
Copilot固有機能をすべてルート直下に残す	他クライアントとの共通化が不完全になる	`com.github.copilot/`へ分離する
`mcp.json`にAPIキーを記載する	認証情報がリポジトリや配布物へ混入する	クライアント側の認証機能を使用する
移行と同時に旧版を削除する	問題発生時にすぐ戻せない	検証完了までは旧版や旧ブランチを保持する
更新時にversionを変更しない	マーケットプレイスやVS Codeで更新が検出されない	`plugin.json`と必要な配布情報のversionを更新する

特に注意したいのは、「旧形式と新形式のフィールドを1つのmanifestに混在させれば互換性を維持できる」と考えないことです。

正規の$schemaを宣言すると、対応クライアントはAgent Plugins 1.0の意味でmanifestを解釈します。旧形式のフィールドを保険として残すのではなく、必要なCopilot固有機能をcom.github.copilot/へ正しく移してください。(Visual Studio Code)

安全に移行するための実務的な進め方

大規模なプラグインでは、次の順序で移行すると切り戻しやすくなります。

移行用ブランチを作る

現行版へ直接変更を加えず、Agent Plugins 1.0用のブランチを作成します。

git switch -c migrate-agent-plugins-1

共通部分を先に移す

最初にplugin.json、skills/、mcp.jsonだけを整備し、Copilot固有機能を除いた状態で検証します。

この段階では、次の点を確認します。

manifestがスキーマに適合する
すべてのスキルが認識される
MCPサーバーが起動する
ファイルパスがプラグインルート外を参照していない

Copilot固有機能を追加する

共通部分が動作した後に、エージェント、コマンド、ルール、フックをcom.github.copilot/へ移します。

問題が発生した場合に、共通部分の不具合なのか、Copilot固有部分の不具合なのかを切り分けやすくなります。

対象クライアントごとに確認する

少なくとも、実際に配布するクライアントで個別に確認します。

確認対象	主な確認内容
VS Code	スキル、MCP、エージェント、コマンド、ルール、フック
Copilot CLI	インストール、スキル呼び出し、MCP接続、エージェント、コマンド
GitHub Copilotアプリ	対応するプラグイン機能とMCP接続
その他の対応クライアント	`skills/`と`mcp.json`が読み込まれること

他クライアントでcom.github.copilot/が読み込まれないことは不具合ではありません。名前空間を実装していないクライアントが、固有部分を無視するのはAgent Plugins 1.0の想定どおりの動作です。

検証後に旧構成を整理する

すべての対象クライアントで動作を確認してから、不要になった旧形式のファイルや設定を削除します。

旧形式を引き続き必要とするクライアントがある場合は、1つのmanifestへ無理に混在させるのではなく、別パッケージや別ブランチとして維持する方が管理しやすくなります。

組織で利用している場合の管理設定

Copilot BusinessやCopilot Enterpriseでプラグインを管理している場合、Agent Plugins 1.0専用の新しい管理ポリシーを作る必要はありません。

既存の管理設定を引き続き利用できます。

設定	用途
`enabledPlugins`	特定のプラグインを自動インストールまたはブロックする
`extraKnownMarketplaces`	組織で利用できるマーケットプレイスを追加する
`strictKnownMarketplaces`	管理対象マーケットプレイス以外からのインストールを制限する

Agent Plugins 1.0はmcp.jsonを通じてMCPサーバーを配布できるため、組織ではプラグインの許可だけでなく、MCPサーバーのURL、コマンド、サーバー名に対する許可リストも併用することが重要です。(The GitHub Blog)

Agent Plugins 1.0への移行は段階的に進める

Agent Plugins 1.0への移行で行う作業は、主に次の4点です。

plugin.jsonへ正規の$schemaを追加する
スキルをskills/<スキル名>/SKILL.mdへ配置する
MCP設定をルートのmcp.jsonへ移す
Copilot固有ファイルをcom.github.copilot/へ分離する

既存のGitHub Copilotプラグインに強制移行はありません。現在のプラグインが安定しており、Copilot以外へ配布する予定もない場合は、急いで変更しなくても問題ありません。

一方、VS CodeとCopilot CLIで同じプラグインを共有したい場合や、クライアントごとに重複したパッケージを管理している場合は、Agent Plugins 1.0へ移行する価値があります。

まず移行用ブランチでplugin.json、skills/、mcp.jsonを整備し、その後にcom.github.copilot/へ固有機能を移してください。すべての対象クライアントで検証してから旧構成を削除することで、既存ユーザーへの影響を抑えながら安全に共通化できます。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

Agent Plugins 1.0への移行手順｜plugin.json・skills・mcp.jsonの新構成

Agent Plugins 1.0とは

Agent Plugins 1.0へ移行すべきか判断する

Agent Plugins 1.0のmanifest構成：VS Code・Copilot CLI共通化の考え方

既存のCopilot形式における代表的な構成

Agent Plugins 1.0へ移行した後の構成

Agent Plugins 1.0への移行手順

現在のプラグインを分類する

plugin.jsonに$schemaを追加する

スキルをskills/へ配置する

MCP設定をmcp.jsonへ移す

Copilot固有ファイルをcom.github.copilotへ移す

Copilot固有のmanifestデータをextensionsへ分ける

ローカル環境で移行後のプラグインをテストする

Copilot CLIからインストールする

VS Codeでローカルプラグインを読み込む

Agent Plugins 1.0移行で失敗しやすいポイント

安全に移行するための実務的な進め方

移行用ブランチを作る

共通部分を先に移す

Copilot固有機能を追加する

対象クライアントごとに確認する

検証後に旧構成を整理する

組織で利用している場合の管理設定

Agent Plugins 1.0への移行は段階的に進める

この記事を書いた人

コメント

コメントするコメントをキャンセル

Agent Plugins 1.0への移行手順｜plugin.json・skills・mcp.jsonの新構成

Agent Plugins 1.0とは

Agent Plugins 1.0へ移行すべきか判断する

Agent Plugins 1.0のmanifest構成：VS Code・Copilot CLI共通化の考え方

既存のCopilot形式における代表的な構成

Agent Plugins 1.0へ移行した後の構成

Agent Plugins 1.0への移行手順

現在のプラグインを分類する

plugin.jsonに$schemaを追加する

スキルをskills/へ配置する

MCP設定をmcp.jsonへ移す

Copilot固有ファイルをcom.github.copilotへ移す

Copilot固有のmanifestデータをextensionsへ分ける

ローカル環境で移行後のプラグインをテストする

Copilot CLIからインストールする

VS Codeでローカルプラグインを読み込む

Agent Plugins 1.0移行で失敗しやすいポイント

安全に移行するための実務的な進め方

移行用ブランチを作る

共通部分を先に移す

Copilot固有機能を追加する

対象クライアントごとに確認する

検証後に旧構成を整理する

組織で利用している場合の管理設定

Agent Plugins 1.0への移行は段階的に進める

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

コメントするコメントをキャンセル