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 首次发布