agent-plugins-spec：六家大厂把 Agent 插件格式统一了，唯独 MCP 的作者没到场

这份规范的讨论区里，有人直接问了一句：厂商真的会跟进吗。这条提问挂了 8 天没人搭理，第一个回复来自另一个开发者，他把自己刚发布的跨端导出 SDK 贴了上来。直到 6 月 3 日才出现一个像样的观察：Goose 似乎在采纳它，那会是个大新闻，因为 Goose 是 AAIF 旗下的项目；除此之外，外面几乎看不到别的动静。

这段话就发生在 agent-plugins-spec 仓库里。仓库描述写得很直白，它是一份把 Agent 扩展打包成可分发插件的标准。官网首页列出的技术指导委员会由 Amazon、Cursor、Microsoft、OpenAI、Vercel 五家的核心维护者组成，Google 在 8 月 6 日宣布加入。截至 2026 年 10 月 8 日，仓库挂着 1368 颗星、75 个 Fork。

真正让这件事变得有意思的地方在名单之外。MCP 是 Anthropic 做出来的，Agent Skills 的 SKILL.md 格式也是 Anthropic 先提的，而这份把两者打包到一起的规范，指导委员会里没有 Anthropic 的位置，兼容客户端列表里也找不到 Claude Code。名单上站的是 Kiro、VS Code、GitHub Copilot、ChatGPT 与 Codex、Cursor，外加 OpenHands、OpenClaw、NanoClaw、Hermes Agent 这几个开源客户端。

这篇文章不打算复述它的目录结构，那些你打开官网就能看到。我想说清楚的是三件事：它实际规定了什么、谁真的需要它、以及一份只有两个必填字段的清单，凭什么让六家大厂坐进同一间会议室？

真正被规定的只有两个位置

规范正文里，能被客户端自动发现的东西只有两样。Skills 固定在 skills/ 目录下，每个含 SKILL.md 的直接子目录算一个技能；MCP server 固定在根目录的 mcp.json 里。plugin.json 不能重定向这两个位置，也不能把它们内联进清单。

这个限制看着像是功能缺失，其实是整份规范里最硬的设计决策。同类项目里，Client 侧原本最烦的工作就是猜测组件的发现路径，一个客户端读 config/，另一个读 plugins/，还有的把 MCP server 直接塞进主配置文件。固定位置之后，客户端不需要实现任何优先级规则，也不需要维护一张兼容路径表，读不到就是读不到，不用报错。

第三个规定更隐蔽，它管的是越界。规范要求所有插件提供的路径，在文件系统解析之后必须落在插件根目录内部。软链接、junction、重解析点都可以用，但解析结果跑出根目录就算违规。这条规则对的是打包分发场景里最常见的攻击面：插件里塞一个指向 /etc 的链接，客户端照着读，用户的机器就交出去了。

处理越界的粒度是分级的，不是一刀切。plugin.json 自己越界，整个插件被拒绝；固定位置越界，那一种组件类型整体作废；某个 SKILL.md 越界，只跳过这一个技能；MCP 的 command 或 cwd 越界，只跳过这一条 server；其他越界路径，客户端拒绝访问该路径。五个失败边界对应五种不同的收窄方式，每一步都要求客户端只砍最小的那一刀。

这种设计带来的直接好处是组件之间互不牵连。一个 MCP server 启动失败、连不上、认证不过，规范明确要求客户端继续加载这个插件剩下的服务器和其他组件，同时把失败报告出来。一个同时提供技能和 MCP 的插件，不会因为其中一个 server 挂了就完全废掉，失败可见但不扩散。

清单本身是封闭的。plugin.json 只认 $schema、name、version、description、author、homepage、repository、license、keywords、extensions 十个顶层字段，多一个都算 schema 违规。但客户端遇到未知字段时不能因此拒绝插件，只能报告并忽略。想给自家客户端多加配置？塞进 extensions 下的反向域名命名空间，别碰顶层。这个取舍换来的是严格的类型校验和补全支持，代价是客户端厂商失去了自由发挥的地方。

配置和运行环境的隔离也做得很干净。包内文件通过 PLUGIN_ROOT 引用，只读；客户端必须再给一个可写的 PLUGIN_DATA 目录，用来放 node_modules、虚拟环境、缓存这些跨更新要保留的东西。这两个变量由客户端注入，插件自己的 env 里不允许覆盖它们。command 字段则完全不做插值，当成单个可执行 token 处理，要么是裸名字，要么是以 ./ 开头的插件内路径。

这张图画的是规范定义的三段链路。上面是包内的四个固定位置，中间是客户端必须完成的发现与校验动作，下面是启动子进程或建立远端连接时的运行时环境。注意虚线那条：PLUGIN_DATA 由客户端创建并注入，插件只能使用，不能声明。

值得留意的是，规范在三处刻意留了白。权限模型没定义，沙箱没定义，密钥怎么给也没定义。FUTURE_CONSIDERATIONS.md 把这些连同签名验证、依赖解析、审计事件一起列了出来，并且明说它们不属于一致性要求，也不承诺进哪个版本。

一个最小插件只要两个文件

装它不需要任何工具，也不需要 npm 或者 pip。插件本身就是一个目录，只要目录里放着清单和技能文件，能识别这套格式的客户端就会认。

mkdir -p hello-plugin/skills/greet
cat > hello-plugin/plugin.json <<'EOF'
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}
EOF

技能文件就是一份带 frontmatter 的 Markdown，和你在 Claude Code 里写的 SKILL.md 是同一个格式，因为 Agent Skills 那份规范才是格式的权威来源，这里只管怎么发现它。

---
name: greet
description: Greet the user and offer help.
---

Greet the user and offer help.

要让插件顺带带一个 MCP server，再写一个 mcp.json。三种传输方式各自有明确字段，不靠猜形状来推断类型。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "env": { "CONFIG": "${PLUGIN_ROOT}/config.json" },
      "cwd": "${PLUGIN_ROOT}"
    }
  }
}

终端里这几条命令就是全部准备工作。一个清单加一份 SKILL.md，两行有效 JSON 加四行 frontmatter，扔进任何兼容客户端的技能目录就能认。真正的门槛不在写，在于写完之后没人能替你检查。

真正的坑集中在校验环节，而且没有一个是无关紧要的小问题，下面这四条中的每一条，都会让插件在某一类客户端上直接失效。

• 官方没有提供校验器。FUTURE_CONSIDERATIONS.md 明确写着 v1.0.0 没有定义测试工具或 linter，当前唯一的调试方式是把插件丢进真实客户端看结果。
• 两个 schema 里的正则不可移植。plugin.schema.json 的 name 用了否定前瞻，mcp.schema.json 的 cwd 用了非捕获组，这些都是 JSON Schema 推荐的可移植子集之外的东西，Go 的 regexp 这类基于 RE2 的校验器直接编译不了。
• 密钥无处安放。规范禁止把凭据写进 env 或 headers，但没有给出替代机制，秘密注入完全交给客户端，1.0.0 阶段没有任何跨客户端可用的做法。
• 清单里没有 id 字段。仓库的提交历史显示，5 月份一度想把 URL 风格的溯源 id 设为必填，最后被移除了，插件身份的唯一标识目前只有 name。

什么时候该用，什么时候纯属给自己加活

判断标准其实只需要一句话：你的技能和 MCP server 是不是需要一起动、并且要去不止一个客户端。

反过来，下面这几种情况就别折腾了，用了只会凭空多出一层包装，外加一份需要自己盯着的清单。

• 你只给一个客户端写插件，直接用它的原生格式，规范提供的可移植性对你毫无价值。
• 你需要权限声明、签名验证、密钥托管中的任何一项，现在就得等，1.0.0 把这四件事全部推给了未来版本。
• 你的主要目标是 Claude Code 生态，两个格式的清单路径不一样，你仍然要维护两份包装。
• 你需要插件之间互相依赖，或者需要一个插件市场来分发，这两件事都被明确排除在核心范围之外。

谈替代方案的时候，得先把层次分清楚。MCP 管的是 Agent 怎么调用工具，Agent Skills 管的是怎么教模型使用工具，这份规范管的是把它们装进同一个盒子。所以它不会替换你已有的 MCP 集成，只是给集成加一层包装。真正的竞品不是某个协议，而是每个客户端自己那套插件格式，以及什么都不装、直接手写配置的原生做法。

Star 数很漂亮，提交记录不太经看

治理文件倒是写得很认真。GOVERNANCE.md 规定治理角色由个人持有而不是组织，任何单一厂商都不能占核心维护者席位多数，核心维护者由指导委员会多数票晋升，Lead Core Maintainer 需要 75% 的超级多数才能罢免。一套看起来能防住厂商绑架规则的设计。

不过规则写得漂亮和规则被执行是两件事。Google 在 8 月 6 日宣布派出 Kevin Hou 加入核心维护者，同一天有个外部贡献者提了 PR 加上这一行名单，直到今天这个 PR 还挂着没合。仓库里的 MAINTAINERS.md 至今只有五家，Google 不在其中。官方博客说 Google 已经进场，治理文件说没有，两个口径差了两个月。

社区声音方面，讨论区并不热闹。除了开头那条追问，我翻到的公开反馈里最实在的一句来自 6 月 3 日那位回复者：Seems like Goose is adopting it, which would be huge as it’s an AAIF project. But other than that I haven’t found a lot of mentions in the wild yet。三个月过去，这句话依然成立，热度集中在发布那两周，之后是长尾的沉默。但这份沉默到底说明规范已经定稿、不需要再讨论，还是说明大家已经不太关心了，得看后面两个月。

这更像一份政治文件

我对它的判断很简单：这不是一个技术项目，是一份划边界的文件。规范里真正被解决的问题只有包装格式，而坐在桌子边的人解决的是另一个问题——Agent 生态的插件分发权归谁定义。把六家大厂的格式统一到一份 42 KB 的文本上，收益不在工程，在话语权。

这个判断的前提是承认，它管的事情窄得反常。v1.0.0 只收 Agent Skills 和 MCP 两种组件类型，原因写在设计决策那一节：hooks、slash commands、子 Agent、规则文件、LSP server 都被认为太客户端化，没有跨客户端共识，所以一律不收。这个克制是对的，一份试图定义一切的标准通常活不到第二版。

代价是它把最难的部分全部推后了。权限、沙箱、溯源、密钥、企业策略、审计，这六件事在 FUTURE_CONSIDERATIONS.md 里排成了清单。所以从今天起用它，你得到的是可移植的包装和一份明确的失败处理约定，同时继承了一套完全没有安全边界的运行时模型。装上第三方插件，仍然等于让第三方代码以客户端给它的权限跑起来。

Anthropic 缺席这件事，值得单独说。Claude Code 现在用自己的 .claude-plugin/plugin.json，MCP 配置放在 .mcp.json，hooks 和 agents 都是一等公民，与这份规范不兼容。但两边的差异全是路径层面的东西，是最容易对齐的那类不一致。真正的分歧不在文件放哪，在于 Claude Code 的插件模型里有一批拿得出手的组件类型，而 v1 明确不要它们。

这张卡片把三种做法并排放在一起看。左边是 Agent Plugins 1.0 的克制版本，中间是 Claude Code 现在的方案，右边是根本不打包、每个项目自己手写 MCP 配置的做法。差异最集中的一行不在清单路径，而在 hooks 和子 Agent 这两类组件的归属。

趋势上我也有些保留。规范文本在 7 月完成公开发布，1.1.0 工作草案在 8 月 15 日开出来，用文件体积对一下就知道里面改了什么：spec/1.1.0.md 比 1.0.0.md 少 14 个字节，全部改动就是版本号、状态标识，以及把几处 v1 专属的措辞泛化。主分支最后一次提交停在 8 月 19 日，之后七周没有新东西进来。

这个状态有两种解释。一种是发布完成后的自然静默，规范项目的节奏本来就慢，等实现方反馈再动是正常的。另一种是维护能量耗尽了，看着 9 个未合并的 PR 里有两个是修 schema 缺陷的、还有一个是加维护者名单的，后一种解释也不能完全排除。未来两个月能不能出现一次实质合并，基本就能定性，这一点值得记下来。

资源地址

先别急着迁移

如果你手上正好有一份要同时供给 Cursor 和 GitHub Copilot 的技能包，现在就动手，成本接近零：加一个两行的 plugin.json，把技能目录搬进 skills/，MCP 配置改名 mcp.json 并给每条 server 补上 type。你不是在重写，只是在改目录名。

如果你还在观望，盯两个信号就够了。一个是那两个修 schema 正则的 PR 有没有合进正式版本，不可移植意味着 Go 写的校验器全部被拦在门外，这决定了工具链能不能长出来。另一个是 #37 那个只加了一行的 PR 什么时候合，名单挂两个月，反映的是治理流程的实际吞吐，而不是流程设计得多好。

那份规范里唯一让我觉得心动的地方，是它把失败边界写到了五个层级。一份讲打包的文档愿意花这么多篇幅规定”出错时该砍哪一刀”，说明起草的人真的实现过客户端。这种务实通常比愿景更耐看。