agent-plugins mcp agent-skills ai-agents tooling

Agent Plugins 1.0.0：技能与MCP服务器的共享打包格式

Agent Plugins 1.0.0 为技能与MCP服务器提供了一种统一的打包格式：文件夹、plugin.json以及mcp.json，但该版本在安全性方面存在不足，同时还缺少一个命令行示例。

发布者：REACTAPP.TOP加入本站 2026年10月28日阅读约 7 分钟1571 词

来源: Six Major Tech Companies Jointly Establish the AI Agent Plugin Packaging Standard After MCP and SKILL

Google、Microsoft、OpenAI、Cursor、Vercel 和 AWS 都参与了 Agent Plugins 1.0.0 的制定，该规范明确了 AI 智能体插件的打包方式。它规范了目录结构、配置文件格式以及两种组件的发现规则，这两种组件分别是技能和 MCP 服务器。其目标很简单：只需编写一次插件，即可在任何兼容的客户端中使用。

迄今为止，为编程智能体添加新功能通常有两种方式。技能是一组 Markdown 指令，智能体在需要时读取这些指令。MCP 服务器则是独立的进程，用于将智能体与外部工具、API 或数据库连接起来。这两种方式的内容本身已经在不同工具之间具备可移植性，但每个工具在文件夹结构、配置文件名称以及文件存放位置方面都有各自的惯例。

1.0.0版本仅处理外部封装层，不对技能的内部结构及MCP协议本身进行改动。

其重要性

这一设计对以下三类群体具有重要意义：

插件开发者只需维护一个在所有支持客户端中都能使用的目录结构，无需再为Cursor、Copilot、Codex等工具分别准备不同的版本。
工具供应商可以确定skills/和mcp.json的固定位置，从而无需自行设计查找逻辑或配置解析机制。供应商仍可在命名空间目录中添加自己的额外内容，而不会影响其他实现方式。

更广阔的生态系统得益于三项设计选择：通过目录进行发现、只需放置文件即可完成设置，以及故障能够被限制在特定范围内。这样一来分发变得更加容易，开发者可以专注于构建什么内容，而非考虑该使用哪些工具。

其局限性同样明显。该规范仅对软件包的封装格式进行了标准化，却未涉及其中内容的安全性问题。它没有签名机制、权限模型，也无法处理敏感信息。目前它的优势在于提升开发者效率，但无法提供安全保障或信任背书。

目录结构

符合规范的插件仅仅是一个文件夹。以名为 reports-plugin 的示例为例，其完整的目录结构如下：

reports-plugin/
├── plugin.json                  # Required: The only entry point for the plugin
├── skills/                      # Optional: Collection of skills
│   ├── summarize/               # One individual skill
│   │   ├── SKILL.md             #   Required: Skill definition file
│   │   ├── scripts/             #   Optional: Scripts used by the skill
│   │   │   └── analyze.sh
│   │   └── references/          #   Optional: Reference documentation for the skill
│   │       └── checklist.md
│   ├── deploy/                  # A second skill
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── rollback.sh
│   │   └── references/
│   │       └── runbook.md
│   └── code-review/             # A third skill
│       └── SKILL.md
├── mcp.json                     # Optional: MCP server configuration
├── com.cursor.tools/            # Optional: Cursor-specific extensions, other clients skip automatically
│   └── hooks/
│       └── hooks.json
├── LICENSE
└── CHANGELOG.md

客户端只会查看三个地方。plugin.json用于标记该文件夹为有效插件。skills/目录下的每个包含SKILL.md文件的一级子文件夹都算作一项技能，而mcp.json则被用作MCP服务器配置。采用反向域名格式命名的文件夹，如com.cursor.tools/，仅能被其所属的客户端（即Cursor）读取，其他客户端如ChatGPT和Codex则会直接忽略它们。

plugin.json清单文件

plugin.json是唯一必须存在的文件，其最小版本体积非常小：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}

该架构是封闭的，允许的顶层字段共有十个：$schema、name、version、description、author、homepage、repository、license、keywords以及extensions。如果出现未知字段，系统会报告并忽略它，插件仍可加载。但name字段出问题则另当别论——若该字段缺失、类型错误或包含非法字符（大写字母、连续的双连字符、空字符串），则整个插件将被拒绝。

name字段的规则为：长度在1到64个字符之间，只能由小写字母、数字、连字符和句点组成，且必须以字母或数字开头和结尾，同时禁止出现连续的两个连字符或两个句点。

组件的查找方式

发现机制完全基于目录结构。plugin.json无法将组件移动到其他位置，也无法直接嵌入其配置。仅有三种类型的路径存在：

skills/：任何包含SKILL.md文件的一级子文件夹都视为一个技能。更深层的文件夹不会被扫描。
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 是 2024-11-05 版 MCP 规范中较旧的 HTTP+SSE 传输方式，为保持向后兼容而保留。

客户端至少需要实现 stdio 或 streamable-http，两者都实现则更好。sse 是可选的。

环境变量与持久数据

每当客户端启动 stdio 进程时，都必须设置两个变量。PLUGIN_ROOT 存储插件根目录的绝对路径。PLUGIN_DATA 指向客户端提供的持久数据目录，该目录在插件更新后依然存在，而在卸载时会被删除。

${PLUGIN_ROOT} 和 ${PLUGIN_DATA} 都可能出现在 args、env 值以及 cwd 中。替换操作仅进行一次纯文本处理，不支持其他占位符或shell风格的变量扩展。

故障仅限于本地

该规范在多个层面实施了“部分故障不得级联”的规则：

一个MCP服务器启动失败不会影响其他服务器或技能。
格式有误的技能会被跳过，其余技能仍可正常加载。
使用客户端不支持的传输协议的MCP条目也会被跳过。
如果mcp.json完全无效，仅会关闭MCP组件，技能仍可加载。

规范未涵盖的内容

版本1中缺失的内容包括：插件安装方式、运行时权限控制、作者身份验证，以及机密信息或API密钥的安全存储方式。文档明确指出，头部值和环境值属于可见的包数据，并非保持信息保密的可靠手段。此外还不存在OAuth配置，也没有通用的凭证引用字段，因此授权问题必须由每个客户端自行处理。

哪些平台支持，哪些不支持

目前有六款客户端获得启动支持：Kiro、VS Code、Cursor、GitHub Copilot、Codex和ChatGPT。谷歌在同一天也加入了维护者行列，其Agents CLI是首批采用该格式的产品之一。AWS同样也是支持方。

Anthropic既创造了技能格式也开发了MCP，而Claude Code自2025年起就一直在使用几乎相同的插件打包方式。即便如此，Anthropic并未参与工作组，Claude Code也不在最初的支援列表中。

使用Google的Agents CLI的端到端示例

Agents CLI是早期采用者之一。安装后，它能为编程智能体提供七种技能，涵盖ADK模式、项目框架搭建、评估、部署以及可观测性功能。

以构建一个RAG知识助手为例。开发者用通俗语言描述目标，智能体便会自行执行操作：

它以ADK的agentic_rag模板为基础搭建项目框架，同时将Vector Search作为数据存储方式。
它发现该模板缺乏引用支持，于是重新编写了智能体指令，要求使用内联引用，并将检索器改为返回来源ID。
它建立了数据存储，加载了12份Python参考文档作为语料库，然后进行了初步测试。

在部署前会进行评估：共20个测试用例，分为四组，其中6个用于测试检索准确性，5个用于测试在上下文不足时的拒绝处理能力，5个用于测试多跳推理能力，4个用于测试引用准确性。

评估过程中发现了一个导致幻觉的边缘情况：对于语料库之外的问题，智能体有时会凭借通用知识给出答案，而非承认自己不知道。原因是系统提示中有一句话称，那些有已知答案的简单问题可以直接回答，无需使用工具。删除那句话后问题便完全解决了。

部署到 Google Cloud 需要两到三分钟，且默认会启用 Cloud Trace。在注册 Gemini Enterprise 后，组织内的所有人都可以找到并使用该代理。