一文搞懂 Agent Plugins：OpenAI 牵头，五大 AI 工具同日支持的插件新标准
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "research-tools"
}```
`$schema` 声明规范版本，`name` 是插件的唯一标识符。一个能被五大客户端识别的插件，从这两行开始。
完整插件的目录结构如下：
```
my-plugin/├── plugin.json# 清单文件（必须）
├── skills/│ └── code-review/
│ └── SKILL.md # 技能描述（可选）├── mcp.json # MCP 服务器配置（可选）
└── extensions/# 客户端特定扩展（可选）├── vscode/
└── cursor/```
关键设计原则：**客户端特定的配置放在 `extensions/` 命名空间，不进 `plugin.json` 顶层字段。** 这保证了顶层格式的跨平台稳定性——一个不认识某客户端扩展的工具可以直接忽略 `extensions/` 目录，而不影响其他部分的加载。
---
五大客户端兼容性一览
Agent Plugins 1.0 发布时，五个主流 AI 开发工具已同步支持：
| 客户端 | Agent Skills | MCP stdio | Streamable HTTP | Legacy SSE |
|--------|-------------|-----------|----------------|-----------|| VS Code | ✅ | ✅ | ✅ | ✅ |
| Cursor | ✅ | ✅ | ✅ | ✅ || GitHub Copilot | ✅ | ✅ | ✅ | ✅ |
| ChatGPT / Codex | ✅ | ✅ | ✅ | ❌ || Kiro | ✅ | ✅ | ✅ | ✅ |
目前唯一的差异点：**ChatGPT / Codex 不支持 Legacy SSE 传输**，其余四个客户端四项全绿。对大多数新插件来说这不是问题——Streamable HTTP 是更新的标准，Legacy SSE 主要用于兼容较早的 MCP 服务器。
值得注意的是，标准页面标注为 "Working Draft"，官方明确说明"不保证每个客户端实现每个组件和每种 MCP 传输"。可移植性意味着客户端能按共同约定发现和加载插件，而不是保证所有客户端行为完全一致。
---
Agent Skills 和 MCP：什么情况用哪个
这是 Agent Plugins 生态里最容易混淆的问题。规范给出了一个清晰的定义：
> **Skill = 智能体应该知道什么、应该怎么工作**
> **MCP = 智能体如何连接外部能力**对应到文件层面：| 维度 | Agent Skills（SKILL.md） | MCP 服务器（mcp.json） ||------|------------------------|----------------------|
| 核心定位 | 可复用的指令、工作流、领域知识 | 连接数据库、API、浏览器等外部服务 || 典型场景 | 代码审查规范、文档生成模板、操作流程 | 数据库查询、部署工具、第三方 API 调用 |
| 网络依赖 | 无 | 需要本地进程或远程 HTTP 端点 || 失败隔离 | 单个无效 Skill 被跳过，其余继续 | 单个无效 MCP 条目不影响其他服务器 |
一个实际决策建议：**如果你要打包的是"给 AI 的工作说明书"，用 SKILL.md；如果你要打包的是"AI 调用的工具"，用 mcp.json。** 两者可以在同一个插件里共存——大多数生产级插件会同时包含两者。
---## Agent Plugins 和 Codex 插件是同一回事吗不完全是，但两者密切关联，有必要区分清楚。**Codex 插件**（Codex Plugin）是 OpenAI 于 2026 年 3 月推出的 ChatGPT/Codex 产品层功能，有自己的 `.codex-plugin/plugin.json` 规范、三层 Marketplace 体系（个人/团队/公共目录）和 `$plugin-creator` 脚手架工具。它是 OpenAI 旗下产品的插件发行和管理机制。**Agent Plugins 1.0**（2026 年 8 月 6 日）是在此基础上推动的跨厂商开放标准，目标是让同一套插件格式能被非 OpenAI 客户端（Cursor、VS Code、Kiro 等）识别。可以理解为：Codex 插件是 OpenAI 的产品实现，Agent Plugins 是多方共同确认的开放规范，两者在文件格式层面高度兼容，但 Agent Plugins 去掉了 OpenAI 专有字段，保留了可跨客户端移植的最小核心。对开发者的实际影响：**如果你已经在按 Codex 插件格式开发，迁移到 Agent Plugins 1.0 的成本很低**——主要差别是把客户端特定配置移入 `extensions/` 目录，并使用 `agent-plugins.org` 的 schema URL。---## 运行时环境变量Agent Plugins 规范定义了两个运行时环境变量，插件 Hooks 和脚本中可以直接使用：| 变量 | 说明 ||------|------|
| `PLUGIN_ROOT` | 已安装插件的根目录路径 || `PLUGIN_DATA` | 插件的可写数据目录 |
这两个变量由客户端在加载插件时注入，使插件脚本能在不硬编码路径的前提下定位自身文件和持久化存储。
---
1.0 版本的已知局限
Agent Plugins 1.0 是一个"工作草案"状态的规范，几个重要功能明确**不在 v1 可移植核心范围内**：
- **Hooks 和命令**：目前仅作为客户端特定扩展存在，不在跨客户端保证范围内
- **子进程沙箱隔离**：规范未定义，安全责任下放给各客户端实现- **插件签名验证**：v1 无内置签名机制，无法验证插件来源的真实性
这意味着安装插件前，用户仍需自行判断来源可信度。规范的保守设计有其合理性——让五家厂商在发布日当天就全部支持一个复杂的安全模型，门槛会高得难以实现。沙箱和签名预计在后续版本中加入。
---
开发者：现在值得上手吗
几个参考判断维度：
**你在同时支持多个客户端（Cursor VS Code GitHub Copilot）**：现在上手最合算。一套格式覆盖三个客户端，是 Agent Plugins 最直接的价值。
**你只用 ChatGPT / Codex，不需要跨客户端**：Codex 插件格式已经成熟，没有迁移的紧迫性。Agent Plugins 与其兼容，未来需要跨平台时再迁移成本也不高。
**如果你正在搭建需要调用外部工具的 Agent 工作流**：眼下，SKILL.md 和 mcp.json 这套组合，基本已经成了业内最主流、也最被广泛接受的结构，当前已有五大主流客户端支持。至于 Agent 工具后端的搭建，优先选择兼容多款主流大模型标准接口的 API 平台，会更省心——比如七牛云 Token Plan，qiniu.com/ai/plan。这样一来，插件在不同模型之间切换时，调用代码通常不用跟着改，这一点在实际落地时尤其关键。
**你在意规范稳定性**：Working Draft 状态意味着字段可能调整。核心字段（`$schema`、`name`、`skills/`、`mcp.json`）稳定性最高，`extensions/` 内的客户端特定字段变更概率更高。
---
常见问题
**Q：Agent Plugins 和 MCP 是竞争关系吗？**
不是，是互补关系。MCP（Model Context Protocol）定义客户端如何与外部工具服务器通信（连接生命周期、传输协议）；Agent Plugins 定义插件文件如何组织和跨客户端识别（目录结构、清单格式）。一个 Agent Plugins 插件可以在 `mcp.json` 中声明 MCP 服务器，两者在同一个插件中共存。**Q：plugin.json 放在哪个位置？**按照 Agent Plugins 1.0 的规范，plugin.json 应该放在插件根目录，而不是 .codex-plugin/ 这个子目录里。至于 Codex 插件把 plugin.json 放到 .codex-plugin/ 下，这属于 OpenAI 产品层面的约定。两套规则看起来很接近，但并不完全一样，开发时务必要把这种对应关系分清楚。
**Q：SKILL.md 必须写什么格式？**
推荐包含 frontmatter（`name` 和 `description` 字段）加自然语言工作流描述，格式与 Codex 插件中的 SKILL.md 相同。内容越具体，AI 客户端的执行结果越稳定。**Q：五个客户端加载同一个插件，行为会完全一样吗？**不保证完全一致。可移植性意味着"五个客户端都能发现和加载这个插件"，不意味着每个客户端对同一个 SKILL.md 的理解和执行方式完全相同。跨客户端测试仍然必要。
**Q：现在有没有 Agent Plugins 的公共市场可以发布插件？**
规范本身不定义发布渠道。各客户端有自己的发现机制——Codex/ChatGPT 有 Universal Plugin Directory，Cursor 和 VS Code 有各自的扩展市场。发布时需参考目标客户端的具体要求。---## 小结Agent Plugins 1.0 在 2026 年 8 月 6 日解决了一个真实存在的碎片化问题：开发者不再需要为每个 AI 客户端维护一套专有插件格式。五大客户端在发布当日同步支持，多厂商背书让这个标准比单一厂商推出的格式有更强的生命力。当前版本是工作草案，沙箱隔离和签名验证尚未纳入规范，Hooks 和命令不在跨客户端保证范围。对于同时服务多个 AI 开发工具的插件作者，现在是合适的上手时机；对于只在单一客户端部署的场景，可以等规范稳定后再迁移，成本不高。本文数据截至 2026 年 8 月 10 日，规范处于 Working Draft 阶段，字段定义以 agent-plugins.org 最新版本为准。 ","createTime":1786362718,"ext":{"closeTextLink":0,"comment_ban":0,"description":"","focusRead":0},"fa vNum":0,"html":"","isOriginal":0,"likeNum":0,
