企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个不加 UTM）。

具体操作路径：

• 登录后进控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
• 在 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 生成一个 Key
• 想先验证模型通不通，用模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 发一条消息确认
• 长期跑编码任务或 Agent，看 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite
• 接入细节查文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

注意：先把通道统一，再调 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. 统一返回 `Result<T>`，禁止裸返回实体 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 Result<UserProfileVO> getById(@PathVariable Long id) { return Result.success(userProfileService.getById(id)); } }

Gotchas

• 不要用@Autowired字段注入，用构造器注入
• 不要在 Controller 里直接调 Mapper
• 不要返回Map<String, 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 CLI，CC Switch 可以在多个配置间快速切换。把 TaoToken 的 Key 配成一个 profile，切换后两个工具共用同一通道：

# 查看当前 profile cc-switch list # 切到 TaoToken 通道 cc-switch use taotoken # 确认环境变量已生效 echo $ANTHROPIC_BASE_URL # 期望输出：https://taotoken.net/api

4. 验证请求：确认 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 里的规则输出Result<T>和构造器注入。如果触发了但规则没生效，说明正文没被读到，检查 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 库的版本管理。我的做法是：通道统一走 TaoToken，Key 只维护一份；Skill 库用 git 管理，项目级和用户级分开目录。

如果你还在逐个工具配 Key、逐个 Skill 调 description，建议先把通道收敛。API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 生成一个 Key，接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里有 Claude Code 和 Codex 的完整配置示例。长期跑编码任务的话，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 比按量计费更划算。

最后一句实操建议：每次发现 Claude 在某个 Skill 下犯了一次傻，就把这次的错误模式追加到 Gotchas 里。Skill 是活的，不是写完就算了。我现在的 Skill 库里，Gotchas 章节平均每两周就会长一条。