1. 为什么你的 Claude Code Skill 写了 30 个还是复用率低先说结论Claude Code Skill 不是 prompt 模板的升级版它是一个「按需加载的任务能力包」。SKILL.md 是它的入口文件frontmatter 里的name和description决定模型要不要激活它正文只在激活之后才被读进上下文。你写的 30 个 Skill 白写大概率不是模型不行而是这三件事搞反了触发条件写成了功能介绍、工具声明塞进了正文、上下文注入没有分层。我见过太多人第一次写 Skill 是这样的打开~/.claude/skills/my-skill/SKILL.md洋洋洒洒写 800 行把「请按以下规范输出」「禁止使用以下表达」「示例如下」全堆进去然后发现 Claude 加载后表现比裸调用还差。原因很直接——Claude 判断是否激活一个 Skill只看 frontmatter 的description正文再精彩激活不了就是零。你把触发条件淹没在几百行细则里模型自己都迷糊该不该用。这篇面向的是已经写过多个 Skill、但复用率低的开发者。我会把 SKILL.md 里最容易失效的三类写法拆开讲触发条件、工具声明、上下文注入。每一类都给可复制的模板和逐项验证动作你可以对着自己的 Skill 库一条条改。技术部分会占大头从目录结构、frontmatter 字段、渐进式披露到用 TaoToken 做请求验证、常见报错排查都会给完整命令和配置。适合谁看写过 5 个以上 Skill 但发现「装了跟没装一样」的人想把 Skill 从个人玩具变成团队资产的人以及正在纠结 Skill 和 MCP 边界怎么划的人。如果你还没写过 Skill也能跟做因为我会从最小可运行模板开始。先给一个判断标准你可以立刻自查打开你任意一个 Skill 的 SKILL.md只看 frontmatter 的description问自己一句——「用户说哪句话的时候这个 Skill 应该被触发」如果这句话你答不上来或者答出来跟 description 里写的对不上那这个 Skill 基本就是白写的。前 30 个 Skill 的根因八成都在这里。2. TaoToken 前置准备给 Skill 验证搭一个稳定的请求入口Skill 写完不是靠感觉判断好坏的得能真实发请求、看返回、对比触发率。这一步先把请求入口搭好后面验证 Skill 触发、调试工具声明、排查报错都要用它。我用的是 TaoToken 作为统一的模型请求入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 这个地址不加 UTM 参数。为什么验证 Skill 需要一个稳定入口因为 Skill 的触发和工具调用最终都要落到一次真实的模型请求上。你在本地改完 SKILL.md得能立刻发一条请求看模型有没有按预期激活 Skill、有没有正确调用工具。如果每次都要换 key、换地址、换模型调试成本会高到让你放弃迭代。TaoToken 的好处是 Base URL 和 Key 一套配置Claude Code、Codex、Cline 这些客户端都能接切换成本低。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。这个 Key 后面会填到各个客户端的配置里。注意 Key 只显示一次丢了就重新建一个别硬找。然后确认你要用的模型 ID。在模型对话页面 https://taotoken.net/models 可以看到当前可用的模型列表把你要用的模型 ID 记下来比如 Claude 系列、Codex 系列的具体标识。Skill 验证阶段建议固定一个模型别今天换一个明天换一个否则触发率波动你分不清是 Skill 的问题还是模型的问题。如果你是要长期跑编码和 Agent 任务可以看下 Coding Plan 页面 https://taotoken.net/coding-plan 它更适合高频调用场景。接入文档在 https://taotoken.net/doc 里面有各客户端的完整配置示例遇到字段不确定的时候直接对照。这一步的验证动作很简单拿到 Key 和模型 ID 之后先用最朴素的方式发一条请求确认链路通。可以用 curlcurl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: 你的模型ID, messages: [ {role: user, content: 回复 ok 两个字母即可} ] }把$TAOTOKEN_API_KEY换成你刚创建的 Key你的模型ID换成实际模型标识。返回里能看到choices[0].message.content就说明链路通了。这一步不通后面所有 Skill 验证都是空中楼阁先把这个解决掉。3. 可复制配置SKILL.md 三类失效写法与正确模板这一节是全文核心。我把 SKILL.md 的失效写法归成三类触发条件失效、工具声明失效、上下文注入失效。每一类先给错误示例再给正确模板最后给验证动作。你可以直接复制模板改。3.1 触发条件失效description 写成了功能介绍错误写法长这样--- name: spring-boot-api description: 这个 Skill 提供了完整的 Spring Boot 项目代码生成能力支持多种数据库适配能生成 Controller、Service、Mapper 等各类代码。 ---这段 description 告诉模型的是「我能做什么」但模型决定触发的逻辑是「什么时候轮到我做」。正确写法要把触发条件写进去最好带上用户实际会说的话--- name: spring-boot-api description: 在用户要求生成 Spring Boot 接口、Controller、Service 代码或提到「新建一个 REST 接口」「加一个查询 API」「写个 Controller」时使用。适用于 Spring Boot 3.x 项目。 ---差别在哪第二种把「用户说什么话时触发」写清楚了。模型匹配的是语义你给的触发短语越接近用户真实表达触发率越高。我实测下来把 description 从功能介绍改成触发条件同一个 Skill 的触发率能从三成提到八成以上。验证动作改完 description 后用三种不同说法各发一条请求看是否都触发。比如「帮我写个查询用户的接口」「新建一个 REST 接口」「加一个 Controller」三条都触发才算合格。只触发一条说明你的触发短语覆盖不够继续补。3.2 工具声明失效把工具调用写进了正文错误写法是在 SKILL.md 正文里写一堆「请按以下格式 curl」「然后 jq 解析返回值」## 查询订单 请执行以下命令查询订单状态 curl -X GET https://internal-api/order/$ORDER_ID -H Authorization: ... 然后用 jq 解析返回的 JSON提取 status 字段。这种写法运行起来时不时翻车因为模型对长 URL 和复杂 jq 表达式的处理不稳定。正确做法是把工具用 MCP 暴露Skill 只负责「什么时候用这个工具、怎么组合多个工具完成任务」。Skill 是任务能力包不是工具调用器。如果你确实需要在 Skill 里声明工具用 frontmatter 的allowed-tools字段而不是在正文里写命令--- name: order-query description: 在用户询问订单状态、订单详情、物流信息时使用。 allowed-tools: - mcp__order-service__query_order - mcp__order-service__query_logistics ---这样工具声明和任务编排就分开了。工具本身的能力由 MCP server 提供Skill 只声明「这个任务允许用哪些工具」。验证动作把 Skill 里所有 curl、jq、文件路径命令删掉改成allowed-tools声明。然后发一条请求看模型是否通过 MCP 工具调用完成任务而不是在正文里拼命令。如果模型还在拼命令说明你的 MCP server 没接好或者工具名写错了。3.3 上下文注入失效主文件塞太满没有分层错误写法是把所有细节都堆在主文件里1200 行 SKILL.md颜色系统、字体规则、错误处理全在里面。正确做法是渐进式披露主文件给 overview细节拆到references/子目录模型按需读取。目录结构长这样~/.claude/skills/frontend-design/ ├── SKILL.md └── references/ ├── color-systems.md ├── typography.md └── anti-patterns.md主文件控制在 200 行以内只写触发条件、核心规则、Gotchas 章节以及「需要细节时读哪个子文件」的指引--- name: frontend-design description: 在用户要求构建 Web 组件、页面、仪表盘、React 组件、HTML/CSS 布局或提到「美化 UI」「设计页面」时使用。 --- # Frontend Design ## 核心规则 - 避免千篇一律的紫色渐变 - 不要在 hero 区域堆 emoji - 不要用 Tailwind 默认配色凑合 ## 需要细节时 - 颜色系统读 references/color-systems.md - 字体规则读 references/typography.md - 反模式清单读 references/anti-patterns.md ## Gotchas - 模型容易在 hero 区域堆 emoji发现即删 - 模型容易用默认紫色渐变强制换色验证动作把主文件行数压到 200 行以内超出部分拆到references/。然后发一条请求看模型是否只在需要时才读子文件而不是一次性全读进来。如果模型把子文件全读了说明主文件里的指引不够明确或者子文件命名太泛。3.4 项目级与用户级 Skill 的配置路径项目级 Skill 放在 repo 根目录的.claude/skills/或.agents/skills/进 git 仓库团队共享。用户级 Skill 放在~/.claude/skills/个人偏好。冲突时项目级覆盖用户级。# 项目级进 git团队共享 mkdir -p .claude/skills/spring-controller-skeleton vim .claude/skills/spring-controller-skeleton/SKILL.md # 用户级个人偏好 mkdir -p ~/.claude/skills/commit-msg-zh vim ~/.claude/skills/commit-msg-zh/SKILL.md验证动作把公司代码规范放项目级个人写作偏好放用户级。然后换一个项目看个人偏好是否被带过去——如果带过去了说明你放错了层级。4. 验证请求与成功结果用真实请求确认 Skill 生效配置写完得用真实请求验证。这一步给完整的验证流程和成功结果的样子。先确认 Skill 目录结构正确ls -la ~/.claude/skills/ # 应该看到你的 Skill 目录每个目录下有 SKILL.md然后发一条会触发 Skill 的请求。以commit-msg-zh为例在 Claude Code 里输入「帮我写个 commit message」观察是否触发。成功的结果是模型按 Conventional Commits 格式输出body 用中文且不出现「修改了 xxx 文件」这种无信息量描述。如果你想用 API 方式验证可以发一条带 Skill 上下文的请求curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: 你的模型ID, messages: [ {role: system, content: 你是一个编码助手可用 Skillcommit-msg-zh}, {role: user, content: 帮我写个 commit message我改了用户登录的 token 过期时间} ] }成功返回里choices[0].message.content应该是一段符合 Conventional Commits 的 commit message比如fix(auth): 延长 token 过期时间加中文 body。如果返回的是裸回答、没有按格式走说明 Skill 没被正确加载。再验证工具声明类 Skill。以order-query为例发一条「查一下订单 12345 的状态」成功结果是模型调用 MCP 工具mcp__order-service__query_order而不是在正文里拼 curl 命令。你可以在返回的tool_calls字段里看到工具调用记录。验证上下文注入类 Skill。以frontend-design为例发一条「帮我设计一个登录页」成功结果是模型先读主文件再按需读references/color-systems.md输出里不会出现默认紫色渐变和 hero emoji。如果输出里还有这些说明 Gotchas 章节没生效或者子文件没被读到。三个验证都过了你的 Skill 才算真正可用。只过一两个回去改对应的那一类写法。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节列真实会遇到的报错和排查路径。每个报错给现象、原因、解决动作。5.1 401 Unauthorized现象请求返回 401提示 invalid api key 或 unauthorized。原因Key 没填对、Key 过期、或者 Authorization header 格式错了。排查动作先确认 Key 是从 https://taotoken.net/api-keys 复制出来的完整字符串没有多余空格。再确认 header 格式是Authorization: Bearer $KEYBearer 后面有一个空格。如果用的是客户端配置检查配置文件里的 key 字段有没有被引号包错。# 快速验证 Key 是否有效 curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY返回模型列表说明 Key 有效返回 401 说明 Key 有问题重新建一个。5.2 local proxy failed现象客户端报 local proxy failed 或 connection refused。原因本地代理配置和实际网络环境不匹配或者 Base URL 填错了。排查动作检查客户端配置里的 Base URL 是不是https://taotoken.net/api注意结尾不要多加/v1或斜杠。如果你之前配过其他地址清掉重填。再检查本地有没有残留的代理环境变量env | grep -i proxy # 如果有输出unset 掉 unset HTTP_PROXY HTTPS_PROXY ALL_PROXY5.3 reading choices 报错现象返回里choices字段读不到或者报 reading choices of undefined。原因请求体格式不对或者模型 ID 写错了返回的是错误结构而不是正常响应。排查动作先看完整返回不要只看choices。如果返回里有error字段按 error 信息处理。常见的是模型 ID 写错去 https://taotoken.net/models 核对实际模型标识。再检查请求体 JSON 是否合法messages是不是数组。# 打印完整返回定位错误 curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d {model:你的模型ID,messages:[{role:user,content:hi}]} | jq .5.4 OAuth 相关报错现象Claude Code 或 Codex 报 OAuth 失败、token 过期。原因客户端走了 OAuth 流程但你的配置应该走 API Key 方式。排查动作确认客户端配置里用的是 API Key不是 OAuth。Claude Code 的配置在~/.claude/settings.jsonCodex 的配置在~/.codex/auth.json。以 Codex 为例auth.json里应该写全三件套{ base_url: https://taotoken.net/api, api_key: 你的Key, model: 你的模型ID }Base URL、Key、Model ID 三件套缺一不可。只填 Key 不填 Base URL客户端会走默认地址报 OAuth 或 401。只填 Base URL 不填 Model ID请求会失败或走错模型。5.5 Skill 不触发现象Skill 装好了但发请求时模型不激活它。原因九成是 description 写错了或者 Skill 目录结构不对。排查动作先确认 SKILL.md 在正确路径下~/.claude/skills/{name}/SKILL.md文件名大小写要对。再检查 frontmatter 格式name和description必须有且---分隔符不能少。最后按 3.1 的方法用三种不同说法测试触发。# 确认目录结构 find ~/.claude/skills -name SKILL.md -maxdepth 2如果目录结构对、frontmatter 对、触发短语也覆盖了还是不触发那就是模型对这类任务的匹配阈值问题把 description 里的触发短语写得更具体、更接近用户原话。6. 语义一致 CTA把 Skill 验证和请求入口固定下来Skill 写到最后拼的不是谁写得快是谁的验证闭环短。你改完 SKILL.md能立刻发请求、看触发、对比结果迭代速度就快。这个闭环里请求入口是基础设施。我现在的做法是把 TaoToken 作为固定入口Base URL 写https://taotoken.net/apiKey 从 https://taotoken.net/api-keys 拿模型 ID 在 https://taotoken.net/models 核对。三件套固定下来Skill 验证就只剩改 SKILL.md 一件事。如果你还在用裸 prompt 跟 Claude Code 一来一回拉锯某种程度上就像还在用 ant 编译 Java 项目——能跑但下个台阶已经迟到了。Skill 库的丰富度和设计质量正在变成「会用 AI 工具」的新门槛。排障和接入相关的直接看接入文档 https://taotoken.net/doc 里面有各客户端的完整配置。想先验证模型表现的去模型对话 https://taotoken.net/models 试几条请求。长期跑编码和 Agent 任务的看 Coding Plan https://taotoken.net/coding-plan 高频调用场景更合适。最后给一个我每天都在用的动作每次发现 Claude 在某个 Skill 下犯了一次傻就把这次的错误模式追加到 Gotchas 章节。Skill 是活的不是写完就算了。你前 30 个 Skill 白写很可能就是因为它们从写完那天起就没再改过。