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_source=taotoken_aicg_blog_end ，API 地址是 https://taotoken.net/api ，注意 API 地址不带查询参数。
操作顺序建议这样：
先去控制台创建 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建后立刻复制保存，页面刷新后完整 Key 不会再显示。
然后打开 API Keys 管理页 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，确认 Key 状态是启用，记下它的前缀方便后面排查。
接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面写了不同客户端填 Base URL 的位置和注意事项，配置前扫一遍能省不少试错时间。
如果你打算长期用 Agent 做编码任务，可以顺手看下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它针对持续性的编码场景做了额度安排，比按次调用更适合插件这种高频触发的用法。
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="你的Key"Windows 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_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 发一条测试消息，确认 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承载可移植工具连接，客户端命名空间隔离专属能力。只要这条边界不破，同一套技能就能在两个客户端里长期复用，而不是每次换工具都重写一遍。
