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_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite第二确认你的 Cursor 版本支持 MCP。打开 Cursor 设置找到 MCP 相关面板能看到「Add new MCP server」入口就说明没问题。如果找不到先升级到较新版本。注意MCP 配置里填的是 API 地址和 Key不要把 Key 硬编码进会提交到 Git 的文件。后面会给一个用环境变量的写法。关于 Key 的创建入口和字段说明官方文档写得更细遇到字段不确定时可以直接对照https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite3. 可复制配置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 配置里导出 KeymacOS/Linux 示例export TAOTOKEN_API_KEYsk-你的KeyWindows 用 PowerShell 的话$env:TAOTOKEN_API_KEY sk-你的Key配置完成后重启 CursorMCP 面板里应该能看到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_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite4.3 长期编码场景如果你打算把 Skill MCP 这套用在日常编码、Agent 长任务上调用量会比偶尔测一次大得多。这种情况更适合用 Coding Plan 来统一管理额度避免每次临时建 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite5. 本篇常见错排查配置过程中最容易踩的坑集中在下面几类对照着查基本能定位。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.mdSKILL.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_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你用的是 Claude Code 这类终端 Agent接入方式略有不同可以参考对应的 Anthropic 兼容配置https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite最后留一个我自己的习惯每写完一个 Skill先故意用一句「擦边」的话测它会不会误触发。误触发比不触发更烦人因为它会在你不想用的时候插进来。把description的边界收窄一点比事后抱怨 AI 乱加载要省事得多。
