1. 为什么 Cursor 里需要一个自己写的 SkillCursor 用久了你会发现一个尴尬每次开新会话它都像失忆一样你得重新交代一遍「我们项目的接口规范是什么」「日志格式要按这个来」「别用那个废弃的库」。这些重复劳动本质上是因为 Cursor 缺少一个稳定的、可复用的「操作说明书」。Skill 就是来解决这件事的。Skill 的本质是一个文件夹里面放一个SKILL.md用 Markdown 告诉 AI「遇到什么情况、按什么步骤干活」。它不需要你写代码不需要你懂 API会写 Markdown 就够了。复杂一点的 Skill 可以带脚本和参考资料但最小可用版本就是一个纯文本文件。你可以把它理解成给 AI 的一份岗位说明书什么时候上岗、按什么流程操作、交付什么格式。那为什么还要接 TaoToken 统一 Key因为 Skill 一旦跑起来它会频繁调用模型——扫描选题、整理 JSON、生成结构化输出。如果你每个 Skill 都单独配一套 Key管理成本会迅速失控。TaoToken 提供的是一个统一的 API 通道Base URL 固定、Key 统一、模型 ID 可切换这样你的 Skill 无论跑在 Cursor 里还是别的工具里都走同一条通道换模型只改一个字段。这篇教程面向的是想用 Markdown 定义可复用 Skill 的开发者。我会从目录结构讲起给出 Cursor 侧的配置片段然后带你跑一次可复现的调用验证。全程不需要你写复杂代码跟着做就能把自定义 Skill 稳定跑通。适合谁适合已经在用 Cursor、被重复提示词折磨、想把手头流程沉淀下来的同学。如果你还没配过任何 API 通道也没关系前置部分我会把 Key 和地址怎么拿讲清楚。先说清楚一个边界Skill 不是插件它不会给 Cursor 增加新功能按钮。它更像一份被 AI 读取的上下文文档AI 在判断「要不要用这个技能」时主要靠SKILL.md里的描述。所以写得好不好直接决定它会不会在该用的时候被触发、不该用的时候被忽略。这也是为什么后面我会反复强调description的写法。2. TaoToken 前置准备统一 Key 与 API 通道怎么拿在写 Skill 之前先把通道准备好。TaoToken 的官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址是https://taotoken.net/api这个地址不加 UTM 参数配置时直接用。你需要拿到两样东西一个 API Key一个可用的模型 ID。拿 Key 的路径是进控制台在 API Keys 页面创建一个新 Key。创建时建议按用途命名比如cursor-skill这样以后排查问题时一眼能看出是哪个场景在用。Key 创建后只显示一次复制下来存到安全的地方别直接写进会提交到 Git 的配置文件里。模型 ID 这块TaoToken 支持多种模型你在模型对话页面能看到当前可用的列表。选一个你常用的就行比如做结构化输出多的场景选一个指令遵循强的模型做长文本整理的选上下文窗口大的。记住这个 ID后面配置里要填。这里有个容易踩的坑很多人把 Base URL 写成带/v1或者带具体路径的形式结果请求 404。TaoToken 的 API 根地址就是https://taotoken.net/api具体端点由客户端拼接。你在 Cursor 里配置时填的是这个根地址不要自己加后缀。还有一点Key 的权限和额度是跟账号绑定的。如果你在多个工具里共用同一个 Key建议在控制台里留意用量避免某个 Skill 跑飞了把额度吃光。实测下来给不同用途建不同的 Key排查问题时能快速定位是哪个环节在消耗。准备好这两样之后先别急着写 Skill。我建议你先用模型对话页面做一次最简单的连通性测试发一句「你好请回复 OK」确认 Key 和模型 ID 都能正常工作。这一步能帮你排除掉大部分低级配置错误省得后面在 Skill 里排查半天结果发现是 Key 本身的问题。3. 可复制配置SKILL.md 目录结构与 Cursor 侧片段先讲目录结构。Skill 的存放位置分两种个人 Skill 放在~/.cursor/skills/所有项目都能用项目 Skill 放在项目根目录的.cursor/skills/只对当前项目生效而且可以随仓库分享给团队。最小结构就是一个文件夹加一个文件~/.cursor/skills/ └── todo-manager/ └── SKILL.md复杂一点的可以带脚本和参考资料~/.cursor/skills/ └── trend-scout/ ├── SKILL.md ├── scripts/ │ └── scan-trends.sh └── references/ └── sources.mdSKILL.md分三个部分frontmatter、Instructions、Examples。frontmatter 是元数据必须有用---包起来。最关键的是descriptionCursor 决定要不要用这个 Skill主要靠这段描述判断。写清楚两件事适合什么场景用以及不适合什么场景。后者经常被忽略但很重要——AI 不知道边界的话会在不该用的时候乱用。--- name: todo-manager description: 管理待办事项的 Skill提供结构化 JSON 结果。 Use when: 用户要添加、完成、列出待办任务。 NOT for: 项目管理排期、甘特图生成。 --- # Todo Manager Skill ## Instructions 当用户提到待办、任务、todo 时按以下规则处理 - 添加任务时解析任务名和截止日期输出 JSON。 - 标记完成时匹配任务名更新状态。 - 列出任务时只返回未完成项。 ## Examples - 增加 ToDo: 添加任务 写报告 截止 2026-01-20 - 标记完成: 完成任务 写报告 - 列出未完成任务 ## Guidelines - 所有输出尽量用 JSON。 - 不要包含无关文本。接下来是 Cursor 侧的配置。Cursor 的模型设置里可以配置自定义 API 通道。你需要填三样Base URL、API Key、Model ID。这三件套缺一不可我把它写成一份可复制的配置对照配置项填写内容Base URLhttps://taotoken.net/apiAPI Key你在控制台创建的 Key如sk-xxxxModel ID你在模型对话页面选定的模型 ID如果你用的是支持settings.json的客户端形态配置片段长这样{ models: { custom: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: 你的模型ID } } }注意路径和字段名要跟你实际使用的客户端版本一致不同版本字段可能略有差异。核心是三件套齐全Base URL 指向 TaoToken 的 API 根地址Key 用你创建的Model ID 填你选定的。填完之后保存重启一下 Cursor 让配置生效。这里再强调一次不要把 Key 硬编码进会提交到仓库的文件。项目 Skill 如果随仓库分享配置文件里用环境变量引用比如apiKey: ${TAOTOKEN_API_KEY}然后在本地环境里设置这个变量。这样团队协作时每个人用自己的 Key互不影响。4. 验证请求跑一次可复现的 Skill 调用配置好之后怎么确认 Skill 真的被触发了我给你一个可复现的验证步骤。先建一个测试用的 Skill就叫todo-manager把上面那段SKILL.md内容写进去放到~/.cursor/skills/todo-manager/SKILL.md。然后在 Cursor 里新开一个会话输入一句明确会触发它的话「添加任务 写周报 截止 2026-02-01」。如果 Skill 生效你应该看到返回的是结构化 JSON而不是一段闲聊式的回复。类似这样{ action: add, task: 写周报, due: 2026-02-01, status: pending }如果返回的是 JSON说明 Skill 被正确读取并执行了。如果返回的是普通文本先别急着改 Skill往下看排查部分。再测一个边界场景验证NOT for有没有起作用。输入「帮我排一下这个季度的项目甘特图」。因为description里写了NOT for: 项目管理排期、甘特图生成理想情况下 Cursor 不会调用这个 Skill而是用通用能力回答。这一步能验证你的边界描述是否被正确理解。如果你想更直接地验证 API 通道本身可以用 curl 打一次请求确认 Key 和地址没问题curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: 回复 OK}] }返回里能看到choices字段和内容就说明通道是通的。这一步和 Skill 验证是两件事curl 验证的是通道Cursor 里验证的是 Skill 是否被触发。两个都过了才算真正跑通。实测下来最容易出问题的是 Skill 没被触发而不是通道不通。所以验证顺序建议是先 curl 确认通道再在 Cursor 里确认 Skill 触发最后测边界场景。这样出问题时能快速定位是哪一层。5. 常见报错排查401、local proxy failed、reading choices这一节我把几个高频报错对照着讲都是真实会遇到的。401 Unauthorized。这个基本是 Key 的问题。检查三件事Key 有没有复制完整前后有没有多余空格、Key 有没有被删除或过期、请求头里的Authorization格式对不对应该是Bearer sk-xxx。如果你在 Cursor 里配的 Key 和 curl 用的不是同一个也要确认两边一致。还有一种情况是 Key 权限不足去控制台看看这个 Key 有没有被限制。local proxy failed。这个报错通常出现在客户端试图走本地代理转发的时候。先确认你的 Base URL 填的是https://taotoken.net/api没有多余后缀。然后检查客户端里有没有开启什么本地代理选项如果有关掉它让请求直连。这个报错和网络环境有关但绝大多数情况是配置里多填了路径或者开了不该开的转发。reading choices 相关报错。比如返回体里读不到choices字段或者解析失败。这通常是模型 ID 填错了或者请求体格式不对。先确认 Model ID 和你在模型对话页面看到的一致大小写、连字符都要对上。然后确认请求体是标准的messages数组格式。如果 curl 能通但 Cursor 里报这个错那大概率是 Cursor 侧的请求体构造有问题检查它的配置字段名。OAuth 相关报错。如果你在配置里看到 OAuth 字样说明客户端在尝试走 OAuth 流程但 TaoToken 用的是 API Key 认证。去设置里把认证方式改成 API Key填上你的 Key别走 OAuth。这个在部分客户端里是默认选项需要手动切换。排查时记住一个原则先用 curl 隔离通道问题再回到客户端隔离配置问题。curl 通了问题就在客户端配置curl 不通问题就在 Key 或地址。这样能省掉大量来回试的时间。另外如果你同时用了 CC Switch、Cline MCP 或者 Codex 的auth.json记得三件套要写全Base URL、Key、Model ID。少任何一个都会报错。auth.json里对应字段名可能是baseURL、apiKey、model按你实际客户端的 schema 来填。6. 把 Skill 沉淀成长期工作流Skill 写顺了之后你会发现它最大的价值不是省几次输入而是把「你脑子里的流程」变成「AI 能读的文档」。以前你靠记忆交代规范现在规范写在SKILL.md里换会话、换项目、换同事都能复用。我的建议是从最小的 Skill 开始别一上来就写复杂的。先写一个只做一件事的比如「把这段文本整理成 JSON」跑通验证流程再逐步加 Instructions 和 Examples。每加一条规则就测一次触发和边界确保它不会在不该用的时候乱用。如果你打算长期在 Cursor 里做编码和 Agent 类工作可以考虑用 Coding Plan 把额度固定下来避免临时 Key 额度不够打断流程。入口在https://taotoken.net/api对应的控制台里能找到。日常验证模型效果用模型对话页面就够了接入和排障的细节看接入文档更全。最后留一个实用技巧给每个 Skill 的description里都写上NOT for哪怕你觉得用不上。AI 的边界感全靠这句话写清楚了它才不会在你聊别的事时突然掏出待办清单。这个坑我踩过后来每个 Skill 都补上触发准确率明显稳了。