Agent Plugins 是 Agent Skills 的未来（13 分钟阅读）

Agent Plugins 是 Agent Skills 的未来

Agent Plugins 是一个开放、供应商中立的標準，用于将 Agent Skills 及其依赖的 MCP 服务器打包到一个可移植文件夹中，任何兼容客户端都可以加载。Google 正在以核心维护者身份加入技术指导委员会。发布帖涵盖了这一公告，规范提供了详细信息。以下是我们通过真实技能实践后所学到的东西。

Agent Skills 为 agent 提供了按需的专业能力。一个指令文件夹，只有当任务匹配时模型才会拉取，因此你的上下文窗口不会在修复 CSS bug 时还带着一份部署运行手册。我们一直非常依赖这一点，无论是 google/skills 仓库，还是 Agents CLI 随附的七个技能。

Skills 从未解决的是分发问题。作者：@lavinigam，Google Cloud 开发者关系工程师

一个需要工具的技能是两个构件。指令位于 SKILL.md 中，工具位于 MCP 服务器中，而没有任何东西将它们绑定在一起。因此，这种绑定关系只能写在 README 里：把这个复制到这里，把那段 JSON 块加到那里，每个客户端都有不同的片段。每个客户端都发明了自己的捆绑格式来解决这个问题，于是作者选择一个，然后为下一个客户端重写。

Agent Plugins 将“盒子”标准化。里面的组件本来就已经是可移植的。以下是当你的技能变成插件后会发生什么变化，以及为什么你已经构建了其中大部分内容：

• 你缺少的那一个文件。 你的文件夹已经是正确的结构了。
• 你的工具随你的专业知识一起移动。 mcp.json，以及能在迁移后存活的路径。
• 组件独立失败。 一个挂掉的服务器不会拖垮你的技能。
• 无需 fork 即可实现客户端特定行为。 扩展命名空间。
• 一个文件夹，适用于每个客户端。 我们发布的内容，以及它实际运行的地方。

你缺少的那一个文件

如果你写过 ADK 技能，看看它所在的位置：skills//SKILL.md，下面还有 scripts/、references/ 和 assets/。Agent Plugins 要求的是 skills//SKILL.md，并将该文件夹内部的内容交由 Agent Skills 规范处理。这是同一棵树。

以下是一个我们已经写好的技能，打包后也没有改变：

注意 Steps 第 1 行假设了什么：一个正在运行的 MCP 服务器。这个依赖正是打包所要修复的东西。迁移只需在根目录添加一个文件：

这两个字段都是必填的，这就是最小的全部内容。名称长度为 1 到 64 个字符，由小写字母、数字、连字符和句点组成，必须以字母数字开头和结尾，并且不能包含 – 或 …。所以 acme.reports 没问题，而 My-Plugin、-start 和 has–double 都不行。

当你准备好发布而不是测试时，清单也可以包含元数据。该 schema 是封闭的：只允许十个顶层字段，其他都不行（完整字段参考）。这是十个中的九个。最后一个是 extensions，用于客户端特定数据，稍后会讲到。author 还可以包含一个可选 email。version 应该是 SemVer，license 应该是 SPDX，不过客户端不会因为格式错误的字符串而拒绝你。错误的 JSON 类型则是另一回事：在应该是字符串的位置出现数字，即使是可选字段也是致命的。

恰好有两种 schema 违规是非致命的：未知的顶层字段，以及不是对象的 extensions 值。这两者都会被报告并忽略，插件仍然会加载。其他一切违规都是致命的，客户端会拒绝整个包。

有一条规则会让迁移到大型技能库的人踩坑。发现机制只深入一层：客户端读取 skills/ 的直接子目录，不会递归（发现规则）。如果你一直在把技能分组到类别文件夹中，那么一旦打包，这些技能就会消失，而且不会有任何错误来解释原因。

你的工具随你的专业知识一起移动

mcp.json 位于清单旁边，声明你的技能所需的服务器。它只包含两个顶层键，每个服务器都明确声明其传输方式：

存在三种传输方式，必填字段各不相同（MCP 服务器参考）：

command 是一个可执行 token，而不是 shell 命令。要么是一个裸名称，由平台搜索规则解析，要么是一个以 ./ 开头的插件相对路径。占位符扩展特意不适用于它，因此捆绑的二进制文件只能通过该 ./ 路径找到，没有其他方式。

这两个占位符是客户端提供给 stdio 子进程的环境变量，它们之间的区别比名称所暗示的更重要：

写入 PLUGIN_ROOT，你的状态会在下次有人更新插件时消失。两者都会在 args、env 值和 cwd 中展开。不会在 environment keys、command、remote URLs 或 headers 中展开。展开是文本性的、单遍的，所以不会嵌套。

Headers 是字面的包数据，任何下载你插件的人都能读取，这就是为什么规范禁止在其中放置凭据。Agent Plugins 1.0.0 根本没有定义可移植的 OAuth 或凭据引用字段。认证仍然由客户端管理。

组件独立失败

如果你的 MCP 服务器无法启动，你的技能仍然会加载。规范要求客户端继续加载其他所有内容，并且应该报告失败而不是吞掉它。对于无效或声明了客户端不支持的传输方式的条目，规范更进一步：客户端必须跳过该条目并继续。

失败在三个级别上界定（失败边界），知道你遇到了哪一个，就解决了大部分调试问题：

缺失也是允许的。没有 mcp.json 的插件并不算损坏，因为缺少组件位置不是错误。位置形式错误，比如 mcp.json 是一个目录，会使该组件类型失效，而其余部分继续加载。

这就是捆绑格式和包格式之间的区别。捆绑包是全有或全无。包格式可以按部分降级，这也是为什么把包含指令和需要访问网络的服务器的一个文件夹交给别人是安全的唯一原因。

无需 fork 即可实现客户端特定行为

Hooks、commands、subagents 和 rules 不在 v1 中。它们过于客户端特定，无法在不冻结某人路线图的情况下进行标准化。规范不是强制一个最低公分母，而是将每个客户端拥有的命名空间交给它。

客户端命名空间可以以反向域目录的形式出现在根目录，也可以以清单中 extensions 下的键的形式出现，或者两者同时出现。两者之间互不依赖。客户端会忽略它们不认识的命名空间，因此可移植核心保持可移植。

如果每个客户端都依赖自己的命名空间而不是核心，同样的机制可能会让插件在下一级目录重新碎片化，这是 v2 被讨论时需要关注的问题。

一个文件夹，适用于每个客户端

今天有两款 Google 产品以 Agent Plugins 的形式发布。Agents CLI 打包了我们的专家技能，用于 agent 构建、评估、部署、可观测性和发布。Data Agent Kit 将 Spanner、Cloud SQL 和 AlloyDB 插件，以及一个覆盖 BigQuery 的入门包，带入你已经使用的任何编码 agent 中。

在 Antigravity CLI 中，只需要一条命令：

其他每个客户端仍然有自己的安装程序，这正是该规范正在弥合的差距：

读取可移植格式的客户端集合正在增长，并且已在 agent-plugins.org/compatible-clients 发布并保持最新。

有一个我们自己实践时得到的警示。符合性允许部分实现：客户端必须至少支持 stdio 和 streamable-http 中的一种，并且应该同时支持两者，而 sse 是可选的。基于这两种现代传输方式中的任何一种构建，你在今天列出的所有环境中都是安全的，但在你承诺插件在另一个客户端中可用之前，请先在第二个客户端中测试。

决定要打包什么

不是所有东西都需要插件。一个没有工具的技能，作为技能本身就很好了。一个客户端配一个服务器，直接用普通的 MCP 配置更简单。当指令和工具必须一起到达多个地方时，才应该使用插件。

当它无法加载时

我们遇到的每个失败在实践中都是静默的，尽管只有第一个是设计上静默的：嵌套过深的目录永远不会被发现，所以客户端没有什么可报告的。对于无效的 SKILL.md，规范说客户端应该报告它，而我们尝试的客户端都没有做到。每个失败都有不同的特征：

目前还没有标准验证器。该项目的非规范性未来考虑文档提出了一个插件 linter，以及针对客户端实现的符合性测试套件，作为未来版本可能定义的内容。没有任何承诺。目前，检查方法是在真实客户端中加载插件并阅读诊断信息。

什么还不能迁移

凭据是第一个缺口。插件不得嵌入密钥，也没有可移植的字段来引用它们，因此任何需要经过认证网关的东西仍然需要每个客户端的设置。文件夹可以移动；认证则留在原地。

第二个是与现有格式的命名冲突。Claude Code 使用 .claude-plugin/plugin.json 和 .mcp.json。Antigravity 使用 mcp_config.json。这些位于可移植布局旁边，而不是在它里面。预计会有一个过渡期，仓库同时携带两者；在调试一个从未被加载的插件之前，先检查客户端实际读取的是哪一个。

有两个状态说明值得记住：ADK 的 Skills 支持仍然是实验性的（Python v1.25.0、TypeScript v0.6.1、Go v1.2.0），Agent Plugins 1.0.0 以工作草案的形式发布。

现在就开始

大约一分钟内构建一个有效插件：

然后从这里开始向外扩展：

• 转换一个真实的东西。 将其指向你已写好的技能。检查 skills/ 下没有任何内容嵌套超过一层。
• 添加它的工具。 编写 mcp.json。对于捆绑的二进制文件使用 ./ 路径，对于你随附的资源使用 ${PLUGIN_ROOT}，对于你写入的任何内容使用 ${PLUGIN_DATA}。
• 在第二个客户端中打开它，确认实际加载了什么，而不是应该加载什么。
• 添加发布元数据，一旦它正常工作：version、license、repository、keywords。
• 安装我们的，Agents CLI 和 Data Agent Kit，并阅读规范。

如果你喜欢这篇文章，别忘了我们之前的一篇文章：每个 AI 工程师都应该知道的 7 条自我改进 agent 循环规则。并继续关注更多内容。