Skill 与 MCP 总要各装一遍？用 Agent Plugins 1.0 把可移植部分装进同一个包

团队把 AI Agent 用进发布、巡检或代码审查后，常会同时维护两类资产：一类是告诉 Agent 如何执行流程的 Skill，另一类是把 Agent 接到部署平台、监控系统或仓库服务的 MCP 配置。两者分别可复用，却往往不能一起交付：换一个客户端，就得重新安排目录、改一份清单，甚至重做安装说明。

2026 年 8 月发布的 Agent Plugins Specification 1.0.0 把问题收敛为一个很小的边界：它不重新定义 Skill，也不重新定义 MCP；它只规定如何把二者放进一个可分发目录。 这很适合把团队已经验证过的运维流程、脚本和工具连接整理成仓库内可审查的插件，而不是让每位开发者在各自客户端里手工拼装。

先分清三层职责：指令、连接与包装

把这三个概念混为一谈，会导致插件要么塞进大量私有配置，要么把“可安装”误当成“可安全执行”。更清晰的划分是：

| 层 | 回答的问题 | 典型内容 |

| — | — | — |

| Agent Skills | Agent 应怎样完成一项工作？ | SKILL.md、脚本、参考资料、模板 |

| MCP | Agent 怎样在运行时调用工具和取得上下文？ | 工具服务、传输方式、连接配置 |

| Agent Plugins | 怎样让上述可移植部分一起被发现？ | 根目录清单、固定目录、mcp.json |

因此，插件不是新的 Agent 运行时，也不是权限系统。客户端仍负责安装入口、审批界面、沙箱、凭据存放及更新策略。规范甚至明确把注册表、市场、发布者身份、来源证明和组织策略留在格式之外。这个取舍很重要：同一个压缩包能被多个客户端读取，不代表它在每个客户端拥有相同权限。

一个最小部署助手长什么样

一个只携带发布步骤的插件，目录可以非常短：

deployment-assistant/
├── plugin.json
└── skills/
    └── deploy-service/
        ├── SKILL.md
        ├── scripts/
        │   └── check-health.sh
        └── references/
            └── rollback.md

根目录的 plugin.json 是唯一的可移植清单。1.0.0 要求它是 JSON，且至少包含固定的 schema 标识和小写名称。名称只能使用小写字母、数字、连字符与点号；未知顶层字段不会获得客户端语义，因此不要把自定义启动命令或密钥偷偷放在这里。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "deployment-assistant",
  "version": "0.1.0",
  "description": "Run a reviewed deployment and rollback workflow",
  "license": "MIT"
}

兼容客户端先验证该文件，再从 skills/ 的直接子目录寻找 SKILL.md。这意味着不要把 Skill 再套一层分类目录指望被递归发现；如果某个 Skill 格式错误，客户端应跳过这一个 Skill，而不是让其余组件全部失效。Skill 本身仍须遵从 Agent Skills 的规范：它可以有前置说明、脚本、参考资料和资源文件，正好适合将“检查什么、何时停止、如何回滚”的团队约定与可执行辅助脚本放在一起。

需要连接工具时，再加 mcp.json

当发布流程还需读取服务健康度或调用部署 API，可以在插件根目录增加 mcp.json。它与 plugin.json 平级，不能内嵌在清单里，也不能换成客户端自定义位置。以下例子展示本地 stdio MCP 服务；命令与参数分开写，避免把 shell 片段误当作可移植配置。

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

这里有四个容易遗漏的约束。

第一，插件自带的可执行文件要以 ./ 开头，且解析后的路径必须仍位于插件根目录内；../bin/tool 这样的逃逸路径无效。第二，command 是一个可执行文件 token，而不是 node server.js && ... 一类 shell 命令串；参数应放入 args。第三，客户端会为 stdio 子进程提供 PLUGIN_ROOT 与持久的 PLUGIN_DATA，规范仅在 args、env 和 cwd 中展开这两个占位符，不会把任意环境变量或 command 做替换。第四，PLUGIN_DATA 适合缓存、依赖和可随更新保留的状态；随包发布的脚本和配置则应通过 PLUGIN_ROOT 引用。

远程 MCP 可以使用 streamable-http，旧式 HTTP+SSE 也有 sse 类型。但连接 URL 必须是绝对 HTTP(S) URL；非 loopback 地址必须用 HTTPS。更关键的是，headers 不是机密管理接口：规范禁止在包内硬编码凭据，也不对 URL 或 header 值进行环境变量展开。认证失败是一次连接失败，不是插件格式失效；具体 OAuth、用户授权和凭据库由客户端管理。

可移植不等于“一次配置，到处无差别运行”

Agent Plugins 1.0 只标准化两种组件：Skill 与 MCP server。命令、hooks、规则、UI 扩展目前都不是可移植组件类型。客户端若需要额外能力，应使用反向域名命名空间，例如 com.example.client/ 目录或清单中的 extensions 对象；不认识该命名空间的客户端应忽略它，而不是猜测其含义。

这带来一个实用的设计原则：把跨客户端真正一致的流程和连接写进标准位置，把产品特有的 hook、交互或审批设置限制在命名空间中。这样在 A 客户端里的增强体验不会污染 B 客户端的基础加载，也不会阻碍只支持 Skill 的客户端使用同一个插件。

另一个边界是失败隔离。缺少 skills/ 或 mcp.json 并不构成错误；一个无效 MCP server 条目也应只被跳过，其他 server 和 Skill 仍可加载。反过来，根 plugin.json 缺少必填字段或违反 schema 则必须拒绝整个插件。把“包级不可信”和“单组件不可用”区分开，能避免一个实验性连接让成熟的操作手册一同消失。

把验证放进提交前，而不是留给使用者排错

这类目录看似只是几个 JSON 文件，最常见的问题却发生在边界处。建议在 CI 中做两级检查：第一层校验 plugin.json 与 mcp.json 是否为合法 JSON，并按 1.0.0 schema 检查必填字段、未知顶层字段和 server 的 transport 类型；第二层检查文件系统布局。例如确认每个 skills/ 的直接子目录都有 SKILL.md，所有 ./ 路径解析后仍位于插件根目录，并拒绝符号链接把脚本带到包外。

运行检查也要分两次。离线阶段只验证格式和路径，不要因为没有生产凭据而跳过；集成阶段则在隔离环境启动 stdio server，确认 command、args 与 cwd 能工作，并故意不给认证，观察客户端是否只将相应远程连接标为失败。这样可以避免把“服务端没有权限”“客户端不支持 transport”误判为插件清单损坏。

对于需要持久状态的工具，还应确认更新行为。把可再生缓存、临时下载和依赖安装在 PLUGIN_DATA；将版本控制的规则、脚本和默认配置留在插件目录。升级插件后，前者应继续存在，后者应随新版本替换。两者混在一起，常见后果是升级时覆盖用户数据，或旧脚本继续读取过期配置。

最后，发布者应把信任信息作为发布流程的一部分，而不是寄希望于格式本身。规范允许记录仓库、许可证和作者元数据，但不定义签名、来源证明或授权。实际团队仍应在代码审查中固定依赖版本、审查可执行脚本和 MCP 指向的域名，并由客户端或组织策略控制谁能安装、谁能批准写操作。可移植包降低了重复配置成本，却不会自动降低执行风险。

落地时用这份检查表

1. 先把现有工作流拆开：重复使用的步骤、脚本和判断条件放进一个符合 Agent Skills 格式的目录；不要把访问令牌写进 SKILL.md、plugin.json 或 mcp.json。
2. 在根目录创建严格的 plugin.json，固定 $schema 与符合规则的 name；为版本、许可证、仓库地址补充可追踪元数据。
3. Skill 放在 skills//SKILL.md，并确认不依赖多层嵌套发现。把回滚条件、人工确认点和危险操作限制写清楚，而非只写“自动发布”。
4. 只有确实需要工具连接时才添加 mcp.json。本地服务用独立的 command 与 args；包内路径使用 ./ 或允许的 PLUGIN_ROOT、PLUGIN_DATA 形式。
5. 用目标客户端实际加载一次：检查它支持哪些组件与传输类型，检查缺少认证时的报错路径，最后再接入团队的审批、凭据与来源验证机制。

对维护者来说，这个格式的价值不在于又多了一个市场文件，而在于建立了可评审的交付边界：流程知识不会和某一个产品的配置格式绑死，MCP 连接也不必散落在个人机器。对使用者来说，最应保持的警惕则是：能被发现、能被安装、能被执行是三件不同的事。Agent Plugins 解决的是第一件事，并为第二、第三件事保留了客户端和组织策略应有的控制权。

相关链接

• Agent Plugins 1.0 官方说明：From Skills and Tools to Portable Agent Plugins
• Agent Plugins Specification 1.0.0
• Agent Plugins 规范仓库
• Agent Skills 规范与概览
• Model Context Protocol 规范