1. 为什么同一套技能要在两个客户端里各写一遍如果你同时用 VS Code 和 Copilot CLI 做开发大概率遇到过这种别扭事在编辑器里调好的代码审查流程切到终端里就得重新描述一遍MCP 服务器在 VS Code 里配好了命令行里又要再写一份配置。功能没变维护成本翻倍。Agent Plugins 1.0 想解决的就是这个打包问题。它把 Agent Skills 和 MCP 服务器收进一个固定结构的目录用plugin.json声明身份用skills/放可移植技能用mcp.json放可移植的工具连接再把 Copilot 专属的 Agent、命令、规则、Hooks 隔离到com.github.copilot/命名空间里。支持这套规范的客户端各取所需不认识的扩展直接忽略不会因为一个专属字段导致整个插件加载失败。这篇聚焦plugin.json的骨架怎么写、MCP 声明放哪里、TaoToken 的统一 Key 和 API 通道接在什么位置以及怎么在 VS Code 和 Copilot CLI 里分别验证技能真的被加载、真的能调用。适合已经在用 Copilot 系工具、想把手头技能沉淀成可复用插件的开发者也适合刚开始接触 Agent Plugins、想先跑通一个最小示例的新手。2. 前置准备TaoToken 统一 Key 与 API 通道在写插件之前先把模型调用这条链路理顺。插件里的 Skill 本身只是流程说明真正干活的是背后的模型和工具。如果你在 VS Code 和 Copilot CLI 里各配一套 Key等于又回到了重复维护的老路。TaoToken 在这里的作用是提供统一的 API 通道一个 Key、一个 Base URL两个客户端都指向同一个入口切换工具时不用重新申请凭证。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 地址是 https://taotoken.net/api 注意 API 地址不带查询参数。操作顺序建议这样先去控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后立刻复制保存页面刷新后完整 Key 不会再显示。然后打开 API Keys 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态是启用记下它的前缀方便后面排查。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了不同客户端填 Base URL 的位置和注意事项配置前扫一遍能省不少试错时间。如果你打算长期用 Agent 做编码任务可以顺手看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对持续性的编码场景做了额度安排比按次调用更适合插件这种高频触发的用法。Key 拿到后不要写进plugin.json也不要提交到仓库。正确做法是通过环境变量注入插件里的mcp.json只引用变量名。这一点后面在 MCP 配置那节会具体写。3. 可复制配置plugin.json 骨架与目录结构先给一个能直接跑的最小插件。目录长这样team-review-tools/ ├── plugin.json ├── skills/ │ └── review-api/ │ └── SKILL.md └── mcp.json根目录的plugin.json只负责身份和元数据不塞任何技能路径或 MCP 配置{ $schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, name: team-review-tools, version: 1.0.0, description: Reusable code review skills for the team, license: MIT, keywords: [code-review, agent-skills] }两个必填字段是$schema和name。name只能用 小写字母、数字、连字符和点长度 1 到 64 个字符。version、description、author、homepage、repository、license、keywords、extensions是规范允许的可选字段。这里有个高频踩坑点不要把hooks、agents、commands、mcpServers、lspServers这些塞到plugin.json顶层。1.0 的根清单是封闭结构多写一个不认识的顶层字段可能导致整个清单校验失败、插件被拒绝加载。MCP 服务器统一放根目录mcp.json客户端专属能力放对应命名空间。技能定义放在skills/review-api/SKILL.md注意skills/的直接子目录才是一项技能客户端不会无限向下递归--- name: review-api description: Review API changes for compatibility, security, and test coverage. --- When reviewing an API change: 1. Identify changed endpoints and schemas. 2. Check backward compatibility. 3. Check authentication and authorization boundaries. 4. Verify error handling and test coverage. 5. Return findings by severity with file references.写法上尽量描述目标、输入、判断标准和输出不要写「点击 VS Code 右侧某个按钮」这种绑定具体界面的动作。终端里的 Agent 读不懂按钮但读得懂「检查向后兼容性」。MCP 声明放在根目录mcp.json把 TaoToken 的 API 通道作为远程服务器接进来{ mcpServers: { taotoken: { type: http, url: https://taotoken.net/api, headers: { Authorization: Bearer ${TAOTOKEN_API_KEY} } } } }${TAOTOKEN_API_KEY}是环境变量占位实际值在系统环境或 shell 配置里设置不要硬编码进文件。设置方式export TAOTOKEN_API_KEY你的KeyWindows PowerShell 用$env:TAOTOKEN_API_KEY你的Key如果插件还需要 Copilot 专属的 Agent 或 Hooks再建com.github.copilot/目录把agents/、commands/、rules/、hooks/放进去。VS Code 和 Copilot CLI 会读取自己支持的部分其他客户端忽略这个命名空间但通用 Skills 和 MCP 配置照常生效。4. 验证请求在两个客户端里确认技能真的加载配置写完不等于生效得分别验证。先做清单校验再测技能发现最后测 MCP 调用。清单校验最直接的办法是用 JSON 解析器过一遍确认没有语法错误python -c import json; json.load(open(plugin.json)); print(plugin.json OK) python -c import json; json.load(open(mcp.json)); print(mcp.json OK)在 VS Code 里把插件目录放到它识别的插件位置后重新加载窗口。打开 Copilot Chat输入一个能触发review-api技能的问题比如「帮我审查这次 API 改动」。如果技能被正确发现回复会按 SKILL.md 里定义的五个步骤展开而不是给一段泛泛的建议。你还可以在插件的管理界面确认team-review-tools出现在已安装列表里状态是启用。在 Copilot CLI 里进入插件目录所在的工作区启动 CLI 后先列出可用技能copilot plugin list确认review-api在列表里。然后直接提问触发copilot review the API changes in this branch观察输出是否遵循 SKILL.md 的步骤结构。如果 CLI 支持查看 MCP 工具再确认taotoken服务器被列出copilot mcp list成功的结果是两个客户端都能发现同一个review-api技能都能列出taotoken这个 MCP 服务器调用时请求正常返回。如果只想快速验证模型通道是否通可以用模型对话页面 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条测试消息确认 Key 和 Base URL 没问题再回到插件里排查。5. 本篇常见错排查插件加载失败提示清单无效。先检查plugin.json顶层有没有多写字段。mcpServers、hooks、agents、commands都不该出现在这里。用上面的 Python 命令确认 JSON 语法没问题再核对$schema是否完整匹配 1.0.0 地址。技能没被发现。最常见的原因是目录层级写错了。必须是skills/skill-name/SKILL.md不能是skills/team/review-api/SKILL.md。客户端只扫描skills/的直接子目录。另外确认文件名大小写完全一致是SKILL.md不是skill.md。MCP 服务器连不上。先确认环境变量TAOTOKEN_API_KEY在当前 shell 里真的存在echo $TAOTOKEN_API_KEY如果为空说明变量没导出到启动客户端的那个环境。VS Code 从图形界面启动时可能读不到 shell 里的 export需要在系统环境变量里设置或者用支持读取.env的方式注入。还要确认mcp.json里的 URL 是https://taotoken.net/api不要多加路径或参数。一个坏技能拖垮整个插件。正常情况下单个 SKILL.md 的 frontmatter 格式错误应该只跳过那一项技能不影响其他有效技能。如果发现整个插件都不工作检查是不是plugin.json本身出了问题而不是某个技能。Copilot 专属能力在别的客户端报错。com.github.copilot/里的内容只有实现该命名空间的客户端才读。如果某个客户端不支持却报错说明它没有正确忽略未知命名空间这属于客户端兼容性问题不是插件配置错误。可以先把专属能力暂时移出确认可移植核心正常后再加回来。禁用插件后 MCP 进程还在跑。测试生命周期时留意这一点。禁用插件应该让对应的 MCP 服务器停止、工具从列表消失。如果进程残留检查是不是有独立的 MCP 配置在别处也引用了同一个服务器。6. 把技能沉淀成可复用资产跑通最小示例之后下一步不是急着把所有旧配置都迁过来而是挑一项最通用的流程先做扎实。代码审查、测试失败排查、发布前核对这类技能不依赖具体界面最适合放进skills/。等它在 VS Code 和 Copilot CLI 里都验证稳定了再考虑把 Copilot 专属的 Hooks 和命令补进com.github.copilot/。维护的时候记住这条边界plugin.json定义身份skills/承载可移植知识和流程mcp.json承载可移植工具连接客户端命名空间隔离专属能力。只要这条边界不破同一套技能就能在两个客户端里长期复用而不是每次换工具都重写一遍。
1. 为什么同一套技能要在两个客户端里各写一遍如果你同时用 VS Code 和 Copilot CLI 做开发大概率遇到过这种别扭事在编辑器里调好的代码审查流程切到终端里就得重新描述一遍MCP 服务器在 VS Code 里配好了命令行里又要再写一份配置。功能没变维护成本翻倍。Agent Plugins 1.0 想解决的就是这个打包问题。它把 Agent Skills 和 MCP 服务器收进一个固定结构的目录用plugin.json声明身份用skills/放可移植技能用mcp.json放可移植的工具连接再把 Copilot 专属的 Agent、命令、规则、Hooks 隔离到com.github.copilot/命名空间里。支持这套规范的客户端各取所需不认识的扩展直接忽略不会因为一个专属字段导致整个插件加载失败。这篇聚焦plugin.json的骨架怎么写、MCP 声明放哪里、TaoToken 的统一 Key 和 API 通道接在什么位置以及怎么在 VS Code 和 Copilot CLI 里分别验证技能真的被加载、真的能调用。适合已经在用 Copilot 系工具、想把手头技能沉淀成可复用插件的开发者也适合刚开始接触 Agent Plugins、想先跑通一个最小示例的新手。2. 前置准备TaoToken 统一 Key 与 API 通道在写插件之前先把模型调用这条链路理顺。插件里的 Skill 本身只是流程说明真正干活的是背后的模型和工具。如果你在 VS Code 和 Copilot CLI 里各配一套 Key等于又回到了重复维护的老路。TaoToken 在这里的作用是提供统一的 API 通道一个 Key、一个 Base URL两个客户端都指向同一个入口切换工具时不用重新申请凭证。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 地址是 https://taotoken.net/api 注意 API 地址不带查询参数。操作顺序建议这样先去控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后立刻复制保存页面刷新后完整 Key 不会再显示。然后打开 API Keys 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态是启用记下它的前缀方便后面排查。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了不同客户端填 Base URL 的位置和注意事项配置前扫一遍能省不少试错时间。如果你打算长期用 Agent 做编码任务可以顺手看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对持续性的编码场景做了额度安排比按次调用更适合插件这种高频触发的用法。Key 拿到后不要写进plugin.json也不要提交到仓库。正确做法是通过环境变量注入插件里的mcp.json只引用变量名。这一点后面在 MCP 配置那节会具体写。3. 可复制配置plugin.json 骨架与目录结构先给一个能直接跑的最小插件。目录长这样team-review-tools/ ├── plugin.json ├── skills/ │ └── review-api/ │ └── SKILL.md └── mcp.json根目录的plugin.json只负责身份和元数据不塞任何技能路径或 MCP 配置{ $schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, name: team-review-tools, version: 1.0.0, description: Reusable code review skills for the team, license: MIT, keywords: [code-review, agent-skills] }两个必填字段是$schema和name。name只能用 小写字母、数字、连字符和点长度 1 到 64 个字符。version、description、author、homepage、repository、license、keywords、extensions是规范允许的可选字段。这里有个高频踩坑点不要把hooks、agents、commands、mcpServers、lspServers这些塞到plugin.json顶层。1.0 的根清单是封闭结构多写一个不认识的顶层字段可能导致整个清单校验失败、插件被拒绝加载。MCP 服务器统一放根目录mcp.json客户端专属能力放对应命名空间。技能定义放在skills/review-api/SKILL.md注意skills/的直接子目录才是一项技能客户端不会无限向下递归--- name: review-api description: Review API changes for compatibility, security, and test coverage. --- When reviewing an API change: 1. Identify changed endpoints and schemas. 2. Check backward compatibility. 3. Check authentication and authorization boundaries. 4. Verify error handling and test coverage. 5. Return findings by severity with file references.写法上尽量描述目标、输入、判断标准和输出不要写「点击 VS Code 右侧某个按钮」这种绑定具体界面的动作。终端里的 Agent 读不懂按钮但读得懂「检查向后兼容性」。MCP 声明放在根目录mcp.json把 TaoToken 的 API 通道作为远程服务器接进来{ mcpServers: { taotoken: { type: http, url: https://taotoken.net/api, headers: { Authorization: Bearer ${TAOTOKEN_API_KEY} } } } }${TAOTOKEN_API_KEY}是环境变量占位实际值在系统环境或 shell 配置里设置不要硬编码进文件。设置方式export TAOTOKEN_API_KEY你的KeyWindows PowerShell 用$env:TAOTOKEN_API_KEY你的Key如果插件还需要 Copilot 专属的 Agent 或 Hooks再建com.github.copilot/目录把agents/、commands/、rules/、hooks/放进去。VS Code 和 Copilot CLI 会读取自己支持的部分其他客户端忽略这个命名空间但通用 Skills 和 MCP 配置照常生效。4. 验证请求在两个客户端里确认技能真的加载配置写完不等于生效得分别验证。先做清单校验再测技能发现最后测 MCP 调用。清单校验最直接的办法是用 JSON 解析器过一遍确认没有语法错误python -c import json; json.load(open(plugin.json)); print(plugin.json OK) python -c import json; json.load(open(mcp.json)); print(mcp.json OK)在 VS Code 里把插件目录放到它识别的插件位置后重新加载窗口。打开 Copilot Chat输入一个能触发review-api技能的问题比如「帮我审查这次 API 改动」。如果技能被正确发现回复会按 SKILL.md 里定义的五个步骤展开而不是给一段泛泛的建议。你还可以在插件的管理界面确认team-review-tools出现在已安装列表里状态是启用。在 Copilot CLI 里进入插件目录所在的工作区启动 CLI 后先列出可用技能copilot plugin list确认review-api在列表里。然后直接提问触发copilot review the API changes in this branch观察输出是否遵循 SKILL.md 的步骤结构。如果 CLI 支持查看 MCP 工具再确认taotoken服务器被列出copilot mcp list成功的结果是两个客户端都能发现同一个review-api技能都能列出taotoken这个 MCP 服务器调用时请求正常返回。如果只想快速验证模型通道是否通可以用模型对话页面 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条测试消息确认 Key 和 Base URL 没问题再回到插件里排查。5. 本篇常见错排查插件加载失败提示清单无效。先检查plugin.json顶层有没有多写字段。mcpServers、hooks、agents、commands都不该出现在这里。用上面的 Python 命令确认 JSON 语法没问题再核对$schema是否完整匹配 1.0.0 地址。技能没被发现。最常见的原因是目录层级写错了。必须是skills/skill-name/SKILL.md不能是skills/team/review-api/SKILL.md。客户端只扫描skills/的直接子目录。另外确认文件名大小写完全一致是SKILL.md不是skill.md。MCP 服务器连不上。先确认环境变量TAOTOKEN_API_KEY在当前 shell 里真的存在echo $TAOTOKEN_API_KEY如果为空说明变量没导出到启动客户端的那个环境。VS Code 从图形界面启动时可能读不到 shell 里的 export需要在系统环境变量里设置或者用支持读取.env的方式注入。还要确认mcp.json里的 URL 是https://taotoken.net/api不要多加路径或参数。一个坏技能拖垮整个插件。正常情况下单个 SKILL.md 的 frontmatter 格式错误应该只跳过那一项技能不影响其他有效技能。如果发现整个插件都不工作检查是不是plugin.json本身出了问题而不是某个技能。Copilot 专属能力在别的客户端报错。com.github.copilot/里的内容只有实现该命名空间的客户端才读。如果某个客户端不支持却报错说明它没有正确忽略未知命名空间这属于客户端兼容性问题不是插件配置错误。可以先把专属能力暂时移出确认可移植核心正常后再加回来。禁用插件后 MCP 进程还在跑。测试生命周期时留意这一点。禁用插件应该让对应的 MCP 服务器停止、工具从列表消失。如果进程残留检查是不是有独立的 MCP 配置在别处也引用了同一个服务器。6. 把技能沉淀成可复用资产跑通最小示例之后下一步不是急着把所有旧配置都迁过来而是挑一项最通用的流程先做扎实。代码审查、测试失败排查、发布前核对这类技能不依赖具体界面最适合放进skills/。等它在 VS Code 和 Copilot CLI 里都验证稳定了再考虑把 Copilot 专属的 Hooks 和命令补进com.github.copilot/。维护的时候记住这条边界plugin.json定义身份skills/承载可移植知识和流程mcp.json承载可移植工具连接客户端命名空间隔离专属能力。只要这条边界不破同一套技能就能在两个客户端里长期复用而不是每次换工具都重写一遍。
