Agent Plugins 1.0.0 发布后怎么打包技能与 MCP：plugin.json、目录约定与跨代理分发

同一套 Agent 能力，常常要同时交给命令行代理、IDE 助手和团队内部工具。过去每个平台都要维护一份安装说明、脚本入口和 MCP 配置，目录一多，版本就容易漂移。Agent Plugins 1.0.0 把这些内容收进统一的插件目录：用 plugin.json 描述包，用固定目录承载 Agent Skills 和 MCP 服务，再交给支持该规范的工具读取。

Agent Plugins 1.0.0 解决的不是“再做一个插件市场”

Google Developers Blog 在 2026 年 8 月介绍的 Agent Plugins 1.0.0，更像一份跨工具的目录约定。它把 Agent Skill、工具服务和描述元数据放到一个可搬运的单元里，目标是减少每个宿主各写一套包装层的重复劳动。Google、Amazon、Microsoft 等参与维护，Google 还提到 Agents CLI 和 Data Agent Kit 已开始支持。

这里有一个容易混淆的边界：规范解决的是“怎么装、怎么发现、怎么分发”，并不替你的技能决定权限，也不会自动让一个危险工具变得安全。真正的访问控制、网络范围和人工确认，仍应留在宿主与服务本身。

先比较三种交付方式，再决定是否迁移

固定宿主的原生扩展

如果团队只使用一个 IDE，原生扩展通常能直接拿到宿主的配置、日志和权限模型。它的优点是体验完整，缺点是迁移到命令行代理或另一款 IDE 时几乎要重做一遍。

脚本加安装文档

脚本方案启动快，适合一次性内部试验。但文档、环境变量和脚本参数没有统一声明，使用者很难在安装前判断包需要哪些能力，也不容易做版本验收。

Agent Plugins 目录包

当同一套技能要被多个代理使用时，目录包的价值会变得明显：身份、指令、参考资料和 MCP 工具可以跟着包一起移动。代价是团队必须认真维护清晰的 manifest、权限边界和兼容说明。

一个可维护的插件包应该怎样分层

不要把整个项目压成一个“万能提示词”。更稳妥的做法是让根目录只保留身份描述和少量入口，把详细规则、参考资料与工具实现分开。示意结构如下：

my-release-helper/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── release-check/
│       ├── SKILL.md
│       └── references/
├── servers/
│   └── changelog/
│       ├── README.md
│       └── package.json
└── README.md

plugin.json 只声明名称、版本、描述和组成部分；SKILL.md 负责告诉代理什么时候加载技能、先读哪些参考资料以及如何验证结果；MCP 服务目录则说明启动参数、工具名称和失败处理。三者分开，才能让代理按需加载，也便于单独升级。

跨代理分发前要做四轮验收

1. 目录验收：从干净目录解包，确认 manifest、技能目录和服务目录都在预期位置，大小写和相对路径不能依赖某台机器。
2. 能力验收：逐项核对描述里的技能名、工具名与真实入口，尤其检查“只读”与“可写”能力有没有写反。
3. 依赖验收：在没有开发者本机缓存的环境中检查运行时、网络范围和配置缺口，遇到缺依赖要给出可理解的终止信息。
4. 版本验收：用两个支持该规范的宿主分别加载同一份包，记录可发现能力、调用结果和不支持项；不要把某一个宿主的成功当成跨平台代理兼容。

哪些情况不适合马上改成插件包

第一种是能力强依赖某个宿主的私有 API，例如必须操作 IDE 的编辑器事务、调试面板或内置账号。硬套通用目录只会增加一层转接。第二种是服务本身仍在快速变动，工具名、输入 schema 和权限尚未稳定，此时先把接口收窄，比急着发布可分发包更重要。

还有一种情况是团队把插件包当成“信任边界”。目录规范只能帮助发现和传输，不能替代密钥管理、沙箱、人工审批或网络隔离。涉及写数据库、发版和删除资源的工具，仍要在服务层做明确的二次确认。

常见问题

Agent Plugins 1.0.0 是一个新的模型吗？

不是。它是用于组织和分发 Agent Skills、MCP 服务及其描述信息的目录规范，不负责提供模型推理能力。

有了 plugin.json 就能在所有代理里直接运行吗？

不能。宿主需要支持这份规范，而且包中的脚本、服务运行时和权限策略仍可能存在差异，必须逐宿主验证。

SKILL.md 和 MCP 服务为什么不合并？

SKILL.md 更偏向任务指令和加载规则，MCP 服务更偏向可调用工具与协议接口。分层后可以独立升级，也更容易限制服务能力。

团队迁移时最先检查哪一项？

先从干净环境验证 manifest 和目录路径，再核对能力声明与真实工具入口，最后才做复杂任务回归。这样能尽早发现“能安装但不能正确调用”的问题。

落地时留一张最小决策表

如果你要把现有技能交给多个代理，先问三个问题：是否需要跨宿主复用，能力接口是否已经稳定，服务是否有清晰的权限边界。三个答案都偏“是”，再用 Agent Plugins 目录包承载；只满足其中一个时，先保留简单交付方式，等边界稳定后再迁移。