刚刚，Google、Microsoft、OpenAI、Cursor、Vercel 和 AWS 联合发布了 Agent Plugins 1.0.0 规范，标准化了 AI Agent 插件的打包格式。该规范定义了 skill 和 MCP server 的目录结构、配置文件格式和发现规则，目标是实现"写一次，多客户端运行"。
此前，给编程 Agent 添加能力有两种方式：skill 是一组 Markdown 指令，Agent 按需读取；MCP server 是一个独立进程，连接 Agent 到外部工具、API 或数据库。二者的内容格式本身已跨工具通用，但各工具对其目录结构、配置文件命名和放置位置有各自约定，导致同一 skill 在不同工具间需要手动调整。
Agent Plugins 1.0.0 只标准化了外层包装，不涉及 skill 内部格式或 MCP 协议本身。
这套规范的价值分三层。对插件开发者，一个目录结构通吃所有支持该规范的客户端，不再需要为 Cursor、Copilot、Codex 各维护一份副本。对工具方，skills/ 和 mcp.json 的固定位置就是约定，不需要自己发明发现逻辑和配置解析，各家想加私货放进自己的命名空间目录即可，互不干扰。对生态，目录即发现、零配置、局部失败不扩散这三个设计降低了分发摩擦，插件作者只需要关心"写什么功能"，不用纠结"适配哪些工具"。但局限同样明显：规范只定包装盒，不定盒子里东西的安全性，没有签名验证、没有权限控制、没有密钥管理，所以现阶段的价值主要在开发效率，不在安全可信。
目录结构
一个符合规范的插件是一个文件夹。以 reports-plugin 为例，完整结构如下：
reports-plugin/
├── plugin.json # 必需，插件唯一入口
├── skills/ # 可选，skill 集合
│ ├── summarize/ # 一个 skill
│ │ ├── SKILL.md # 必需，skill 定义文件
│ │ ├── scripts/ # 可选，skill 用到的脚本
│ │ │ └── analyze.sh
│ │ └── references/ # 可选，skill 参考文档
│ │ └── checklist.md
│ ├── deploy/ # 另一个 skill
│ │ ├── SKILL.md
│ │ ├── scripts/
│ │ │ └── rollback.sh
│ │ └── references/
│ │ └── runbook.md
│ └── code-review/ # 第三个 skill
│ └── SKILL.md
├── mcp.json # 可选，MCP 服务器配置
├── com.cursor.tools/ # 可选，Cursor 专用扩展，其他客户端自动跳过
│ └── hooks/
│ └── hooks.json
├── LICENSE
└── CHANGELOG.md客户端加载时只认三个固定位置：plugin.json 判断这是一个合法插件，skills/ 下每个含 SKILL.md 的一级子目录自动识别为一个 skill，mcp.json 读取 MCP 服务器配置。com.cursor.tools/ 这类以反向域名命名的目录只有 Cursor 自己会读取，ChatGPT、Codex 等客户端看到不认识的前缀直接跳过。LICENSE 和 CHANGELOG.md 是常规工程文件，不在规范约束范围内，不影响加载。
plugin.json 规范
plugin.json 是唯一必需的入口文件。最简形态仅需两行：
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "hello-plugin"
}Schema 为封闭式，仅允许 10 个顶层字段：$schema、name、version、description、author、homepage、repository、license、keywords、extensions。未知字段会被报告并忽略，不阻止加载。但 name 字段缺失、类型错误或包含非法字符（大写字母、连续横杠、空字符串）时，整个插件直接拒绝。
name 字段约束：长度 1-64 字符，仅允许小写字母、数字、连字符和句点，首尾必须为字母数字，不允许连续连字符或连续句点。
组件发现
- skills/：每个一级子目录中若存在 SKILL.md，即视为一个 skill。不递归扫描更深层级。
- mcp.json：MCP 服务器配置文件。
- 客户端扩展目录：以反向域名命名（如 com.example.client/），其他客户端自动跳过。
组件缺失不视为错误。若 skills 不是目录或 mcp.json 不是普通文件，该组件类型被标记为无效，其他组件类型继续加载。
MCP 配置
mcp.json 必须包含 $schema 和 mcpServers 两个顶层字段。$schema 版本必须与 plugin.json 声明一致，不一致则 MCP 配置整体失效。
支持三种传输类型：
- stdio：本地子进程通信。command 为单个可执行令牌，支持裸名称（依赖系统 PATH）或 ./ 开头的插件相对路径。可选字段 args、env、cwd。cwd 默认值为插件根目录。
- streamable-http：当前 MCP Streamable HTTP 传输。
- sse：已废弃的 HTTP+SSE 传输（MCP 2024-11-05 规范），保留兼容。
客户端必须至少支持 stdio 或 streamable-http 之一，推荐两者都支持。sse 为可选。
环境变量与数据持久化
启动 stdio 子进程时，客户端必须提供两个环境变量：
- PLUGIN_ROOT：插件根目录绝对路径
- PLUGIN_DATA：客户端分配的持久化数据目录，插件更新时内容保留，卸载时清理
${PLUGIN_ROOT} 和 ${PLUGIN_DATA} 可在 args、env 值、cwd 字段中使用，执行单次、非递归的文本替换。不支持其他占位符或环境变量展开。
局部失败隔离
规范在多个层级贯彻"局部失败不扩散"原则：
- 单个 MCP 服务器启动失败，不影响其他服务器和 skills 加载
- 单个 skill 格式不合法，跳过该 skill，其余继续
- MCP 服务器传输类型不被客户端支持，跳过该条目
- mcp.json 整体无效，仅禁用 MCP 组件，skills 仍正常加载
未覆盖的领域
规范不涉及以下内容：插件安装机制、运行时权限控制、作者身份验证、密钥和 API key 的安全存储。规范文档明确说明，header 值和 env 值属于"可见的包数据，不是可移植的保密机制"。Agent Plugins v1 未定义 OAuth 配置或可移植的凭据引用字段，授权流程由各客户端自行管理。
支持方与缺席方
首批支持该规范的客户端包括 ChatGPT、Codex、Cursor、GitHub Copilot、Kiro 和 VS Code。Google 在发布当天以维护者身份加入，其 Agents CLI 是首批采用该格式的产品之一。AWS 也在支持者名单中。
Skills 和 MCP 协议均由 Anthropic 创建。Claude Code 自 2025 年起使用几乎相同的格式打包插件，但 Anthropic 不在规范制定团队中，Claude Code 也不在首批支持工具名单中。
实践案例：Agents CLI 全流程
Google 的 Agents CLI 是首批采用该格式的工具之一。安装后，Agents CLI 向编程 Agent 注入 7 个技能，覆盖 ADK 模式、项目脚手架、评估、部署和可观测性。
以构建 RAG 知识助手为例，开发者通过自然语言描述需求，Agent 自动完成以下步骤：
- 基于 ADK agentic_rag 模板搭建项目结构，使用 Vector Search 作为数据存储
- 发现模板缺少引用支持，自动重写 Agent 指令要求内联引用，并修改检索器以返回源 ID
- 配置数据存储，导入 12 条 Python 基础语料，运行冒烟测试
部署前执行评估：20 个测试场景，分为四类。检索正确性 6 个，上下文不足拒绝能力 5 个，多跳推理 5 个，引用准确性 4 个。
评估发现一个幻觉边缘案例：面对语料库外的问题，Agent 偶尔附加常识回答而非明确拒绝。根因定位为系统指令中的一行："如果你已经知道简单问题的答案，可以不使用工具直接回答"。删除该行后问题解决。
部署到 Google Cloud 耗时 2-3 分钟，Cloud Trace 默认开启。注册到 Gemini Enterprise 后，组织内所有成员均可发现和使用该 Agent。
相关链接
- 规范文档：https://agent-plugins.org/specification
- GitHub 仓库：https://github.com/agentplugins/agent-plugins-spec
关注公众号回复“进群”入群讨论