适用范围
如果团队需要同时维护 VS Code、命令行 Agent 和 Copilot 相关客户端配置，通常会遇到三个实际问题：
- 同一份 skill 在多个客户端重复复制；
- MCP server 配置分散，修改后容易漏同步；
- 客户端专属的 agents、commands、rules、hooks 与公共能力混在一起。
最终目标不是把所有 Agent 工具强行变成一个格式，而是把公共能力集中到插件包，把客户端差异放入命名空间，并保留可回退的迁移路径。
1. 官方状态和日期边界
GitHub 的官方 Changelog 公告发布日期为 2026-08-12。公告说明 Agent Plugins 1.0 标准于 2026-08-06 发布，参与方包括 AWS、Anysphere、Microsoft、OpenAI 和 Vercel。
GitHub 公告称 Agent Plugins 1.0 已在 VS Code、GitHub Copilot CLI、GitHub Copilot SDK 和 GitHub Copilot app 中普遍可用。实际可用范围仍然受具体客户端版本、账号计划、组织策略和插件内容影响，其他 Agent 客户端需要单独确认是否支持该标准。
官方还明确说明：已有 skills 和 MCP server 配置继续支持，不要求立即迁移。因此下面的迁移是渐进式整理方案，不是强制升级脚本。
2. 迁移前的三份配置问题
典型旧结构如下：
text
client-vscode/
├── skills/code-review/SKILL.md
└── mcp.json
client-cli/
├── skills/code-review/SKILL.md
└── mcp.json
client-desktop/
├── skills/code-review/SKILL.md
└── mcp.json问题不只在于文件重复：
- skill 的修复可能只进入其中一份；
- MCP 的 command、args 或环境变量可能出现版本漂移；
- 客户端扩展规则混进公共配置后，其他客户端无法理解；
- 删除旧配置后，迁移失败很难快速回退。
3. 一个最小插件目录
可以先整理成下面的插件目录：
text
project-review-plugin/
├── plugin.json
├── skills/
│ └── code-review/
│ └── SKILL.md
├── mcp.json
└── com.github.copilot/
├── agents/
│ └── reviewer.agent.md
├── commands/
│ └── review.md
├── rules/
│ └── repository.md
└── hooks/
└── after-review.json各目录的职责：
| 路径 | 作用 | 迁移判断 |
|---|---|---|
plugin.json |
插件元数据、名称、版本和可发现入口 | 以目标客户端当前 schema 为准 |
skills/ |
跨客户端复用的 Agent 技能 | 内容相同时合并到公共目录 |
mcp.json |
MCP server 的描述和启动配置 | 合并前检查环境变量和权限 |
com.github.copilot/ |
Copilot 相关扩展的命名空间示例 | 只放客户端特有内容 |
命名空间只是组织原则的示例。正式项目中如果目标客户端规定 manifest 必须放在自己的隐藏目录，应该遵守该客户端 schema，不要为了保持示意图而改变实际安装路径。
4. plugin.json不要承担所有配置
迁移时常见的错误是把所有信息都塞进 plugin.json。更稳妥的分工是：
text
plugin.json -> 插件身份、版本、描述、发现入口
skills/ -> Agent 工作流正文
mcp.json -> MCP server 定义与启动参数
命名空间 -> 客户端特有 agents、commands、rules、hooks
部署环境 -> 密钥、个人路径、组织权限、运行时变量下面是一个 manifest 结构示例。字段名称和 schema 需要以目标客户端的 1.0 实现为准，不能直接替代具体客户端的完整 manifest：
json
{
"name": "project-review",
"version": "1.0.0",
"description": "Review project changes with repository-aware checks",
"skills": ["skills/code-review"],
"mcp": "mcp.json"
}如果某个客户端的 schema 不接受 skills 或 mcp 这种字段，应按其官方 schema 调整；不要把示例字段当成跨产品的兼容承诺。真正稳定的迁移原则是目录职责和版本边界，而不是手工复制一个未经校验的 JSON。
5. mcp.json的迁移检查
MCP 配置迁移前，至少检查以下字段：
json
{
"mcpServers": {
"repo-search": {
"command": "node",
"args": ["./servers/repo-search.js"],
"env": {
"REPO_ROOT": "${REPO_ROOT}"
}
}
}
}不同客户端的 MCP 配置方言可能不同，迁移时重点检查：
command在目标机器上是否存在；args是否引用了插件包内或部署环境中的稳定路径；- 环境变量是否由运行环境注入，而不是提交真实密钥；
- server 所需网络、文件和执行权限是否符合组织策略；
- 不同客户端是否使用同一种
mcp.json方言。
如果某个客户端使用 .mcp.json、不同的顶层字段，或有额外的 allowlist，就保留它的适配文件，不能仅凭文件名相同就认为语义相同。
6. 从三份复制配置迁移到一个插件
6.1 先做差异清单
可以先用普通文件比较工具找出重复和差异：
bash
diff -ru client-vscode/ client-cli/
diff -ru client-cli/ client-desktop/把结果分为四类：公共 skill、公共 MCP、客户端扩展、部署环境变量。此时不要删除旧目录。
6.2 合并公共能力
将内容完全一致的审查流程移入：
text
project-review-plugin/skills/code-review/SKILL.md如果三份 SKILL.md 看起来相似但实际不同，先比较行为和版本，不要直接覆盖。可以选择一个基线版本，再把差异单独记录为迁移任务。
6.3 合并 MCP 描述
将共同的 server 定义整理到插件的 mcp.json。个人路径和秘密不写入文件，可以改成部署时注入的 ${REPO_ROOT}、${API_TOKEN} 等变量。变量语法是否支持，仍然要按实际客户端文档确认。
6.4 放入命名空间
只被 Copilot 相关客户端理解的入口放在 com.github.copilot/ 示例目录中；其他客户端的扩展放入对应的受支持命名空间。公共 skills/ 不应该出现大量 if client == ... 的说明和分支。
6.5 保留回退点
先以"行为等价"为验收标准发布迁移版本：
text
v0：三份旧配置仍可用
v1：插件包与旧配置并存，逐客户端验证
v2：确认插件包稳定后，停止新增旧配置
v3：清理旧配置，但保留 v0/v1 回退版本Agent 工具配置也应该像代码一样有版本和回退，不要一次性删除所有旧入口。
7. 验收清单
每个兼容客户端至少验证：
text
[ ] 能发现插件及其版本
[ ] 能加载公共 skill
[ ] 能启动并调用 MCP server
[ ] 环境变量由部署环境提供
[ ] 权限范围符合预期
[ ] 客户端专属 agent/command/rule/hook 不污染其他客户端
[ ] 关闭或回退插件后，旧配置仍可恢复这份清单用于迁移验收，是否通过需要在目标客户端逐一执行；目录结构本身不能替代安装和运行验证。
8. 什么时候不要迁移
以下场景可以继续保持现有配置：
- 项目只有一个客户端；
- MCP server 只有一个临时实验用途；
- 团队还没有明确的插件来源和权限审查流程；
- 目标客户端尚未声明支持 Agent Plugins 1.0；
- 迁移会同时改变 skill 逻辑、MCP 运行时和组织权限。
标准化的收益来自减少重复和漂移。如果只是为了得到一个新目录，却引入了额外的运行时不确定性，应该先完成验证再切换。
9. 结论
Agent Plugins 1.0 可以把 plugin.json、skills/、mcp.json 和客户端命名空间组织成一个可分发单元。它解决的是 Agent 工具配置的重复维护、版本漂移和团队交接问题。
迁移时记住三点：公共能力集中，客户端差异隔离，密钥和权限留在部署环境。它能让兼容客户端共享一套插件来源，但不能保证所有工具、所有命令和所有运行时都完全一致。
官方来源
- GitHub Changelog：Agent Plugins 1.0 in VS Code, Copilot CLI, and the Copilot app
- GitHub Copilot documentation
#AgentPlugins #AI编程 #MCP #VSCode #工程实践