1. 为什么你写的 SKILL.md 在 Claude 里总是不触发
很多人第一次接触 AI Skill 机制，都是被一句话吸引的：写一个 Markdown 文件，AI 就能按你的流程干活。听起来像给模型装了个插件，实际动手却发现——文件放进去了，Claude 和 Cursor 却像没看见一样，该聊天还是聊天，触发词喊破喉咙也不执行。
我先把结论放前面：SKILL.md 不触发，九成不是模型笨，而是目录结构、frontmatter 字段、触发描述这三件事里至少错了一件。Skill 的本质是一个“约定大于配置”的文件夹，AI 应用靠扫描固定路径 + 解析元信息来决定要不要加载它。你少写一个 name，或者把文件放错一层，扫描就直接跳过了。
先讲清楚 Skill 到底是什么。你可以把它理解成给 AI 看的一份“岗位操作手册”：一个文件夹，里面一份 SKILL.md 作为入口，写清楚这个技能干什么、什么时候用、按什么步骤执行、输出成什么格式。模型在收到用户请求时，会先看所有已注册 Skill 的描述，判断哪个匹配当前意图，匹配上了才把这份手册读进上下文，然后照着执行。
它适合谁？适合那些反复用同一套提示词、反复“拷打”模型改输出的人。比如你每天都要把长文总结成三点、每周都要按固定模板生成周报、每次都要按同一套规则审查代码。这些重复劳动，写成一个 Skill 就固化了，下次一句话触发。
那为什么标题里要带上 TaoToken？因为 Skill 触发之后，真正干活的是背后的模型调用。Claude、Cursor 这类工具本身要连模型服务，如果你每个工具配一套 Key、一套地址，管理起来很乱。用 TaoToken 做统一入口，一个 Key、一个 Base URL，Claude Code、Cursor、Cline 都能指向同一处，Skill 在哪个工具里触发，模型调用都走同一条链路，排查问题也只看一个地方。
这一篇我会带你走完整条路：先搭出能被识别的 SKILL.md 目录结构，再配好 TaoToken 的统一接入，然后实测一次 Skill 触发，最后把常见的报错一个个拆开。全程可复制，你跟着敲就行。
需要先说明一点：Skill 的目录约定在不同工具里略有差异，Claude Code 走的是.claude/skills/，Cursor 走的是项目内约定目录。下面我会把两种都写出来，你按自己用的工具选。
2. TaoToken 前置准备：统一 Key 与 Base URL 怎么配
在写 Skill 之前，先把模型接入这条链路打通。否则你 SKILL.md 写得再漂亮，触发后调用模型那一步 401，前面全白费。
TaoToken 在这里扮演的角色是统一接入层。你注册后拿到一个 API Key，所有支持自定义 Base URL 的工具都指向https://taotoken.net/api，模型 ID 按需选。这样 Claude Code、Cursor、Cline 共用一套凭证，Skill 在哪个工具里跑，模型调用都一致。
第一步，拿 Key。打开 https://taotoken.net/api-keys ，登录后创建一个新的 API Key，复制保存。注意这个 Key 只在创建时完整显示一次，丢了就重新建一个。
第二步，记下 Base URL：https://taotoken.net/api。注意这里不带任何多余路径，很多工具要求你填到/v1或者根路径，具体看工具说明，但源头都是这个地址。
第三步，确认你要用的 Model ID。Skill 触发后调用的模型，取决于你在工具里配置的默认模型。Claude 系列、DeepSeek 系列等都可以在模型列表里查到，填的时候用准确的 ID，别自己拼。
这里有个关键点：Skill 本身不绑定模型。SKILL.md 里写的是“怎么干活”，用哪个模型是工具配置决定的。所以你可以同一个 Skill，在 Claude Code 里用 Claude 跑，在 Cursor 里换成别的模型跑，只要 Base URL 和 Key 指向 TaoToken 就行。
如果你用的是 Claude Code，接入方式是在配置里指定 Anthropic 兼容的 Base URL 和 Key。具体路径参考官方文档 https://taotoken.net/doc ，里面有各工具的接入示例。Cursor 则在设置里的 Models 面板，填入 OpenAI 兼容的 Base URL 和 Key，再选模型。
我建议你先把这一步单独验证通过，再去写 Skill。验证方法很简单：在工具里发一句“你好”，能正常回复，说明接入没问题。如果这一步就报错，先解决接入，别往下走。
配好之后，你的三个要素就齐了：Base URL 是https://taotoken.net/api，Key 是刚创建的那串，Model ID 是你在工具里选定的。这三件套后面在排障章节还会反复用到，先记牢。
3. 可复制配置：SKILL.md 目录结构与 settings 片段
这一节是核心，直接给你能抄的结构和配置。先讲目录，再讲 SKILL.md 内容，最后给工具的 settings 片段。
3.1 目录结构
一个能被识别的 Skill，最小结构是这样：
your-project/ ├── .claude/ │ └── skills/ │ └── summarize/ │ └── SKILL.md如果你用 Cursor，约定目录换成项目内的 skills 文件夹，结构类似：
your-project/ ├── .cursor/ │ └── skills/ │ └── summarize/ │ └── SKILL.md关键点：文件夹名summarize就是这个 Skill 的标识，SKILL.md 必须直接放在这个文件夹下，不能多套一层。很多人失败就是把 SKILL.md 放在了 skills 根目录，或者多包了一层 src，扫描直接跳过。
3.2 SKILL.md 内容
SKILL.md 开头需要一段 frontmatter，用三个短横线包起来，声明元信息。这是模型判断“要不要用这个技能”的依据，写不好就不触发。
--- name: summarize description: 将长文本总结为三个要点，每点不超过30字。当用户要求总结、提炼、概括一段文字时使用。 --- # 文本总结技能 ## 工作内容 把用户提供的长文本，压缩成三个要点的短摘要。 ## 执行步骤 1. 通读用户提供的文本，识别核心信息。 2. 提炼出三个最重要的要点。 3. 每个要点控制在30字以内，去掉连接词和修饰语。 4. 按编号列表输出。 ## 输出格式 1. 要点一 2. 要点二 3. 要点三 ## 约束 - 不添加原文没有的信息。 - 不使用“首先”“其次”这类连接词。 - 如果文本不足三个要点，有几个写几个。name和description是触发关键。description 要写清楚“什么时候用”，把用户可能说的触发词覆盖进去，比如“总结”“提炼”“概括”。模型就是靠这句话做匹配的。
3.3 工具 settings 片段
Claude Code 的配置，在项目根目录或用户目录下的 settings 文件里指定接入。JSON 片段如下：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoToken Key" } }Cursor 的配置在设置面板里填，对应字段是 OpenAI 兼容的 Base URL 和 Key：
{ "openai.baseUrl": "https://taotoken.net/api", "openai.apiKey": "你的TaoToken Key", "openai.model": "你的Model ID" }如果你用 Cline 这类支持 MCP 的工具，配置里同样填 Base URL、Key、Model ID 三件套。Cline 的 MCP 配置片段：
{ "mcpServers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "你的TaoToken Key", "model": "你的Model ID" } } }注意：上面所有片段里的 Key 和 Model ID 都要换成你自己的。Base URL 统一是https://taotoken.net/api，不要加/v1后缀，除非工具明确要求。
配好之后，重启工具，让它重新扫描 skills 目录。这一步别省，很多“不触发”就是没重启导致的。
4. 验证请求：一次 Skill 触发与结果确认
配置齐了，现在实测。我以 Claude Code 为例，Cursor 流程一样。
第一步，确认 Skill 被识别。在 Claude Code 里输入/skills或者查看技能列表（不同版本命令略有差异，参考文档 https://taotoken.net/doc ）。如果列表里出现了summarize，说明目录和 frontmatter 都对了。没出现，回到上一节检查路径。
第二步，触发。直接输入一段长文本，然后说“帮我总结一下”。注意，触发词要和你 description 里写的一致。我写的是“总结、提炼、概括”，所以用这三个词都行。
第三步，看输出。正常情况下，模型会按 SKILL.md 里的步骤，输出三个编号要点，每点不超过30字，没有连接词。如果它只是普通地总结了一大段，说明 Skill 没被加载，模型走了默认行为。
第四步，确认模型调用走的是 TaoToken。这一步怎么验证？看工具的请求日志，或者在 TaoToken 控制台 https://taotoken.net/console 看调用记录。如果能看到这次请求，说明 Base URL 和 Key 生效了。
我实测下来，第一次触发最容易出的问题是：Skill 被识别了，但模型没按格式输出。这通常是 description 写得太模糊，模型不确定该不该严格照做。解决办法是把 description 写得更具体，把触发场景和输出要求都塞进去。
再给一个验证技巧：故意在 SKILL.md 里写一条特殊约束，比如“输出末尾加上 [summarize-done]”。如果触发成功，输出里就会带这个标记。这是确认 Skill 真正生效的最直接方法，比看格式靠谱。
如果你用的是 Cursor，触发方式是在对话里直接描述任务，Cursor 会自动匹配 Skill。验证逻辑一样：看输出是否符合 SKILL.md 的约束，看 TaoToken 控制台有没有调用记录。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节把真实会撞上的报错一个个拆开。每个都给你现象、原因、解法。
5.1 401 Unauthorized
现象：工具里发消息，直接返回 401，或者提示 authentication failed。
原因：Key 不对，或者 Base URL 和 Key 不匹配。常见的是 Key 复制时带了空格，或者用了别的平台的 Key 填到 TaoToken 的地址上。
解法：重新去 https://taotoken.net/api-keys 复制 Key，确认没有多余字符。检查 Base URL 是不是https://taotoken.net/api，别写成别的。如果还不行，新建一个 Key 试。
5.2 local proxy failed
现象：提示本地代理失败，连接被拒绝。
原因：工具配置里残留了旧的代理设置，或者 Base URL 填成了本地地址。有些工具默认走 localhost 代理，你换了接入地址但没改这个配置。
解法：检查工具的代理设置，关掉本地代理，Base URL 直接填https://taotoken.net/api。如果你之前配过别的中转，把旧配置清干净。
5.3 reading choices 报错
现象：返回结构解析失败，提示 reading 'choices' 或类似字段缺失。
原因：Base URL 和工具的协议不匹配。比如工具按 OpenAI 格式解析，但你填的地址返回的是 Anthropic 格式，字段对不上。
解法：确认工具要求的协议。Cursor、Cline 走 OpenAI 兼容格式，Claude Code 走 Anthropic 格式。TaoToken 的https://taotoken.net/api支持对应协议，但你要在工具里选对模式。如果工具支持切换，切到正确的协议。
5.4 OAuth 相关报错
现象：提示 OAuth 认证失败，或者要求登录授权。
原因：工具默认走 OAuth 登录流程，但你用的是 API Key 接入，两者冲突。
解法：在工具设置里关掉 OAuth 登录，改成 API Key 模式。Claude Code 里对应的是把认证方式从 OAuth 切到 API Key，填上 TaoToken 的 Key。
5.5 Skill 不触发（非报错类）
现象：没有报错，但 Skill 就是不生效。
原因：三种可能。一是目录结构不对，SKILL.md 没放在正确位置。二是 frontmatter 缺 name 或 description。三是没重启工具，扫描没刷新。
解法：对照第 3 节的目录结构逐层检查，确认 SKILL.md 直接在技能文件夹下。检查 frontmatter 两个字段都在。重启工具。
排障时记住三件套：Base URL、Key、Model ID。任何接入问题，先把这三个对齐，再去查 Skill 本身。大部分报错都出在这三件套上，而不是 SKILL.md 写错了。
6. 把 Skill 用起来：从单文件到工作流的下一步
到这里，你已经能跑通一个最小 Skill 了。但 Skill 真正的价值不在单个文件，而在把一整套流程拆成多个 Skill，让它们协同干活。
比如你要做一个“行业分析”工作流，可以拆成三个 Skill：一个负责抓取数据，一个负责清洗整理，一个负责分析输出。每个 Skill 一份 SKILL.md，放在同一个项目目录下。触发时，模型会按你的描述依次调用，形成流水线。
这种项目级 Skill 的写法，和单文件没本质区别，只是文件夹多了几个，description 要写清楚各自的职责边界，避免模型调错。你可以先从一个 Skill 跑通，再逐步加。
如果你打算长期用 Skill 做编码或 Agent 类任务，建议了解一下 Coding Plan，它更适合高频、长时间的模型调用场景，地址是 https://taotoken.net/coding-plan 。日常验证模型效果，用模型对话就行：https://taotoken.net/chat 。
最后给一个实用技巧：写 SKILL.md 的时候，别一次写完美。先写个最小版本，触发一次，看输出哪里不对，再回去改 description 和约束。Skill 是迭代出来的，不是一次写对的。我试过把 description 改了四五版，触发才稳定。
现在你可以动手了：建一个my-first-skill文件夹，放上你的第一份 SKILL.md，配好 TaoToken 的三件套，触发一次，看结果。跑通之后，再把它扩成你的第一个工作流。
