Agent Plugins 1.0.0

它替你干掉什么 · 装法 · 第一条能跑的用法

① 规范本体 agentplugins/agent-plugins-spec（据 GitHub 仓库页，2026-10 读取约 1.4k 星）——spec/1.0.0.md 是规范正文，schemas/1.0.0/ 是两份 JSON Schema；1.1.0 仍是工作草案。最小插件：

hello-plugin/
├── plugin.json
└── skills/greet/SKILL.md

# plugin.json —— 只有 $schema 与 name 是必填
{ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin" }

首发客户端的装法（均据各家官方文档，2026-10 检索）：

• VS Code——命令面板跑 Chat: Install Plugin From Source，填 Git 仓库地址即可；默认已接 copilot-plugins 与 awesome-copilot 两个市场，加别的市场改 chat.plugins.marketplaces。
• Copilot CLI——copilot plugin install <插件名>@awesome-copilot；旧版本先跑 copilot plugin marketplace add github/awesome-copilot。也可写进 settings 的 enabledPlugins。
• github/awesome-copilot——GitHub 官方维护的社区市场，VS Code、Copilot CLI、Copilot app 默认可见；规范插件从这里装。
• Codex——codex plugin marketplace add owner/repo 加市场，codex plugin add <插件>@<市场> 安装；交互里 /plugins 看列表。
• Cursor——同时认两种格式：根目录 plugin.json（Agent Plugins）与 .cursor-plugin/plugin.json（Cursor 自有）。本地调试把目录放进 ~/.cursor/plugins/local/ 后 Reload Window；市场里的用 /add-plugin。
• Kiro——在 Powers 面板选「Import power from GitHub」贴仓库地址；plugin.json 与旧的 POWER.md 都认。插件里的 MCP server 由 Kiro 托管，不写进你的 ~/.kiro/settings/mcp.json，随 power 启停。

机制：它凭什么能跨客户端

① 固定位置，不做配置

skill 只在 skills/ 的直接子目录里找 SKILL.md，规范明文禁止递归往下找；skill 本身照 Agent Skills 规范写，不合规的那一个被跳过，插件其余部分照常加载。MCP 只读根目录的 mcp.json，不认写在 plugin.json 里的。

② MCP 配置是一个封闭联合

每个 server 必须显式写 type：stdio / streamable-http / sse（旧版），多一个字段就判该条无效。理由写在规范的 Design Decisions 里：各家现有 MCP 配置形状互不兼容、推断传输的方式也不同。客户端只需支持 stdio 或 streamable-http 中的一种，不支持的条目跳过。

{ "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "lint": { "type": "stdio", "command": "./bin/lint-server",
              "args": ["--cache", "${PLUGIN_DATA}/cache"] } } }

只认两个占位符：${PLUGIN_ROOT}（插件根）与 ${PLUGIN_DATA}（客户端管理、升级后仍保留的可写目录）；所有路径必须 ./ 开头且不能解析到插件根之外。

③ 各家私货放进反向域名目录

hooks、commands、agents、rules、LSP 被规范明确排除在 v1 之外——「太依赖具体客户端」。它们放进 com.github.copilot/ 这类目录，或 plugin.json 的 extensions 字段；不认识的命名空间，客户端必须忽略、不得校验。

真实用法与边界：同一个文件夹喂 Claude Code 和其他五家

my-tools/
├── plugin.json                # Agent Plugins：$schema + name
├── .claude-plugin/plugin.json # Claude Code 自家清单（可选）
├── skills/review/SKILL.md     # 两边共用，只写一份
├── mcp.json                   # 显式 type + ${PLUGIN_ROOT}
├── .mcp.json                  # Claude Code 版 + ${CLAUDE_PLUGIN_ROOT}
└── com.github.copilot/hooks/  # 某家专属的东西放这里

验货两条命令：Claude Code 这边 claude --plugin-dir ./my-tools 直接加载、claude plugin validate ./my-tools 校验清单；skill 那层用 agentskills/agentskills 的 skills-ref validate。规范自己的 FUTURE_CONSIDERATIONS 承认还没有官方校验工具，Agent Plugins 那一侧只能靠两份 JSON Schema 和各客户端的报错。

判据：什么时候该打成 Agent Plugin

• 只有一个 skill、只用一个客户端 → 不打包。一份 SKILL.md 放进 skills 目录就够了。
• 一组 skill + 一个 MCP server，团队里有人用 Copilot、有人用 Cursor → 打成 Agent Plugin，放进一个 Git 仓库，各人按上面的装法装。
• 核心价值在 hooks 或 subagent → v1 帮不了你，这部分照样每家写一份，放各自命名空间。
• 团队只用 Claude Code → 留在 .claude-plugin/ 加 marketplace，见 Skill 34 的插件管理。

代价与替代品

① 信任边界留给了客户端

规范明确不定义安装、权限与信任模型、分发与市场、注册表、OAuth 与凭据。FUTURE_CONSIDERATIONS 列出的待办包括：清单里声明权限、签名与来源验证、密钥注入、企业白名单——这些在 1.0 里都还没有。一个 stdio 类型的 MCP server 就是一个会在你机器上跑的程序，审查照 Skill 30 与 Skill 12 的清单来。

② 「跨客户端」不等于「同样好用」

规范只规定客户端在哪找组件，不规定「怎么把 skill 暴露给用户或模型」。同一个 skill 在不同客户端的触发方式、命名空间、上下文开销都可能不同，跨端发布前每家至少跑一遍。

③ 双份配置要同步

为了兼顾 Claude Code 写两份 MCP 配置，就多了一个会漂移的地方。没有依赖声明（同样在待办里），插件之间也不能互相引用。