Google 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 裡也按名稱空間放	別的客戶端必須能忽略

事實來自 2026-08-06 的 Agent Plugins 1.0.0 規範、Vercel 的發布說明，以及同日 Google Developers Blog。訂單 A-1042 和 orders.example.com 是虛構的。

它把技能和 MCP 收進一個可搬走的目錄

2026 年 8 月 6 日，Agent Plugins 1.0.0 公開。維護組當時的核心維護者來自 Amazon、Cursor、Microsoft、OpenAI 和 Vercel。同一天，Google Developers Blog 寫明：Google 以 Kevin Hou 為代表加入這個組，並開始在自己的產品裡做支援。所以這不是 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 伺服器地址寫進 plugin.json」開始：

1. 先寫根目錄 plugin.json。只放閉合欄位表裡的鍵。name 用 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 不在，客戶端載入現有的部分，不算錯誤。缺必填欄位或名字不合法，才拒絕整包。

mcp.json 和 plugin.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 首次發布