夜雨聆风摘要
Skill 和 MCP 各自可移植，但「装它们的盒子」每个客户端各搞一套——目录结构、manifest 字段、MCP transport 推断方式全不同，作者 fork 两份包、看着它们漂移。Agent Plugins 1.0.0（2026-08-06 发布）把 Agent Skills + MCP 服务器收进一个固定目录，manifest 极简到只剩 $schema 和 name；Amazon、Cursor、Microsoft、OpenAI、Vercel 五家 Core Maintainer 中立维护，Google 同日宣布加入并已在 Agents CLI、Data Agent Kit 落地。本文按规范原文拆解目录模型、组件发现、MCP 三种传输、四层生态栈，以及工程师何时该用 Plugin、何时只用 Skill/MCP。
一、痛点：组件没问题，manifest 有问题
你写了一个 weekly report Skill，配了一个查报表库的 MCP server——单独拷到 Cursor 能用，拷到 Gemini CLI 就要改目录、改顶层 metadata、改 MCP 配置 shape，transport 还得靠客户端猜。组件本身没变，变的是每个客户端自创的包装层。
Agent Skills 已经让 Agent 能复用指令与资源；MCP 已经让 Agent 连工具与服务。两者单独都是可移植的，不可移植的是「把它们装在一起的盒子」。 Google 开发者博客把这个问题概括为：核心矛盾不在组件，在 manifest。
2026 年 8 月 6 日，Agent Plugins 1.0.0 作为开放、厂商中立的打包规范发布。Technical Steering Committee（TSC）Core Maintainer 来自 Amazon、Cursor、Microsoft、OpenAI、Vercel；Google 宣布加入，由 Google DeepMind 的 Kevin Hou 代表，并开始在自家产品集成。
| 层面 | 已有规范 | Agent Plugins 补什么 |
|---|---|---|
| 指令与资源 | Agent Skills（SKILL.md） | 在 skills/ 固定路径发现 |
| 工具连接 | MCP 协议 | 在 mcp.json 显式声明 transport |
| 打包 | 各客户端自创 | 一个目录 + 固定布局 |
| 发现/分发 | ARD、AI Catalog（可选） | 与打包层解耦 |
1.1 规范 deliberately 小：只做打包
v1 只是 package format，公开写明了不包含：安装机制、分发协议、权限模型、沙箱要求、信任/来源验证、用户审批 UX。这些在 future considerations 里点名，不是悄悄遗漏——IDE、CLI、企业托管平台对用户的义务完全不同，安装与策略留给各客户端。
1.2 与 Cursor Skills 的关系
如果你已经在 Cursor 里写 .cursor/skills/ 下的 SKILL.md，格式本身不变——Agent Plugins 引用的是 Agent Skills 规范 作为 skill 内容的 source of truth。Plugins 只规定在插件包里怎么发现这些 skill，不改变 SKILL.md 怎么写。
扫码加入交流群
二、一个目录就是插件：标准布局
规范的核心约束：Plugin = 一个 filesystem 目录，restraint is the point。
架构图 1：plugin.json 只写名字；Skills 在 skills/；MCP 在 mcp.json；客户端扩展走 reverse-domain 目录
2.1 最小 manifest
plugin.json 放在插件根目录，封闭 schema——允许的顶层字段只有：$schema、name、version、description、author、homepage、repository、license、keywords、extensions。
最小合法示例：
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "reports-plugin"
}
plugin.json 不能做的事（规范硬性禁止）：
• 不能 relocate 组件（不能把 skills 指到别的路径） • 不能 inline 声明 MCP server • 没有 discovery path 配置，也没有 precedence order 要学
name 约束：1–64 字符，小写字母数字 + 连字符 + 点号，首尾必须是字母数字，禁止 -- 和 .. 连续出现。
2.2 固定位置发现组件
| 组件类型 | 固定路径 | 发现规则 |
|---|---|---|
| Skills | skills/ |
每个直接子目录含 SKILL.md 即一个 skill；不递归更深目录 |
| MCP servers | mcp.json |
根目录 JSON；每个 entry 必须有显式 type |
skills/ 或 mcp.json 缺失不算错误——客户端加载有的部分就继续。某 MCP server 启动失败，不会拖垮同插件里的 Skills；客户端跳过该条目、继续加载、报告失败。
2.3 客户端扩展：com.example.client/
reverse-domain 目录是 escape hatch——hooks、agents、commands 等非可移植能力放这里。不认识的客户端直接忽略；可移植核心保持极小，创新留在合法命名空间里。
manifest 里对应 extensions 字段，键也是 reverse-domain namespace；客户端只处理自己实现的 namespace。
2.4 路径安全
插件内所有配置路径必须以 ./ 开头、解析后不能逃出 plugin root。../bin/server 这类路径 invalid。Symlink 可以指向 root 内目标，解析到 root 外必须拒绝。
三、MCP 配置：三种 transport，不再猜
各客户端原先 MCP 配置 shape 不兼容、transport 靠推断——Agent Plugins 定义封闭的 union，每个 server entry 必须带 type。
架构图 2：stdio / streamable-http / sse 显式声明；单 server 失败不影响其他组件
3.1 三种 transport 对照
| type | 用途 | 关键字段 | 客户端要求 |
|---|---|---|---|
stdio |
本地子进程 | command（单 token）、args、env、cwd |
MCP-capable 客户端 MUST 支持 stdio 或 streamable-http，SHOULD 两者都支持 |
streamable-http |
当前远程 MCP 标准 | url（HTTPS，非 loopback）、headers |
同上 |
sse |
MCP 2024-11-05 遗留 HTTP+SSE | url |
OPTIONAL |
command 必须是单个可执行 token——裸名或 ./ 开头的 plugin-relative 路径，不是 shell 命令串。插件若 bundle 二进制，应使用 ./bin/xxx 保证确定性。
远程 URL：非 loopback 必须 HTTPS；headers 禁止内嵌密钥——可见包数据不是 portable secret 机制。
3.2 环境变量：PLUGIN_ROOT 与 PLUGIN_DATA
客户端启动 stdio MCP 子进程时 MUST 注入：
| 变量 | 含义 |
|---|---|
PLUGIN_ROOT |
插件根目录绝对路径（只读 bundled 资源） |
PLUGIN_DATA |
客户端管理的可写持久目录（node_modules、venv、缓存） |
在 args、env 值、cwd 中支持 ${PLUGIN_ROOT}、${PLUGIN_DATA} 占位符替换（单次、非递归）。env 里禁止出现名为 PLUGIN_ROOT / PLUGIN_DATA 的条目——由客户端强制设置。
示例（规范原文）：
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"local-validator": {
"type": "stdio",
"command": "./bin/validator",
"args": ["--data", "${PLUGIN_DATA}/validator"],
"env": { "CONFIG": "${PLUGIN_ROOT}/config.json" },
"cwd": "${PLUGIN_ROOT}"
},
"deployment-api": {
"type": "streamable-http",
"url": "https://deploy.example.com/mcp"
}
}
}
3.3 故障隔离规则
规范 §7.2.2 / §11.3 强调组件级 failure boundary：
• plugin.json schema 致命错误 → 整包 reject
• 单个 skill 不合 Agent Skills 规范 → skip 该 skill
• 单个 MCP server invalid / transport 不支持 / 连接失败 → skip 该 server
• mcp.json 与 plugin.json 的 $schema 版本 mismatch → 禁用 MCP，Skills 仍可加载
四、生态四层栈：发现、描述、打包、运行
打包只是一件事；让用户找到并装上插件是另一件事。Google 博客与规范都把层次拆清楚——各层独立有用、独立可采纳。
架构图 3：ARD 发现 → AI Catalog 描述 → Agent Plugins 打包 → Skills/MCP 执行
| 层级 | 名称 | 做什么 | 与 Plugin 关系 |
|---|---|---|---|
| L1 | Agentic Resource Discovery (ARD) | 调用前问「这个任务有什么资源？」 | Plugin 是一类 agentic resource |
| L2 | AI Catalog | 索引条目格式 | 提议注册 application/agent-plugins+json，指向 plugin.json |
| L3 | Agent Plugins | 固定目录打包 | 本篇主题 |
| L4 | Agent Skills + MCP | 执行契约 | 已有独立规范 |
你可以：只发 plugin、无 catalog 条目；只 catalog 非 plugin 资源；只跑 skill 不用 plugin——采纳一层不绑架下一层。
4.1 什么时候该用 Plugin？
规范与 Google 博客一致：不是每个 skill 都要 plugin。
| 场景 | 建议 |
|---|---|
| 单个 MCP server、单客户端 | 只用 mcp.json 更简单 |
| 单个 skill | 直接发 skill 目录 |
| Skill + MCP（或多 skill）要一起分发、跨客户端 | 用 Agent Plugin |
| 需要 Cursor hooks / 客户端专有 agents | Plugin + com.cursor.* 扩展目录 |
一分钟 hello world：建目录 → 写 plugin.json（name）→ 写 skills/greet/SKILL.md → 合法 plugin。
4.2 Google 已落地产品
| 产品 | 内容 | 意义 |
|---|---|---|
| Agents CLI | Agent 构建、评测、部署、可观测、发布等 expert skills | 原先可分发，现用跨客户端格式 |
| Data Agent Kit | 连 BigQuery、Spanner、Cloud SQL 等的 skills + MCP | 数据工程师在任意兼容 IDE/Agent 里管资产、跑查询、部署 pipeline |
Google 表示将把 Agent Plugins 支持扩展到更多已使用 Skills/MCP 的产品。
4.3 v1 刻意不做的 vs 竞品各自封装
| 能力 | Agent Plugins v1 | 典型客户端现状 |
|---|---|---|
| 目录布局 | 固定 | 各搞一套 |
| MCP transport | 显式 type |
常靠 shape 推断 |
| 安装/更新 | 未定义 | marketplace、git submodule、settings UI |
| 权限/沙箱 | 未定义 | IDE 各有 approval flow |
| 企业审计 | 未定义 | 平台策略 |
这意味着：Plugin 解决「作者写一次、多客户端能读」；「用户怎么安全地装」仍是 Cursor vs Gemini CLI vs 企业平台的差异化战场。
4.4 客户端 conformance 最低要求
规范 §11.1 对 conformant client 的底线：
1. 能从目录路径加载 plugin
2. 解析 $schema，验证封闭 plugin.json
3. 忽略未实现的 extensions namespace
4. 在固定位置发现所支持的组件类型
5. 若支持 MCP：至少 stdio 或 streamable-http 之一；mcp.json 独立 schema
6. 若启动子进程：提供并展开 PLUGIN_ROOT / PLUGIN_DATA
7. 至少支持一种组件类型（skills 或 MCP）
Skills-only 客户端可以不支持 MCP，仍可能 conformant。
你的 Skill 只给 Cursor 用，还是打成 Agent Plugin 给 Cursor + Gemini CLI 一起用？——评论区二选一。