企业官网建设流程全解析

1. 为什么你的 skills 目录越写越像提示词垃圾场

很多人第一次接触 Claude Code 的 skills 目录，直觉反应就是「这不就是个放提示词的地方吗」，于是把接口规范、错误码表、发布流程、代码风格、老系统背景全塞进一个 SKILL.md，越写越长，最后连自己都懒得翻。问题不在于你写得不够多，而在于你把两种完全不同职责的东西混在了一个文件里。

Claude Code 的配置体系其实分三层。CLAUDE.md 是项目里的长期共识，会话一开始就完整加载，适合放那些永远成立的短规则，比如启动命令、模块边界、代码风格总原则。settings.json 是强制执行的权限和钩子配置，管的是能不能做、什么时候做。而 skills/ 是第三层，它更像一个按需打开的工具抽屉，负责把某类重复任务做成可调用、可组合、可携带的能力模块。

这三层的加载时机完全不同。CLAUDE.md 是常驻的，你写多少它就占多少上下文。skills/ 默认只把 description 放进上下文，完整内容等你真正用到时才加载。这个差异决定了它们的写法必须不一样：CLAUDE.md 要短要稳，SKILL.md 要准要能导航。

我见过最典型的翻车场景是这样的：一个团队想让 Claude Code 遵守接口约定，于是把命名规范、错误码、分页格式、鉴权策略、事务边界、日志规范全写进一个 SKILL.md，写了八百多行。结果 Claude 每次触发这个 Skill，这八百行就整段进入对话，后面几轮都跟着走。上下文被塞满，任务边界反而更糊。大模型不是拿到信息越多就越稳，噪声一多，它判断重点的能力就下降。

所以这篇文章要解决的核心问题就一个：SKILL.md 和 CLAUDE.md 到底各自该装什么，边界画在哪里，怎么用一次真实任务验证这个分工有没有生效。适合已经上手 Claude Code、但把 skills 目录当成提示词仓库堆放的开发者。下面我会给出目录结构示例、两份可复制的配置，以及一次触发验证的完整过程。

2. TaoToken 前置：把 Claude Code 的模型通道先接稳

在讨论 skills 目录之前，得先保证 Claude Code 本身能正常跑起来。因为后面验证 SKILL.md 触发效果时，你需要一个稳定的模型通道，不然触发失败你分不清是 Skill 写错了还是请求根本没通。

TaoToken 在这里的角色是提供一个统一的模型接入入口，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。它不替代 Claude Code 这个编辑器或 CLI 本身，只是把模型请求这条路铺好，让你在配置 skills 的时候不用同时折腾网络和鉴权。

你需要准备三样东西，这三样在后面所有配置里都会反复出现，我把它叫做三件套：Base URL、API Key、Model ID。Base URL 就是 https://taotoken.net/api ，API Key 在控制台生成，Model ID 按你实际要用的模型填。这三件套缺一个，Claude Code 就会在启动或首次请求时报错。

生成 Key 的入口在控制台，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，进去之后创建 API Key，复制出来先存好。如果你还没决定用哪个模型，可以先到模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 试一下，确认模型能正常响应，再回到 Claude Code 里配。

这里有个顺序建议：先把模型通道验证通，再去写 skills。因为 Skill 的触发依赖模型对 description 的理解，如果通道本身不稳，你会把通道问题误判成 Skill 写法问题，排查方向就歪了。我试过先写一堆 Skill 再配通道，结果触发一直不灵，最后发现是 Key 没生效，白白改了半天 description。

对于长期要做编码和 Agent 任务的场景，可以考虑 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合持续性的开发工作流。如果你只是想先验证 skills 分工，用按量的 Key 就够了。

配置文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，API Keys 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。Claude Code 相关的接入说明可以参考 https://taotoken.net/doc/claudecode?utm_source=taotoken_aicg_blog_end&utm_content=ClaudeCodeAnthropic&utm_campaign=rewrite ，里面有针对 Anthropic 风格接口的配置方式。

把这三件套准备好之后，Claude Code 的模型请求就能走通。接下来才是重点：在这个已经能跑的环境里，怎么把 CLAUDE.md 和 SKILL.md 的职责分开。

3. 可复制配置：CLAUDE.md 与 SKILL.md 的职责边界

这一节是全文的核心，我会给出两份可以直接复制的配置，一份是 CLAUDE.md，一份是 SKILL.md，然后逐段解释为什么这么分。

先看 CLAUDE.md。它的定位是常驻共识，所以只放那些每次会话都必须知道、而且永远成立的短规则。不要放长文档，不要放流程细节，不要放参考资料。

# 项目约定 ## 启动与构建 - 安装依赖：pnpm install - 本地启动：pnpm dev - 构建：pnpm build - 测试：pnpm test ## 代码风格总原则 - TypeScript 严格模式，禁止 any - 组件文件用 PascalCase，工具函数用 camelCase - 提交前必须通过 lint 和 typecheck ## 模块边界 - src/api 只放路由和请求处理 - src/components 只放 UI 组件 - src/lib 放纯函数和工具 ## 详细规范位置 - 接口设计规范见 .claude/skills/api-design/ - 测试策略见 .claude/skills/test-writing/ - 发布流程见 .claude/skills/deploy/

这份 CLAUDE.md 很短，但它把「去哪里找详细规范」这件事写清楚了。这就是职责边界的第一条：CLAUDE.md 负责导航，不负责承载细节。

再看 SKILL.md。它放在 .claude/skills/api-design/SKILL.md，负责接口设计这一类重复任务。

--- name: api-design description: Apply API design rules for TypeScript backend routes, including Zod validation, response shape, and error codes --- When editing backend route handlers under src/api, follow these rules. ## 输入校验 - 所有请求体必须用 Zod schema 校验 - schema 定义放在同目录的 schema.ts - 校验失败返回 400，错误信息用 { error: string } ## 响应格式 - 成功返回 { data: T } - 失败返回 { error: string } - 分页返回 { data: T[], page: number, pageSize: number, total: number } ## 错误码 - 400 参数错误 - 401 未认证 - 403 无权限 - 404 资源不存在 - 500 服务端错误 ## 详细资料 - 完整错误码表见 reference.md - 标准接口样例见 examples.md - 校验脚本见 scripts/validate-api.sh

注意这份 SKILL.md 的写法：正文只写执行规则，详细资料全部指向支持文件。这就是职责边界的第二条：SKILL.md 负责约束和导航，不负责堆资料。

现在把两份配置放在一起对比，边界就很清楚了。

还有一个关键字段要讲清楚：description。它是 Claude Code 判断是否自动触发这个 Skill 的主要依据。很多人 Skill 效果不好，不是 Claude 不会用，而是 description 写得太泛。像 help with backend 这种描述几乎没有辨识度，Claude 不知道它该在 API 路由、数据库模型还是鉴权中间件里触发。写成 Apply API design rules for TypeScript backend routes 就清楚很多。

如果你用的是 Cline MCP 或 Codex 的 auth.json 配置，三件套同样要写全。以 Codex 的 auth.json 为例，Base URL 填 https://taotoken.net/api ，Key 填你生成的 API Key，Model ID 填实际模型名。Cline MCP 的配置里也是这三样，缺一个就会在请求时报错。

{ "baseUrl": "https://taotoken.net/api", "apiKey": "your-api-key-here", "model": "your-model-id" }

这份 JSON 里的三个字段就是三件套，路径和字段名按你实际使用的工具调整，但内容不能少。CC Switch 这类切换工具也是同样的逻辑，切换的是通道，不是 Skill 本身。

把配置写完之后，下一步是验证。光看配置看不出分工有没有生效，必须跑一次真实任务。

4. 验证请求：一次任务触发看两者分工是否生效

配置写完不算完，得用一次真实任务验证 CLAUDE.md 和 SKILL.md 的分工到底有没有生效。我设计了一个很简单的验证方法：构造一个应该触发 api-design 的任务，和一个不应该触发的任务，看 Claude Code 的反应。

先确认目录结构。在项目根目录下，应该是这样：

project/ ├── CLAUDE.md ├── .claude/ │ └── skills/ │ └── api-design/ │ ├── SKILL.md │ ├── reference.md │ ├── examples.md │ └── scripts/ │ └── validate-api.sh └── src/ └── api/ └── user.ts

第一个验证任务：应该触发。在 Claude Code 里输入：

帮我在 src/api/user.ts 里加一个获取用户列表的接口，要支持分页

这个任务涉及 src/api 下的路由文件，而且明确提到分页，正好命中 api-design 的 description。预期结果是 Claude Code 自动加载 api-design，然后按 SKILL.md 里的规则写代码：用 Zod 校验、返回 { data, page, pageSize, total }、错误码用 400/401 这些。

如果触发成功，你会看到 Claude 在写代码前提到它参考了 api-design 的规则，或者直接按规则输出。如果没触发，它可能就随便写一个返回数组的接口，没有分页字段，也没有 Zod 校验。

第二个验证任务：不应该触发。输入：

帮我把 src/components/Header.tsx 的标题颜色改成蓝色

这个任务是改 UI 组件，跟 API 设计无关。预期结果是 api-design 不触发，Claude 直接改样式。如果它莫名其妙开始讲接口规范，说明 description 写得太泛，触发边界糊了。

第三个验证任务：验证 CLAUDE.md 的常驻性。新开一个会话，输入：

这个项目怎么启动

预期结果是 Claude 直接回答 pnpm dev，因为它从 CLAUDE.md 里读到了启动命令。这个不需要任何 Skill 触发，因为 CLAUDE.md 是会话开始就加载的。

三个任务跑完，分工是否生效就清楚了。如果第一个任务触发、第二个不触发、第三个直接答对，说明边界画对了。如果第一个不触发，去检查 description 是不是太泛；如果第二个乱触发，去收窄 description 的适用范围；如果第三个答错，去检查 CLAUDE.md 是不是没放对位置。

这里有个细节要注意：Skill 一旦被调用，渲染后的 SKILL.md 会作为一条消息进入对话，并在本次会话余下时间保留。Claude Code 后续轮次不会重新读取 Skill 文件。所以 SKILL.md 里需要持续生效的规则要写成常驻指令，而不是只对第一步有效的描述。这也是为什么正文要像操作手册，不要写太多解释性散文。

验证通过之后，你还可以用 /api-design 手动触发一次，确认显式调用也正常。手动调用适合那些有明确启动动作的流程，自动调用适合参考知识。两种入口都通了，这个 Skill 才算真正可用。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

配置和验证过程中，最容易卡住的不是 Skill 写法，而是通道和鉴权报错。这一节把几个高频报错列出来，对照排查。

401 未授权。这个最常见，基本是 Key 的问题。检查三件套里的 API Key 是不是复制完整，有没有多余空格，是不是在控制台里已经启用。如果 Key 刚生成，确认一下有没有生效延迟。401 出现时，Skill 写得再好也没用，因为请求根本没到模型。

local proxy failed。这个报错通常出现在本地代理配置环节。检查你的 Base URL 是不是写成了 https://taotoken.net/api ，有没有多写或少写路径。有些工具要求 Base URL 不带尾部斜杠，有些要求带，按你用的工具文档来。另外确认本地没有其他进程占用同一个端口。

reading choices 相关报错。这个一般出现在响应解析阶段，说明请求通了但返回结构不符合预期。检查 Model ID 是不是填对了，有些模型名大小写敏感。如果用的是 Claude Code 的 Anthropic 风格接口，确认接入方式跟文档一致，参考 https://taotoken.net/doc/claudecode?utm_source=taotoken_aicg_blog_end&utm_content=ClaudeCodeAnthropic&utm_campaign=rewrite 里的说明。

OAuth 相关报错。如果你用的是需要 OAuth 流程的工具，检查授权是否完成，token 是否过期。OAuth 和 API Key 是两套机制，不要混用。如果工具同时支持两种，选一种配到底，不要一半 OAuth 一半 Key。

还有一个容易被忽略的问题：Skill 触发了但行为不对。这通常不是通道问题，而是 description 或正文写法问题。先确认通道正常（用一个简单请求测一下），再回头改 Skill。排查顺序很重要，先通道后 Skill，不然会白改很多遍。

如果三件套里任何一个缺失，报错信息可能各不相同，但根因都是配置不全。Base URL、Key、Model ID 这三样，在任何工具里都要写全。CC Switch、Cline MCP、Codex auth.json 都一样，出现其中任何一个配置场景，就按三件套补齐。

排障相关的入口我放在这里：API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。遇到报错先去这两个地方对照，大部分配置问题都能定位。

6. 把 skills 目录用对，比多写提示词重要

回到最开始的问题：skills 目录不是提示词仓库。它的价值在于把重复任务做成可调用、可组合、可携带的能力模块，让 Claude Code 在正确的时间拿到正确的资料，执行正确的流程，并且受到正确的权限约束。

CLAUDE.md 负责常驻共识，短而稳，会话开始就加载。SKILL.md 负责按需能力，入口轻、资料深、触发准。settings.json 负责权限和钩子，管执行边界。三层各司其职，混在一起就会变成噪音。

如果你现在项目里的 CLAUDE.md 已经膨胀到几百行，可以考虑把长规范迁到 skills/。超过一定长度的 API 手册、测试策略、发布流程、迁移指南，放进 skills/ 更合理。Claude Code 官方也建议保持 CLAUDE.md 简短，把参考材料移动到按需加载的 Skills。

对于长期做编码和 Agent 任务的场景，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 可以了解一下。想先验证模型效果的，模型对话在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

最后留一个实操建议：每次新增 Skill 之前，先问自己三个问题。这个任务会重复出现吗？它的边界明确吗？它值得标准化吗？三个都是是，才写 Skill。否则就留在 CLAUDE.md 或者干脆不写。Skill 不是越多越好，边界清楚才是关键。