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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 进去之后创建 API Key复制出来先存好。如果你还没决定用哪个模型可以先到模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 试一下确认模型能正常响应再回到 Claude Code 里配。这里有个顺序建议先把模型通道验证通再去写 skills。因为 Skill 的触发依赖模型对 description 的理解如果通道本身不稳你会把通道问题误判成 Skill 写法问题排查方向就歪了。我试过先写一堆 Skill 再配通道结果触发一直不灵最后发现是 Key 没生效白白改了半天 description。对于长期要做编码和 Agent 任务的场景可以考虑 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的开发工作流。如果你只是想先验证 skills 分工用按量的 Key 就够了。配置文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Claude Code 相关的接入说明可以参考 https://taotoken.net/doc/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 里面有针对 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 负责约束和导航不负责堆资料。现在把两份配置放在一起对比边界就很清楚了。维度CLAUDE.mdSKILL.md加载时机会话开始完整加载默认只加载 description内容类型常驻共识、短规则按需知识、工作流长度控制越短越好入口短资料放支持文件触发方式始终生效手动 /name 或自动匹配典型内容启动命令、模块边界接口规范、发布流程还有一个关键字段要讲清楚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 KeyModel 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_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 里的说明。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_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。遇到报错先去这两个地方对照大部分配置问题都能定位。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_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 可以了解一下。想先验证模型效果的模型对话在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。最后留一个实操建议每次新增 Skill 之前先问自己三个问题。这个任务会重复出现吗它的边界明确吗它值得标准化吗三个都是是才写 Skill。否则就留在 CLAUDE.md 或者干脆不写。Skill 不是越多越好边界清楚才是关键。