1. 为什么我前 30 个 Claude Code Skill 全都白写了如果你写过 Claude Code 的 Skill大概率经历过这个场景SKILL.md里 description 写得明明白白「用于 Spring Boot 接口设计」结果 Claude 愣是不触发或者触发了输出还不如裸 prompt。我去年 11 月开始写 Skill前 30 个基本可以全删——不是 Claude 不行是我把 Skill 当成了「prompt 模板升级版」方向从一开始就错了。Claude Code Skill 本质是一个任务能力包它告诉 Claude「在什么场景下、按什么规则、组合哪些工具完成任务」。它和 MCP 的分工是——MCP 负责暴露「我有什么工具」Skill 负责编排「这个场景下怎么用这些工具」。把这两件事混在一起写就是前 30 个 Skill 失效的根因。这篇面向已经写过多个 Skill 但效果不佳的开发者交付三样东西一份可直接复制的SKILL.md骨架、一份settings.json配置片段、以及用 CC Switch 把 Key/API 通道统一到 TaoToken 后的验证动作。适合谁手上有 5 个以上 Skill、但触发率低或输出不稳定的 Claude Code 用户。2. 前置准备统一 Key 与 API 通道先排除环境变量干扰Skill 不触发时很多人第一反应是改 description但忽略了更底层的问题你的 Claude Code 到底连的是哪个 API 通道。如果 Key 分散在多个环境变量、多个配置文件里排查 Skill 问题时你连「模型是不是同一个」都确认不了。我的做法是先把通道收敛到一处。TaoToken 提供统一的 Key 和 API 入口Claude Code、Codex CLI 这类工具可以共用同一个通道省掉每个工具单独配 Key 的麻烦。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。具体操作路径登录后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成一个 Key想先验证模型通不通用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息确认长期跑编码任务或 Agent看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入细节查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意先把通道统一再调 Skill。否则你改了半天 description可能只是模型换了、上下文长度变了白折腾。3. 可复制的 SKILL.md 骨架与 settings.json 配置3.1 SKILL.md 骨架主文件不超过 200 行官方建议主文件控制在 500 行以内我实测下来 200 行以内触发最稳。超出的内容拆到references/子目录Claude 按需读取这叫渐进式披露。--- name: spring-controller-skeleton description: 当用户要求新增 REST 接口、HTTP 接口、Controller或提到「加一个查询 API」「新建一个接口」时使用。生成符合公司规范的 Spring Boot Controller 代码。 --- # Spring Controller 生成规范 ## 触发场景 - 用户说「新增一个接口」「加个 Controller」「写个 REST API」 - 用户贴出接口需求文档要求实现 ## 生成规则 1. 统一返回 ResultT禁止裸返回实体 2. 参数校验用 Validated禁止在方法体内手写 if 判空 3. 异常通过 ControllerAdvice 统一处理Controller 内不写 try-catch 4. URL 命名用 kebab-case如 /user-profile ## 完整示例 java RestController RequestMapping(/user-profile) Validated public class UserProfileController { private final UserProfileService userProfileService; public UserProfileController(UserProfileService userProfileService) { this.userProfileService userProfileService; } GetMapping(/{id}) public ResultUserProfileVO getById(PathVariable Long id) { return Result.success(userProfileService.getById(id)); } }Gotchas不要用Autowired字段注入用构造器注入不要在 Controller 里直接调 Mapper不要返回MapString, Object这种弱类型结构三个关键点description 写的是**触发条件**不是功能介绍示例必须是完整可运行代码不能有 // ... your logic 这种占位符Gotchas 章节是整份文件里最值钱的部分。 ### 3.2 settings.json 配置片段 Claude Code 的配置放在 ~/.claude/settings.json把 API 通道和 Skill 目录一起配好 json { env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key }, skills: { userDir: ~/.claude/skills, projectDir: .claude/skills } }项目级 Skill 放 repo 根目录的.claude/skills/进 git 仓库团队共享个人偏好放~/.claude/skills/。冲突时项目级覆盖用户级。3.3 用 CC Switch 切换通道如果你同时用 Claude Code 和 Codex CLICC Switch 可以在多个配置间快速切换。把 TaoToken 的 Key 配成一个 profile切换后两个工具共用同一通道# 查看当前 profile cc-switch list # 切到 TaoToken 通道 cc-switch use taotoken # 确认环境变量已生效 echo $ANTHROPIC_BASE_URL # 期望输出https://taotoken.net/api4. 验证请求确认 Skill 真的被加载和触发配好之后别急着写新 Skill先验证通道和加载都正常。第一步确认 API 通道通不通curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }返回里能看到content字段就说明通道正常。第二步确认 Skill 被 Claude Code 识别。在项目里跑claude # 进入交互后输入 /skills列表里应该能看到你刚放的spring-controller-skeleton。如果没出现检查目录层级——必须是skills/{skill-name}/SKILL.md少一层或多一层都不行。第三步触发测试。直接说「帮我加一个查询用户资料的接口」观察 Claude 是否按你 SKILL.md 里的规则输出ResultT和构造器注入。如果触发了但规则没生效说明正文没被读到检查 frontmatter 的---是否闭合。5. 本篇常见错排查清单Skill 完全不触发90% 是 description 写成了功能介绍。把 description 当成搜索引擎关键词去想——用户说什么话时该匹配把这些原话作为 examples 写进去。触发了但输出不符合规则检查 SKILL.md 主体是否超过 200 行。太长会导致模型注意力分散把关键规则淹没在细则里。多个 Skill 同时触发、输出混乱description 关键词重叠。两个 Skill 出现相似触发词时要么合并要么重新切分边界。设计 Skill 和拆微服务一个道理职责单一。示例代码被原样输出你用了伪代码占位符。模型是镜子你给// ... your logic它就输出// ... your logic。所有示例必须是完整可运行代码。换个项目后风格全乱项目级和用户级 Skill 混用了。公司代码规范放项目级个人写作偏好放用户级。Codex 那边不认涉及工具调用的 Skill 不能直接复用。Codex 的工具命名和路径解析与 Claude 不同比如 Claude 的Read在 Codex 是read_file。纯指令型 Skill 可以软链复用带工具调用的各写一份。改了 Skill 没生效Claude Code 启动时只读 frontmatter正文按需加载。改完重启会话别指望热更新。6. 下一步把通道和 Skill 库一起管起来Skill 写多了之后真正卡你的不是单个 Skill 的质量而是通道和 Skill 库的版本管理。我的做法是通道统一走 TaoTokenKey 只维护一份Skill 库用 git 管理项目级和用户级分开目录。如果你还在逐个工具配 Key、逐个 Skill 调 description建议先把通道收敛。API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成一个 Key接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有 Claude Code 和 Codex 的完整配置示例。长期跑编码任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 比按量计费更划算。最后一句实操建议每次发现 Claude 在某个 Skill 下犯了一次傻就把这次的错误模式追加到 Gotchas 里。Skill 是活的不是写完就算了。我现在的 Skill 库里Gotchas 章节平均每两周就会长一条。
1. 为什么我前 30 个 Claude Code Skill 全都白写了如果你写过 Claude Code 的 Skill大概率经历过这个场景SKILL.md里 description 写得明明白白「用于 Spring Boot 接口设计」结果 Claude 愣是不触发或者触发了输出还不如裸 prompt。我去年 11 月开始写 Skill前 30 个基本可以全删——不是 Claude 不行是我把 Skill 当成了「prompt 模板升级版」方向从一开始就错了。Claude Code Skill 本质是一个任务能力包它告诉 Claude「在什么场景下、按什么规则、组合哪些工具完成任务」。它和 MCP 的分工是——MCP 负责暴露「我有什么工具」Skill 负责编排「这个场景下怎么用这些工具」。把这两件事混在一起写就是前 30 个 Skill 失效的根因。这篇面向已经写过多个 Skill 但效果不佳的开发者交付三样东西一份可直接复制的SKILL.md骨架、一份settings.json配置片段、以及用 CC Switch 把 Key/API 通道统一到 TaoToken 后的验证动作。适合谁手上有 5 个以上 Skill、但触发率低或输出不稳定的 Claude Code 用户。2. 前置准备统一 Key 与 API 通道先排除环境变量干扰Skill 不触发时很多人第一反应是改 description但忽略了更底层的问题你的 Claude Code 到底连的是哪个 API 通道。如果 Key 分散在多个环境变量、多个配置文件里排查 Skill 问题时你连「模型是不是同一个」都确认不了。我的做法是先把通道收敛到一处。TaoToken 提供统一的 Key 和 API 入口Claude Code、Codex CLI 这类工具可以共用同一个通道省掉每个工具单独配 Key 的麻烦。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。具体操作路径登录后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成一个 Key想先验证模型通不通用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息确认长期跑编码任务或 Agent看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入细节查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意先把通道统一再调 Skill。否则你改了半天 description可能只是模型换了、上下文长度变了白折腾。3. 可复制的 SKILL.md 骨架与 settings.json 配置3.1 SKILL.md 骨架主文件不超过 200 行官方建议主文件控制在 500 行以内我实测下来 200 行以内触发最稳。超出的内容拆到references/子目录Claude 按需读取这叫渐进式披露。--- name: spring-controller-skeleton description: 当用户要求新增 REST 接口、HTTP 接口、Controller或提到「加一个查询 API」「新建一个接口」时使用。生成符合公司规范的 Spring Boot Controller 代码。 --- # Spring Controller 生成规范 ## 触发场景 - 用户说「新增一个接口」「加个 Controller」「写个 REST API」 - 用户贴出接口需求文档要求实现 ## 生成规则 1. 统一返回 ResultT禁止裸返回实体 2. 参数校验用 Validated禁止在方法体内手写 if 判空 3. 异常通过 ControllerAdvice 统一处理Controller 内不写 try-catch 4. URL 命名用 kebab-case如 /user-profile ## 完整示例 java RestController RequestMapping(/user-profile) Validated public class UserProfileController { private final UserProfileService userProfileService; public UserProfileController(UserProfileService userProfileService) { this.userProfileService userProfileService; } GetMapping(/{id}) public ResultUserProfileVO getById(PathVariable Long id) { return Result.success(userProfileService.getById(id)); } }Gotchas不要用Autowired字段注入用构造器注入不要在 Controller 里直接调 Mapper不要返回MapString, Object这种弱类型结构三个关键点description 写的是**触发条件**不是功能介绍示例必须是完整可运行代码不能有 // ... your logic 这种占位符Gotchas 章节是整份文件里最值钱的部分。 ### 3.2 settings.json 配置片段 Claude Code 的配置放在 ~/.claude/settings.json把 API 通道和 Skill 目录一起配好 json { env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key }, skills: { userDir: ~/.claude/skills, projectDir: .claude/skills } }项目级 Skill 放 repo 根目录的.claude/skills/进 git 仓库团队共享个人偏好放~/.claude/skills/。冲突时项目级覆盖用户级。3.3 用 CC Switch 切换通道如果你同时用 Claude Code 和 Codex CLICC Switch 可以在多个配置间快速切换。把 TaoToken 的 Key 配成一个 profile切换后两个工具共用同一通道# 查看当前 profile cc-switch list # 切到 TaoToken 通道 cc-switch use taotoken # 确认环境变量已生效 echo $ANTHROPIC_BASE_URL # 期望输出https://taotoken.net/api4. 验证请求确认 Skill 真的被加载和触发配好之后别急着写新 Skill先验证通道和加载都正常。第一步确认 API 通道通不通curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }返回里能看到content字段就说明通道正常。第二步确认 Skill 被 Claude Code 识别。在项目里跑claude # 进入交互后输入 /skills列表里应该能看到你刚放的spring-controller-skeleton。如果没出现检查目录层级——必须是skills/{skill-name}/SKILL.md少一层或多一层都不行。第三步触发测试。直接说「帮我加一个查询用户资料的接口」观察 Claude 是否按你 SKILL.md 里的规则输出ResultT和构造器注入。如果触发了但规则没生效说明正文没被读到检查 frontmatter 的---是否闭合。5. 本篇常见错排查清单Skill 完全不触发90% 是 description 写成了功能介绍。把 description 当成搜索引擎关键词去想——用户说什么话时该匹配把这些原话作为 examples 写进去。触发了但输出不符合规则检查 SKILL.md 主体是否超过 200 行。太长会导致模型注意力分散把关键规则淹没在细则里。多个 Skill 同时触发、输出混乱description 关键词重叠。两个 Skill 出现相似触发词时要么合并要么重新切分边界。设计 Skill 和拆微服务一个道理职责单一。示例代码被原样输出你用了伪代码占位符。模型是镜子你给// ... your logic它就输出// ... your logic。所有示例必须是完整可运行代码。换个项目后风格全乱项目级和用户级 Skill 混用了。公司代码规范放项目级个人写作偏好放用户级。Codex 那边不认涉及工具调用的 Skill 不能直接复用。Codex 的工具命名和路径解析与 Claude 不同比如 Claude 的Read在 Codex 是read_file。纯指令型 Skill 可以软链复用带工具调用的各写一份。改了 Skill 没生效Claude Code 启动时只读 frontmatter正文按需加载。改完重启会话别指望热更新。6. 下一步把通道和 Skill 库一起管起来Skill 写多了之后真正卡你的不是单个 Skill 的质量而是通道和 Skill 库的版本管理。我的做法是通道统一走 TaoTokenKey 只维护一份Skill 库用 git 管理项目级和用户级分开目录。如果你还在逐个工具配 Key、逐个 Skill 调 description建议先把通道收敛。API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成一个 Key接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有 Claude Code 和 Codex 的完整配置示例。长期跑编码任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 比按量计费更划算。最后一句实操建议每次发现 Claude 在某个 Skill 下犯了一次傻就把这次的错误模式追加到 Gotchas 里。Skill 是活的不是写完就算了。我现在的 Skill 库里Gotchas 章节平均每两周就会长一条。
