1. 先搞清楚：Skill 到底是什么，为什么不用写代码
如果你最近在 Cursor 里看到别人晒「Skill 跑通了」，第一反应可能是——这玩意儿是不是得会写 TypeScript、得懂 Agent 框架？其实不是。Cursor 的 Skill 本质就是一份 YAML 文件，你只要会打字、会描述「我希望 AI 在什么场景下按什么流程干活」，就能把它写出来。它解决的是「每次对话都要重新调教」的问题：把一套稳定的工作方式固化下来，之后输入一个触发词，Agent 就按你预设的步骤执行。
这篇面向的是零代码基础的 AI 工具用户。你不需要会写 Python，也不需要理解 Function Calling 的底层协议，只需要在 Cursor 里把模型通道配好，然后手写一份 YAML 骨架，让 Agent 跑通第一个最小任务。整个过程我实测下来，从配 Key 到看到 Agent 实际响应，30 分钟是够的。核心检索词就三个：Skill、Cursor、YAML Agent。适合谁？适合那些已经在用 Cursor 做 AI 编程、但每次都要重复贴提示词、想让流程稳定下来的人。
先说清楚 Skill 和 Rules 的区别，不然后面容易混。Rules 是永远生效的声明式约束，比如「缩进用 4 空格」「注释用中文」；Skill 是动态触发的程序化操作指南，比如「当我输入 /review 时，按以下流程审查代码」。一个是规矩，一个是手艺。Skill 的技术机制叫渐进式披露：Agent 启动时只加载每个 Skill 的元数据（名称和描述，大约 100 个 token），当模型判断需要某个 Skill 时，才加载它的完整指令。所以你的 YAML 写得再长，也不会一上来就把上下文塞爆。
那为什么要在 Cursor 里配 TaoToken？因为 Skill 跑起来要调模型，而 Cursor 默认的模型通道有时候在额度、模型切换、Key 管理上不够灵活。TaoToken 提供统一的 Key 和 API 通道，你可以在一个地方管理模型调用，Cursor 侧只需要指向这个通道就行。这样 Skill 里写的模型调用不会因为换项目、换机器就失效。下面从配置开始，一步步来。
2. TaoToken 前置：拿 Key、选通道、确认模型
在写 YAML 之前，先把模型通道打通。这一步不做，后面 Skill 跑起来会直接报 401 或连接超时。TaoToken 的官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意 API 地址后面不加 UTM 参数，配置里填的就是这个干净地址。
操作顺序是这样的：先注册登录，进控制台，在 API Keys 页面创建一个新 Key。创建的时候给它起个能认出来的名字，比如 cursor-skill-demo，方便后面排查是哪个 Key 出的问题。Key 只显示一次，复制下来先存到本地一个临时文件里，别直接贴在聊天窗口。
然后确认你要用哪个模型。Skill 场景下，我建议先用一个响应快、指令遵循稳的模型跑通流程，别一上来就挑最贵的。你可以在模型对话页面先手动发一条测试消息，确认这个 Key 和模型组合是通的。模型对话入口在这里：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。如果这一步就报错，先别往下走，把 Key 和模型确认好。
接下来是 Cursor 侧的接入。Cursor 支持自定义 OpenAI 兼容的 API 地址，所以你要做的是把 Base URL 指向 TaoToken 的 API 地址，把 API Key 填成刚才创建的那个。具体填在哪，下一节给完整的 settings.json。这里先提醒一个坑：Base URL 结尾不要多加/v1或者斜杠，不同版本的 Cursor 对路径拼接处理不一样，多写一段就容易 404。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到路径问题可以对照看。
如果你打算长期用 Skill 做编码或 Agent 任务，而不是只跑一次 demo，那可以考虑 Coding Plan，额度模型更适合持续调用：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。短期验证的话，按量用就行，不用急着上套餐。
3. 可复制配置：settings.json 与 Skill YAML 骨架
这一节给两份可以直接抄的东西。第一份是 Cursor 侧的 settings.json，第二份是 Skill 的 YAML 骨架。两份都改几个字段就能用。
先看 settings.json。Cursor 的配置文件位置在不同系统下不一样，macOS 一般在~/Library/Application Support/Cursor/User/settings.json，Windows 在%APPDATA%\Cursor\User\settings.json。如果你不确定，在 Cursor 里按Cmd/Ctrl + Shift + P，输入Open User Settings (JSON)就能直接打开。下面这份是接入 TaoToken 的最小配置：
{ "cursor.general.enableAutoComplete": true, "openai.apiKey": "你的_TaoToken_Key", "openai.baseUrl": "https://taotoken.net/api", "cursor.chat.model": "gpt-4o-mini", "cursor.chat.temperature": 0.2, "cursor.chat.maxTokens": 2048 }几个字段说明一下。openai.apiKey填你刚才创建的 Key，别带引号外的空格。openai.baseUrl就是 TaoToken 的 API 地址，结尾不要加斜杠。cursor.chat.model先填一个你确认可用的模型名，跑通之后再换。temperature设 0.2 是为了让 Skill 执行时输出稳定，别太发散。maxTokens先给 2048，够跑最小任务。
注意：不同 Cursor 版本对配置键名可能有差异，如果你填完发现不生效，去接入文档核对当前版本的键名。别硬猜，猜错了会以为是 Key 的问题。
然后是 Skill 的 YAML 骨架。Cursor 的 Skill 一般放在项目根目录的.cursor/skills/下，文件名就是 Skill 名，比如hello-skill.yaml。下面这份是一个最小可跑的骨架：
name: "HelloSkill" description: "最小可跑 Skill，接收一个主题，输出三段结构化说明" trigger: command: "/hello" languages: ["markdown", "yaml"] context: include_file_path: false include_project_root: false prompt_template: | 你是一个技术内容助手。用户会给你一个主题：{{topic}}。 请按以下结构输出，不要额外解释： 1. 这个主题是什么（一句话） 2. 它能解决什么问题（两句话） 3. 一个最小可执行的例子（三行以内） 输出语言：中文。这份骨架里，name和description是元数据，Agent 启动时只加载这两项，所以描述要写清楚「这个 Skill 干什么」，方便模型判断什么时候调用。trigger.command是触发词，你在 Cursor 聊天框输入/hello就会命中。prompt_template是核心，里面用{{topic}}占位，实际执行时会被替换成你输入的内容。context里两个开关先关掉，最小任务不需要读文件路径和项目根目录，开了反而增加干扰。
把这两份文件放好之后，别急着跑。先确认 YAML 缩进是对的——YAML 对缩进敏感，prompt_template下面的内容用两个空格缩进，|表示保留换行。如果你用 Tab 缩进，解析会直接失败。这是新手最容易踩的坑，没有之一。
4. 验证请求：让 Agent 跑通第一个任务
配置放好之后，重启 Cursor，让 settings.json 生效。然后在项目里打开聊天框，输入触发词加主题，比如：
/hello 渐进式披露如果一切正常，Agent 会按你 YAML 里定义的三段结构输出。你会看到类似这样的响应：
1. 这个主题是什么：渐进式披露是一种按需加载上下文的机制。 2. 它能解决什么问题：避免一次性把所有指令塞进上下文导致 token 浪费和注意力分散。让 Agent 只在需要时加载完整指令。 3. 最小例子：启动时只加载 Skill 元数据，命中触发词后再加载 prompt_template。看到这个输出，说明三件事都通了：Cursor 成功调用了 TaoToken 的通道，模型正确读取了 YAML 里的 prompt_template，占位符{{topic}}被正确替换。这就是最小验证动作，不需要更复杂。
如果你想再确认一次通道是通的，可以回到模型对话页面手动发一条消息，对比响应速度和质量。模型对话入口前面给过了，这里不重复贴。实测下来，Skill 触发和手动对话走的是同一个通道，所以手动能通，Skill 基本也能通。
跑通之后，你可以试着改 YAML 里的prompt_template，加一段「输出末尾附一个检查清单」，再输入/hello 测试，看输出有没有变化。这一步是确认你改的配置真的生效了，而不是 Cursor 缓存了旧版本。如果改了没变化，重启 Cursor 再试。
5. 本篇常见错排查
第一个高频错误是 401 Unauthorized。原因通常是 Key 填错、Key 被删除、或者 Key 前后有空格。排查方法：把 Key 复制到模型对话页面手动发一条消息，如果那里也 401，就是 Key 的问题；如果那里能通，就是 settings.json 里填错了。注意别把 Key 贴到公开的地方，包括截图。
第二个是 404 Not Found。这个基本是 Base URL 写错了。常见写法错误是结尾多了/v1、多了斜杠、或者把 API 地址写成了官网地址。正确写法就是https://taotoken.net/api，结尾不加任何东西。如果你用的是某个特定版本的 Cursor，它可能要求带/v1，那就以接入文档为准，别凭记忆。
第三个是 YAML 解析失败，报错类似mapping values are not allowed here。这九成是缩进问题。检查prompt_template下面的内容是不是用空格缩进，|后面有没有多余字符。还有一个隐蔽的坑：YAML 里冒号后面必须跟空格，name:"HelloSkill"是错的，name: "HelloSkill"才对。
第四个是触发词没反应。输入/hello之后 Agent 没按 Skill 执行，而是当成普通对话回复了。原因可能是 Skill 文件没放在.cursor/skills/目录下，或者文件名和name字段对不上，或者 Cursor 版本不支持 Skill。先确认目录和文件名，再确认 Cursor 版本。如果版本太旧，升级一下。
第五个是响应被截断。输出到一半停了，通常是maxTokens设太小。把 settings.json 里的maxTokens调到 4096 再试。如果还是截断，检查模型本身的最大输出限制。
排障的时候，建议按「Key → Base URL → YAML 语法 → 触发词 → 输出限制」这个顺序查，别跳着查。大部分问题都在前两步。
6. 接下来怎么走：从最小 Skill 到可复用 Agent
最小任务跑通之后，你手里就有了一套可复制的模板。接下来可以做的，是把prompt_template写得更具体，比如加一个「输出格式必须是 Markdown 表格」的约束，或者加一个「如果输入缺少必要参数，先反问」的分支。Skill 的价值不在于一次跑通，而在于你把经验固化进去之后，下次换个项目、换台机器，只要配置还在，行为就是一致的。
如果你打算把 Skill 用到长期编码或 Agent 任务上，比如让 Agent 按固定流程做代码审查、生成测试用例、整理变更日志，那模型调用会变得频繁，这时候 Coding Plan 的额度模型更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。如果只是偶尔跑几个 Skill 验证想法，按量用就行。
Key 的管理也别偷懒。建议一个用途一个 Key，比如 cursor-skill-demo 专门给 Skill 用，别和别的项目混。这样出问题的时候能快速定位是哪个环节的 Key 失效了。API Keys 页面在这里：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。
最后说一个我踩过的坑：改完 YAML 之后一定要重启 Cursor，别指望热加载。我有一次改了三遍 prompt_template 都没生效，以为是模型不听话，重启之后一次就对了。这个坑不复杂，但很耗时间。
