1. 为什么你的 Cursor 需要一个「技能手册」
如果你已经在 Cursor 里写过.cursorrules，大概率遇到过这种尴尬：规则文件越写越长，从命名规范到部署流程全塞进去，结果每次对话 AI 都要把这坨内容读一遍，既浪费上下文，又经常「记混」——你问它写个提交信息，它却开始给你讲单元测试覆盖率。
Cursor Skill 就是来解决这个问题的。一句话说清楚：Skill 是一份 Markdown 文件，用来教会 Cursor AI 执行某类特定任务，比如代码审查、生成 commit message、按团队规范生成接口文档。它和 Rules、MCP 的分工可以这样理解：
| 机制 | 类比 | 加载方式 | 典型体量 |
|---|---|---|---|
| Rules | 员工守则 | 始终或按文件类型生效 | 50 行以内 |
| Skills | 岗位操作手册 | AI 判断场景后按需加载 | 500 行以内 |
| MCP | 外部工具箱 | 常驻连接，提供工具调用 | 配置为主 |
Rules 是「永远要遵守的简短约束」，Skill 是「用到才翻开的详细指南」，MCP 是「连接外部系统的标准协议」。三者不冲突，配合起来才是完整的 Agent 工作流。
这篇要讲的不只是 Skill 怎么写，而是把 Skill 和 MCP 串起来：用 SKILL.md 定义技能，用 MCP 配置接入 TaoToken 统一 Key/API 通道，让 Cursor 里所有模型调用走同一个入口。适合需要在 Cursor 中复用自定义技能、同时想统一管理模型调用的开发者。下面从概念到落地，一步步跑通一次真实调用。
2. 前置准备：TaoToken 统一 Key 与 MCP 通道
在写 SKILL.md 之前，先把「模型从哪来」这件事定下来。Skill 本身只描述「怎么做」，真正执行时还是要调用模型，而 MCP 就是让 Cursor 通过标准协议访问外部模型服务的桥梁。
TaoToken 在这里扮演的角色是统一的 API 通道：你只需要一个 Key，就能在 Cursor、Claude Code、各类 Agent 工具里复用同一套模型调用配置，不用每个工具单独维护一份密钥。对经常在多个编辑器/终端之间切换的人来说，这一点省事很多。
你需要准备两样东西：
第一，一个可用的 API Key。到控制台创建即可，建议按项目或用途分开建，方便后续排查和回收：
https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite第二，确认你的 Cursor 版本支持 MCP。打开 Cursor 设置，找到 MCP 相关面板，能看到「Add new MCP server」入口就说明没问题。如果找不到，先升级到较新版本。
注意：MCP 配置里填的是 API 地址和 Key，不要把 Key 硬编码进会提交到 Git 的文件。后面会给一个用环境变量的写法。
关于 Key 的创建入口和字段说明，官方文档写得更细，遇到字段不确定时可以直接对照：
https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite3. 可复制配置：SKILL.md 骨架 + MCP 配置片段
这一节是全文的核心，分两块：先写 Skill 本体，再配 MCP 通道。
3.1 目录结构
Skill 的目录结构很轻，主文件必须是SKILL.md，其余都是可选的附属文件：
skill-name/ ├── SKILL.md # 必须，AI 会读取的主文件 ├── reference.md # 可选，详细参考 ├── examples.md # 可选，使用示例 └── scripts/ # 可选，工具脚本 └── validate.py存放位置有两种作用域，按需选择：
| 类型 | 路径 | 生效范围 |
|---|---|---|
| 个人 Skill | ~/.cursor/skills/skill-name/SKILL.md | 你的所有项目 |
| 项目 Skill | .cursor/skills/skill-name/SKILL.md | 仅当前项目，可随仓库共享 |
注意：不要放进
~/.cursor/skills-cursor/，那个目录是 Cursor 内置 Skill 专用的，放进去不会按你的预期加载。
3.2 SKILL.md 骨架
SKILL.md 由两部分组成：YAML 头部 + Markdown 正文。头部只有两个必填字段，但description几乎决定了这个 Skill 能不能被正确触发。
--- name: api-review description: >- 审查接口代码的质量、安全性和可维护性，并检查是否符合团队接口规范。 当用户提交 Pull Request、要求代码审查，或提到 "review"、"接口评审" 时使用。 --- # 接口代码审查 ## 快速开始 审查接口代码时按以下顺序检查： 1. 逻辑正确性和潜在 Bug 2. 安全最佳实践（鉴权、参数校验、越权） 3. 代码可读性与命名 4. 测试是否覆盖变更 ## 审查清单 - [ ] 逻辑正确，边界情况已处理 - [ ] 无安全漏洞（注入、越权、敏感信息泄露） - [ ] 符合项目接口规范 - [ ] 错误处理完善，返回结构统一 - [ ] 测试覆盖了变更内容 ## 反馈格式 - **严重**：合并前必须修复 - **建议**：建议改进 - **锦上添花**：可选优化 ## 补充资料 详细接口规范见 [STANDARDS.md](STANDARDS.md)。头部字段的要求很明确：
| 字段 | 要求 | 作用 |
|---|---|---|
| name | 最长 64 字符，仅小写字母/数字/连字符 | Skill 唯一标识 |
| description | 最长 1024 字符，不能为空 | AI 据此判断何时加载 |
写description有两个关键点。一是用第三人称，比如「审查接口代码的质量」而不是「我帮你审查代码」；二是同时说清 WHAT 和 WHEN——做什么，以及什么场景下用。把触发关键词（如 "review"、"接口评审"）自然写进去，AI 匹配时命中率会高很多。
正文则要克制。上下文窗口是共享资源，每个 token 都有成本，所以 SKILL.md 控制在 500 行以内，只写 AI 不知道的专有知识，别教它基础常识。详细内容拆到reference.md、examples.md里，需要时再展开。
3.3 MCP 配置片段
Skill 定义好了「怎么做」，接下来让 Cursor 通过 MCP 访问 TaoToken 的模型通道。在 Cursor 的 MCP 配置里新增一个 server，用环境变量传 Key，避免明文入库：
{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"], "env": { "TAOTOKEN_API_KEY": "${env:TAOTOKEN_API_KEY}", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }然后在你的 shell 配置里导出 Key（macOS/Linux 示例）：
export TAOTOKEN_API_KEY="sk-你的Key"Windows 用 PowerShell 的话：
$env:TAOTOKEN_API_KEY = "sk-你的Key"配置完成后重启 Cursor，MCP 面板里应该能看到taotoken这个 server 处于已连接状态。如果显示红色或报错，先看第 5 节的排查清单。
4. 验证请求：跑通一次技能调用
配置写完不代表能用，得实际验证一次。分两步：先确认 MCP 通道通，再确认 Skill 被正确触发。
4.1 验证 MCP 通道
在 Cursor 的对话里直接问一句需要走外部通道的问题，比如让它调用模型接口返回一段内容。如果 MCP 面板显示已连接，且对话能正常返回结果，说明通道没问题。
更稳妥的方式是用命令行单独测一次 API 连通性，排除 Cursor 本身的干扰：
curl -X POST "https://taotoken.net/api/v1/chat/completions" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "回复 ok"}] }'返回里能看到正常的choices结构，就说明 Key 和地址都对。这一步能过，MCP 配置基本不会有大问题。
4.2 验证 Skill 触发
把 3.2 的 SKILL.md 放到.cursor/skills/api-review/SKILL.md，然后在对话里输入一句带触发词的话，比如：
帮我 review 一下这个 PR 的接口改动如果 Skill 生效，AI 会按 SKILL.md 里的审查清单和反馈格式来组织回答，而不是泛泛而谈。你可以故意提交一段有越权风险的代码，看它是否按「严重/建议/锦上添花」的格式指出问题——格式对上了，说明 Skill 被正确加载。
想单独验证模型对话效果，也可以直接到模型对话页面测一轮：
https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite4.3 长期编码场景
如果你打算把 Skill + MCP 这套用在日常编码、Agent 长任务上，调用量会比偶尔测一次大得多。这种情况更适合用 Coding Plan 来统一管理额度，避免每次临时建 Key：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite5. 本篇常见错排查
配置过程中最容易踩的坑集中在下面几类，对照着查基本能定位。
Skill 不触发。九成是description的问题。检查三点：是不是用了第一人称（改成第三人称）、有没有写清 WHEN（触发场景）、触发关键词是否自然出现。另外确认目录名和name字段一致，路径没放错到skills-cursor/。
MCP 显示未连接。先看npx能不能正常执行，网络环境是否允许拉取包；再确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的导出了（echo $TAOTOKEN_API_KEY验证）。Cursor 是从启动时的环境继承变量的，改完环境变量要完全重启 Cursor，不是关窗口重开。
401 / 鉴权失败。Key 拼写错误、前后有空格、或者用了已删除的 Key。到控制台重新建一个，替换后重启。注意Authorization头是Bearer加 Key，中间有一个空格。
404 / 地址错误。确认 base URL 是https://taotoken.net/api，不要多加或漏掉路径段。curl 测试时完整路径是/api/v1/chat/completions。
Skill 加载了但行为不对。大概率是正文太长或塞了太多通用知识，AI 抓不住重点。把详细内容挪到reference.md，SKILL.md 只留核心步骤和清单。
改了 SKILL.md 不生效。Cursor 启动时扫描 Skill 目录，改完文件后重启一次对话或重启 Cursor 再试。
6. 把 Skill 和统一 Key 用起来
回到最初的问题：为什么要在 Cursor 里同时用 Skill 和 MCP？因为 Skill 解决的是「AI 知不知道你团队的规矩」，MCP 解决的是「AI 能不能稳定调到模型」。两件事分开管，各自都简单。
实操建议是：先把一个高频场景做成 Skill，比如接口审查或 commit message 生成，跑通触发逻辑；再把 MCP 通道配好，用环境变量管 Key；最后把两者串起来验证一次完整调用。跑通之后，你会发现新增一个技能只是往.cursor/skills/里丢一个目录的事，而模型调用始终走同一个 Key，不用每个工具重新配一遍。
接入文档里有更完整的字段说明和示例，遇到配置细节可以直接对照：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite如果你用的是 Claude Code 这类终端 Agent，接入方式略有不同，可以参考对应的 Anthropic 兼容配置：
https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite最后留一个我自己的习惯：每写完一个 Skill，先故意用一句「擦边」的话测它会不会误触发。误触发比不触发更烦人，因为它会在你不想用的时候插进来。把description的边界收窄一点，比事后抱怨 AI 乱加载要省事得多。
