适用范围如果团队需要同时维护 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. 迁移前的三份配置问题典型旧结构如下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. 一个最小插件目录可以先整理成下面的插件目录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.jsonMCP server 的描述和启动配置合并前检查环境变量和权限com.github.copilot/Copilot 相关扩展的命名空间示例只放客户端特有内容命名空间只是组织原则的示例。正式项目中如果目标客户端规定 manifest 必须放在自己的隐藏目录应该遵守该客户端 schema不要为了保持示意图而改变实际安装路径。4. plugin.json不要承担所有配置迁移时常见的错误是把所有信息都塞进plugin.json。更稳妥的分工是plugin.json - 插件身份、版本、描述、发现入口 skills/ - Agent 工作流正文 mcp.json - MCP server 定义与启动参数 命名空间 - 客户端特有 agents、commands、rules、hooks 部署环境 - 密钥、个人路径、组织权限、运行时变量下面是一个 manifest 结构示例。字段名称和 schema 需要以目标客户端的 1.0 实现为准不能直接替代具体客户端的完整 manifest{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 配置迁移前至少检查以下字段{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 先做差异清单可以先用普通文件比较工具找出重复和差异diff-ruclient-vscode/ client-cli/diff-ruclient-cli/ client-desktop/把结果分为四类公共 skill、公共 MCP、客户端扩展、部署环境变量。此时不要删除旧目录。6.2 合并公共能力将内容完全一致的审查流程移入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 保留回退点先以“行为等价”为验收标准发布迁移版本v0三份旧配置仍可用 v1插件包与旧配置并存逐客户端验证 v2确认插件包稳定后停止新增旧配置 v3清理旧配置但保留 v0/v1 回退版本Agent 工具配置也应该像代码一样有版本和回退不要一次性删除所有旧入口。7. 验收清单每个兼容客户端至少验证[ ] 能发现插件及其版本 [ ] 能加载公共 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 ChangelogAgent Plugins 1.0 in VS Code, Copilot CLI, and the Copilot appGitHub Copilot documentation#AgentPlugins #AI编程 #MCP #VSCode #工程实践