「寫一次，到處都能跑」很誘人，也很容易讓團隊高估 agent plugin 的可攜性。

同一個 plugin 在 VS Code 找得到，在 CLI 也載入成功，只能證明套件送到了。MCP 依賴是否真的綁上、權限被拒絕時會走哪條路、失敗後能不能留下可重現的證據，仍然取決於各個 client 的執行環境。

Agent Plugins 1.0 讓一個套件可以帶著 skills 與 MCP 設定，在 VS Code、Copilot CLI、GitHub Copilot SDK 和 Copilot app 等相容 client 之間分發；client 專屬行為則能留在各自的 namespaced directory。這解決了不少重複安裝與設定漂移，但它處理的是分發單位，不是跨 client 的執行等價性，更不是所有廠商都適用的通用 plugin 標準。

團隊如果把「安裝成功」當成「工作流可用」，問題通常會在上線後才出現。

可攜性其實有四層

我會把一個 agent plugin 拆成四份契約來管理，而不是只看 manifest 能不能被讀取。

1. Core skill contract

先定義這個 skill 到底承諾什麼：輸入格式、任務範圍、預期輸出、停止條件，以及失敗時必須回傳的狀態。

例如，外部 reader 無法使用時，skill 應該回傳 dependency_unavailable，而不是改用模型記憶湊出一份看似合理的答案。這條規則要由共用 skill 決定，不該讓每個 client 自由猜測。

2. Dependency contract

列出 MCP server 或外部服務的版本、連線條件、credential 來源，以及依賴不可用時允許的降級方式。

「設定檔裡有 MCP」不代表 runtime 已完成 binding。client 可能找得到 plugin，卻因為啟動方式、環境變數或驗證流程不同，根本沒有把所需工具接上。

3. Permission contract

檔案、網路、credential 與 tool scope 要分別寫清楚，也要定義哪些動作需要 approval。

同一個唯讀研究任務，在 IDE 裡可能能讀 workspace，在 CLI 裡卻從另一個工作目錄啟動；某個 client 遇到未知網域會詢問使用者，另一個則直接拒絕。這些差異不能藏在「支援此 client」一句話裡。

4. Client adapter contract

最後才是 client adapter。它負責 discovery、設定位置、事件格式，以及 UI 或 CLI 的互動差異，但不應偷偷改掉核心任務的成功標準。

adapter 可以不同，驗收結果不能各說各話。

除了 manifest，再交一份 release envelope

下面不是 GitHub 官方的 Agent Plugins schema，而是一份由團隊自行維護的發佈資料。欄位和值都只是示意，重點是讓每次升版都有可追查的測試邊界。

plugin_id: genui-research
plugin_version: 1.4.0
skill_version: 3

tested_clients:
  vscode: org-baseline-2026-08
  copilot_cli: org-baseline-2026-08

mcp_dependencies:
  resource_reader: team-pin-2026-08

required_scopes:
  files: read-only
  network: fixture-origin-only
  credentials: none

acceptance_fixture: fixtures/genui-research-v3.yaml
evidence_path: evidence/genui-research/1.4.0/
rollback_to: 1.3.2

這份 envelope 應跟著 plugin source 進版控。tested_clients 記錄實際測過的組合，不要寫一個模糊的 all；rollback_to 也必須指向上一個通過相同驗收流程的版本，而不是「目前看起來還能用」的資料夾備份。

用同一個 fixture 測所有 client

假設團隊有一個 genui-research plugin，共用 skill 會從固定的公開資源集合尋找 Generative UI 資料。驗收時可以選用 Awesome Generative UI 的生成式 UI 資源頁 當測試來源，要求每個 client 找出兩筆與 MCP Apps UI 直接相關的資源，保留標題、公開連結與判定理由。

這個頁面只是人為整理的公開資源目錄，不是 Agent Plugin，也不是 MCP server。真正要測的是 plugin 能否透過指定的 reader 完成相同任務。

fixture 至少要固定這些條件：

• 只能使用指定的 resource_reader，不可用時必須明確失敗。
• 回傳兩筆結果，且都要落在團隊版控的接受清單內。
• 保留 tool binding 與執行證據，不能只比對最後一段文字。
• 任務只需讀取公開資料，不得要求專案寫入或 credential。

不要比較兩個模型寫出的理由是否一字不差。該比的是任務結果、來源連結、工具綁定、權限行為與證據是否完整。

一個很容易被誤判的失敗案例

以下是一份精簡的相容性矩陣：

CLI 端雖然顯示 plugin 已載入，甚至可能憑模型既有知識產生兩個像樣的結果，這一版仍然不能 promote。因為它違反 dependency contract，也沒有證明 deny path 與 rollback 可用。

這正是只做 happy path 測試會漏掉的地方。輸出看起來正確，不代表工作流按照約定完成。

發佈流程不要在 production 現場補洞

一個可維護的流程不需要很花俏，但每一步都要留下東西：

1. 從版控中的 source 建立不可變的 plugin package 與 release envelope。
2. 在每個宣稱支援的 client 執行同一份 fixture，保存矩陣和失敗證據。
3. 只有完整通過的 package 才能 promote；不要在安裝後手改 client 專屬檔案。
4. adapter 變更時，只重跑受影響的矩陣格子，但核心 skill 或依賴版本變更時要重跑全部。
5. 回退到上一個已驗證版本，再執行一次最小 smoke test，確認舊版仍符合目前的 client baseline。

同一波 coding-agent 更新往往還會帶來 task queue、平行 subagent、rewind、memory 與 model choice 等不同工作流能力。plugin 進入這些 client 後，執行生命週期本來就不會只剩下一種。把差異寫進測試矩陣，比假設平台會替你抹平差異可靠得多。

套件裝得上，只代表配送完成。當團隊能回答某一版在哪些 client、哪些依賴與哪些權限下通過測試，也能指出失敗證據和回退版本時，這個 plugin 才算是可維護的軟體，而不是一份被複製到很多地方的設定資料夾。

來源備註

• Agent Plugins 1.0 in VS Code, Copilot CLI, and the Copilot app
• GitHub Copilot weekly releases — August 10