Agent Plugins:插件世界的通用包装箱

AI Agent 的能力越来越像软件工程里的依赖包。有人把工作方法写进 Agent Skills，有人通过 MCP 接入服务，也有人为某个客户端补上命令、钩子或专用配置。

问题是，同一份能力到了不同客户端里，往往要换目录、改字段、复制文件。作者维护的是同一个插件，却可能要准备好几套包装。客户端也得理解各自不同的布局，迁移成本就这样一点点堆起来。

Agent Plugins 给出的答案很克制。它不试图统一所有 Agent 产品，只定义一个最小的互操作底座：什么文件必须存在，Skills 和 MCP 放在哪里，客户端怎样发现它们，哪里出错时应该停多大范围。

所以它更像插件世界的通用包装箱，而不是一个新的运行时。箱子的尺寸和标签统一了，谁来运输、怎么安检、最终摆进哪个货架，仍由客户端决定。

一个 Agent Plugin 就是一个自包含目录。根目录必须有 plugin.json，Skills 和 MCP 配置都是可选项。完整一点的结构可以长这样：

my-plugin/├── plugin.json├── skills/│   └── summarize/│       ├── SKILL.md│       ├── scripts/│       └── references/├── mcp.json└── com.example.client/    └── hooks/

这里有四层角色。

• plugin.json 说明插件是谁、面向哪个规范版本。
• skills/ 放 Agent Skills，每个直接子目录代表一个可被发现的 Skill。
• mcp.json 描述本地或远程 MCP 服务器的连接方式。
• com.example.client/ 是客户端扩展目录，用反向域名命名空间避免撞名。

这套布局有两个容易忽略的点。一个是固定位置，plugin.json 不能把 Skills 或 MCP 重定向到任意目录。另一个是包边界，规范要求插件提供的文件解析后仍留在插件根目录内，不能靠 ../、符号链接或同类机制逃出包。

plugin.json 是每个插件唯一的可移植清单。最小版本只有两个必填字段：

{  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",  "name": "hello-plugin"}

$schema 不只是给编辑器做自动补全，它声明了整套校验和解释规则。客户端应根据自己已经支持的规范版本来解析插件，不能在加载插件时临时上网下载一个陌生 Schema，再边看边猜。

name 也有明确约束。它只能使用小写字母、数字、连字符和句点，长度为 1 到 64 个字符，首尾必须是字母或数字，不能出现连续的 -- 或 ..。

清单的顶层结构是封闭的。除了 $schema、name、version、description、author、homepage、repository、license、keywords 和 extensions，其他顶层字段都不属于可移植规范。未知顶层字段会被报告并忽略；其余类型或约束错误通常会让整个插件被拒绝。

这个区别很关键。拼错一个可选字段，不应该偷偷获得新语义；真正破坏清单结构的错误，也不能带病继续加载。

Agent Plugins 1.0 只定义两种可移植组件：Agent Skills 和 MCP servers。

Agent Skills 负责把操作方法、领域知识和配套资源打包。规范并不重新发明 SKILL.md，而是直接采用 Agent Skills 规范。Agent Plugins 只规定发现位置：客户端扫描 skills/ 的直接子目录，找到名称精确为 SKILL.md 的普通文件；它不会递归到更深层继续找新的 Skill。

MCP 负责连接外部工具和数据。根目录的 mcp.json 使用封闭结构，1.0.0 支持三种传输类型：

• stdio：用单个可执行文件令牌启动本地进程。
• streamable-http：连接当前的远程 MCP HTTP 端点。
• sse：兼容旧版 HTTP+SSE，客户端可以不支持。

一个本地服务器配置可以这样写：

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

PLUGIN_ROOT 指向已解析的插件根目录，适合读取随包发布的脚本和配置。PLUGIN_DATA 是客户端为当前插件实例管理的可写持久目录，适合放依赖、缓存和更新后仍需保留的数据。

两者不能混用。包内文件属于 PLUGIN_ROOT，运行时状态属于 PLUGIN_DATA。这样升级插件时，客户端既能替换包内容，也不用顺手把缓存和持久数据一起抹掉。

客户端会先读取并校验根目录的 plugin.json，然后按自己支持的组件类型去固定位置发现 Skills 与 MCP。缺少 skills/ 或 mcp.json 不是错误，因为两者本来就是可选的。

真正有意思的是故障边界。

如果 plugin.json 存在致命 Schema 错误，整个插件会被拒绝。如果某一个 SKILL.md 无效，客户端跳过这个 Skill，其他组件继续加载。如果 mcp.json 顶层结构、版本或 Schema 不合法，只禁用这个插件的 MCP；如果只是某个服务器条目配置错误、传输不受支持、启动失败或认证失败，也只跳过那个条目。

这是一种很实用的失败策略。一个插件里既有文档型 Skill，又有三个 MCP 服务，其中一个远程端点暂时不可用，不应该让其余能力全部消失。规范要求客户端尽量报告问题，同时继续加载彼此独立的有效组件。

对插件作者来说，这也改变了调试顺序。先确认是清单级错误、组件类型级错误，还是单个服务器级错误，再决定修哪里。别一看到插件没完全工作，就把整个目录推倒重来。

Agent Plugins 解决的是包装与发现，不包办安装、分发、启用、更新、权限、用户界面和凭据管理。客户端可以逐步采用规范，只支持 Skills 的客户端也能合规；支持 MCP 的客户端至少实现 stdio 或 streamable-http 之一即可。

安全边界更不能读错。插件路径必须留在包内，这能防止包通过配置路径直接越界读取其他文件，但规范明确说明，这不等于给插件子进程套上沙箱。进程启动后能访问什么路径、拥有什么网络和系统权限，仍要看客户端与操作系统的执行策略。

凭据也不该塞进插件包。远程 MCP 的 headers 和本地服务器的 env 都是可见配置，不是通用秘密存储。1.0.0 没有定义可移植的 OAuth 或凭据引用字段，认证发现、用户交互和凭据保存都由客户端处理。

把这条边界记住，很多误解会自然消失。Agent Plugins 让同一份能力更容易被多个客户端理解，但它没有替你完成权限审计，也没有保证来自任意来源的插件都安全。

最小可用插件只需要一个清单和一个 Skill。先创建目录：

hello-plugin/├── plugin.json└── skills/    └── greet/        └── SKILL.md

plugin.json 使用前面那份最小清单。再写 skills/greet/SKILL.md：

---name: greetdescription: 向用户打招呼并主动询问需要什么帮助。---向用户打招呼，并用一句话询问需要什么帮助。

然后按五项检查。

• $schema 是否正好指向目标 Agent Plugins 版本。
• name 是否满足小写命名规则。
• 每个 Skill 是否位于 skills/ 的直接子目录，文件名是否精确为 SKILL.md。
• 配置中被规范定义为插件相对路径的字段，是否以 ./ 开始并保持在插件根目录内。
• 如果加入 mcp.json，它的 Schema 版本是否与 plugin.json 一致，配置里是否没有密钥。

做到这里，插件包已经符合可移植结构。怎样把本地目录安装或导入具体客户端，规范故意没有统一命令，需要继续看对应客户端的安装说明。

这不是缺失，而是边界设计。不同客户端有不同的信任模型、发布渠道和交互方式，强行塞进 1.0.0，只会把一个小而稳的互操作底座重新做成大而难落地的平台。

截至 2026 年 8 月 7 日，官网的兼容客户端页面列出了 VS Code、Cursor、GitHub Copilot、ChatGPT & Codex 和 Kiro。它们支持的 MCP 传输并不完全相同，这正好说明客户端可以渐进采用，而不是等所有能力一次性对齐。

项目以开放方式开发。官网称初始技术指导委员会包含来自 Amazon、Cursor、Microsoft、OpenAI 和 Vercel 的核心维护者，重大提案与技术决策通过公开仓库和 GitHub Discussions 推进。

不过，1.0.0 的完整规范页面仍标为草案状态。今天可以基于它做插件、验证目录、梳理迁移方式，也应该在正式分发前固定目标 Schema 版本，并关注后续规范变化。尤其是 commands、hooks、agents、rules 和 LSP servers 等组件，目前都不属于 v1 的可移植核心。

Agent Plugins 不是它又给生态添了一个新名词，而是它主动把目标缩小了。先让 Skills 和 MCP 用同一种包装方式移动起来，再把权限、分发和产品体验留给客户端竞争。

一个小小的共同格式，可能比一套试图包办一切的宏大平台更容易真正长出来。

参考：https://agent-plugins.org/