UIレビュー用のskillとPlaywright系MCPを一つのdirectoryへまとめ、VS CodeとCLIの両方へ配りたい。Agent Plugins 1.0は、こういう用途にかなり素直なpackage形を用意しています。

ただし、両方のhostがpackageを認識した時点で「portableになった」と判定するのは早いです。

持ち運べたのはskillやMCP設定の梱包です。file writeの承認、network access、secretの扱い、sandboxまで同じになったわけではありません。自分なら本作業に入る前に、package検査とは別のtrust preflightを通します。

この記事では、次の順番を使います。

package validation
  -> capability inventory
  -> host policy check
  -> read-only canary
  -> negative tests
  -> accept / reject per host

仕様が運ぶ範囲を先に固定する

例として、frontend review用pluginを次のdirectoryへまとめます。

frontend-review-plugin/
├── plugin.json
├── skills/
│   └── ui-review/
│       └── SKILL.md
└── mcp.json

plugin.jsonがpackageの入口、skills/が再利用する手順、mcp.jsonがMCP接続の設定面です。具体的なfieldや必須・任意の条件はAgent Plugins 1.0.0の仕様に合わせます。ここでは仕様にないfieldを足して、permission設定まで表現できるようには見せません。

directory shapeが揃えば、skillとtoolを一つの単位として配りやすくなります。ここで揃うのはpackage contractです。host上のpermission systemやsandbox、trust判断は別に確認します。

GitHub側にはVS Code、Copilot CLI、Copilot appでの対応に加え、managed settingsやMCP allowlistの運用があります。これは具体的な実装例として参考になりますが、別のagent hostにも同じcontrolがあるとは限りません。

「portable」の目的語を曖昧にしないほうがよいです。

portable package: 同じartifactを配布・認識できる
equivalent execution: 同じ権限、制限、secret処理で動く

前者を確認しただけでは、後者のtestは終わっていません。

検査を4層に分ける

自分はpackageの導入判定を4層へ分けます。この4層はAgent Pluginsの公式用語ではなく、チーム側の運用です。

層	検査するもの	主な所有者
package contract	必須file、JSON syntax、skill path、参照先	仕様とpackage作者
capability inventory	MCP server、command / URL、環境変数、外部通信	package作者と導入者
host policy	install元、allowlist、write範囲、network、approval、sandbox	各hostと導入チーム
evidence	prompt / deny、filesystem diff、uninstall後の残存物	導入チーム

plugin.jsonのsyntaxが正しくても、mcp.jsonから起動するcommandが安全とは限りません。要求能力に問題がなくても、host側にdenyする仕組みがない場合があります。そこで検査結果を層ごとに残します。

package作者が責任を持てる範囲と、実行hostでしか確認できない範囲を一つの「安全」というlabelへ丸めないようにします。

最初のpreflightは地味でいい

まずはfileの存在、JSON syntax、差分を確認します。

set -eu

plugin_dir="frontend-review-plugin"

test -f "$plugin_dir/plugin.json"
test -d "$plugin_dir/skills"
jq -e . "$plugin_dir/plugin.json" >/dev/null

test ! -f "$plugin_dir/mcp.json" \
  || jq -e . "$plugin_dir/mcp.json" >/dev/null

git diff -- \
  "$plugin_dir/plugin.json" \
  "$plugin_dir/mcp.json" \
  "$plugin_dir/skills"

jqで分かるのはJSONとして読めるかだけです。schema validationの代わりにはなりません。公式validatorが提供されている環境では、そちらも使います。

最後のgit diffは自動判定ではなく、人が見るために残しています。とくに確認したいのは次です。

想定外のskillが増えていないか
mcp.jsonへ知らないserver、command、引数、URLが入っていないか
secretの実値がpackageへ混ざっていないか
package外のpathを参照していないか

MCP serverの名前だけを見て終えると、実行commandや接続先の変更を見落とします。plugin更新時にはlockfileのように差分を読み、能力が増えたら再承認する運用が必要です。

trust条件はteam-owned policyへ置く

permissionやnetwork条件を、仕様外のfieldとしてplugin.jsonへ押し込むのは避けます。代わりに導入チームが検査用fileを持ちます。

# plugin-policy.yml
# Agent Pluginsの公式schemaではない。導入前の期待条件を記録するfile。
package: ./frontend-review-plugin

expected_mcp_servers:
  - playwright

secrets: env-only

hosts:
  vscode:
    write_scope: worktree-only
    network: deny-unless-reviewed
    approval: required

  copilot-cli:
    write_scope: worktree-only
    network: deny-unless-reviewed
    approval: required

このYAMLをVS CodeやCopilot CLIが直接読み込む想定ではありません。「このhostを採用するなら満たしてほしい条件」をreview可能な形にしただけです。

各項目の結果はpass / fail / unsupported / not-testedで残します。hostに該当controlがなければ、package側で安全そうな説明を足すのではなくunsupportedです。チームの必須条件なら、そのhostはrejectします。

client固有のinstall commandはversionで変わり得るため、ここでは固定しません。packageを読み込む部分は各clientの現行手順に従い、読み込み後の検査を同じにします。

read-only canaryで「認識」と「実行」を分ける

最初から実装taskを渡すと、skill選択、command実行、file変更、network accessが一度に起きます。どこでpolicyが効いたのか追えません。

最初のtaskは、書き込みもnetworkも不要なものに絞ります。

このrepositoryのpackage.jsonを読み、scripts名だけを列挙する。
file変更、command実行、network accessは行わない。

VS CodeとCopilot CLIで同じcanaryを走らせ、結果を別々に記録します。

check	VS Code	Copilot CLI
package recognized	pending	pending
skill selected	pending	pending
file changed	pending	pending
command executed	pending	pending
network used	pending	pending

package recognizedとskill selectedは別々に判定します。package一覧へ出たことは、意図した場面でskillが選ばれた証拠にはなりません。

同様に、agentが会話で「変更していません」と答えただけでは弱いです。git statusやfilesystem diff、host側の実行logを証拠にします。

negative testは3つだけ先に通す

canaryが通ったら、禁止したい動作を小さなtest環境で要求します。本番repositoryや本物のcredentialは使いません。

1. file write

使い捨てのworktreeでfile変更を依頼し、approval promptまたはdenyが記録されるかを見ます。変更できたかどうかだけでなく、誰が、どのpathに、どの承認を経て書いたかを残します。

2. allowlist外のMCP

未許可のMCP serverを使うtaskを与えます。期待する結果は、利用不可として止まるか、明示的なapprovalへ進むことです。勝手に代替serverへ接続した場合はfailにします。

3. 未承認network access

未承認URLへのaccessを要求し、team policyどおりdenyまたはapprovalになるかを確認します。agentの返答ではなく、hostのprompt、deny記録、network logを見ます。

追加で、必要な環境変数を外した状態も試します。secretを推測したり別の保存場所から拾ったりせず、入力不足として停止するのが期待値です。

最後にuninstallし、skill、MCP設定、credential参照が残っていないかを確認します。導入時だけ見ていると、この後片付けを忘れがちです。

hostごとにaccept / rejectする

結果はpackage単位の一つの判定ではなく、hostごとに残します。

| check | VS Code | Copilot CLI |
|---|---|---|
| package recognized | not-tested | not-tested |
| read-only canary | not-tested | not-tested |
| file-write approval | not-tested | not-tested |
| MCP allowlist | not-tested | not-tested |
| network policy | not-tested | not-tested |
| clean uninstall | not-tested | not-tested |

上の表はtemplateです。実測した結果ではありません。最初からpassで埋めず、検査していない項目をnot-testedのまま見せます。

判定に残す情報はこの程度で足ります。

package commit
host / version
install source
capability inventory
canary result
negative-test result
filesystem diff
uninstall result
known unsupported controls

VS Codeでは必須条件を満たし、CLIではnetwork controlがunsupportedだった。そういう結果なら、VS Codeだけをallowlistへ残せばよいです。同じpackageを読めることを理由に、判定まで共通化する必要はありません。

Agent Plugins 1.0を使うと、同じskillとMCPを複数hostへ配りやすくなります。配布先が増えたときに頼れるのは、「どこでも動くはず」という期待より、plugin-policy.yml、canary、negative testの記録です。

自分なら導入完了の条件をpackage recognizedには置きません。hostごとの証拠が揃ったところを完了にします。

参考資料