1. 先搞清楚CLAUDE.md 和 Skills 到底在解决什么问题如果你正在用 Claude Code 或者类似的 AI 编码工具搭工作流大概率会遇到一个很具体的困惑项目里那些必须遵守的规则和某类任务才用得上的流程到底该写在哪写进 CLAUDE.md 吧文件越堆越长每次对话都占着上下文写成 Skill 吧又怕关键约束在没触发的时候直接丢了。这个问题的本质是上下文注入策略和能力复用粒度两件事被混在了一起。CLAUDE.md 解决的是这个项目里永远成立的事实和红线Skills 解决的是遇到某类任务时按什么流程做。前者是常驻的、无条件的、项目级的后者是按需的、匹配触发的、可跨项目复用的。把这两者分清楚你的 AI 编码工作流会干净很多token 消耗也会明显下降。这篇内容面向正在搭建 AI 编码工作流的开发者我会先用一张对照表把职责边界钉死然后给出可复制的settings.json与config.toml配置骨架说明如何通过统一的 Key/API 通道接入最后用一次实际调用验证配置是否生效。全程小白友好命令和参数都能直接抄。先给一句话版本方便你记住CLAUDE.md 是贴在 Agent 桌子上的便签——在这个项目里永远记住这些事Skills 是放在 Agent 书架上的操作手册——遇到这类任务时按这个流程做。便签一直在视线里手册要用的时候才翻。这个类比后面会反复用到。2. 一张表彻底分清 CLAUDE.md 与 Skills下面这张表是全文的核心建议直接收藏。它从八个维度把两者的差异拆开每一行都对应一个实际决策点。维度CLAUDE.mdSkills本质项目级持久约束场景化能力模块作用范围该项目内所有会话全程生效只在匹配到的特定任务时加载内容类型项目事实、规范、禁止事项特定领域的流程、最佳实践、工具组合加载时机每次启动 Agent 时默认注入任务匹配时动态加载加载方式自动无条件自动匹配或手动调用是否占用上下文是始终占用是但只在加载时占用可插拔否一个项目一个文件是可以有多个随时启用/禁用谁维护你手动编写你可以写也可以用社区现成的典型内容用 pnpmNode ≥ 18别碰数据库 schemaTypeScript 迁移流程React 组件生成规范用代码来类比会更直观。CLAUDE.md 相当于全局常量整个项目到处都能引用Skills 相当于按需 import 的模块用到的时候才加载进内存。// CLAUDE.md 全局常量整个项目到处都能用 const PROJECT_RULES { packageManager: pnpm, nodeVersion: 18, forbiddenPaths: [/packages/database/schema], }; // Skills 按需引入的模块用到的时候才 import import { typeScriptMigrationGuide } from ./skills/ts-migration; import { reactBestPractices } from ./skills/react-patterns;这个类比能解释一个常见现象为什么你把所有规则都塞进 CLAUDE.md 之后Agent 反而变笨了。因为全局常量太多留给推理的工作内存就被挤占了。而 Skills 的按需加载本质上是在做上下文预算管理。2.1 实际运行时两者怎么配合光看表还不够得看一次真实的任务流。假设你的项目配置如下。CLAUDE.md 内容- 使用 pnpm不要用 npm - Node 版本 ≥ 18 - 所有 API 路径以 /api/v1 开头 - 不要在周五部署Skills 列表nextjs-patternsNext.js 最佳实践api-error-handling统一错误处理规范weekly-report周报生成器当你执行给项目加统一错误处理时运行时的加载顺序是这样的Agent 启动 ├── 自动读取 CLAUDE.md → pnpm、Node ≥ 18、API 路径规则 永驻上下文 └── 建立 Skill 索引 你下指令给所有 API 加统一错误处理 ├── Agent 匹配 Skill → 命中 api-error-handling → 加载到上下文 ├── Agent 规划任务受 CLAUDE.md Skill 双重约束 │ ├── CLAUDE.md 约束API 路径保持 /api/v1 开头 │ └── Skill 约束错误格式遵循 RFC 7807 └── 开始执行注意这里的关键点CLAUDE.md 的约束是全程在线的Skill 的约束是命中才在线的。如果这次任务没命中api-error-handling那么 RFC 7807 这条规则就不会出现但/api/v1这条永远在。这就是为什么通用硬约束必须写在 CLAUDE.md——Skill 不匹配就不会加载重要约束会直接丢失。2.2 一个直观判断法每次纠结写哪边的时候问自己一个问题这个规则是每次任务都要遵守的还是某类任务才需要遵守的每次都要遵守的写 CLAUDE.md某类任务才需要的写成 Skill。这个判断法能覆盖九成以上的场景。3. TaoToken 前置统一 Key/API 通道怎么接在给出配置骨架之前得先把接入通道说清楚。不管你是用 Claude Code、还是自己写的 Agent 脚本模型调用都需要一个稳定的 API 入口。TaoToken 提供的就是这样一个统一通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。为什么要在讲 CLAUDE.md 和 Skills 之前先讲接入因为配置骨架里的settings.json和config.toml本质上都要指向一个 API 地址和一把 Key。如果通道不统一你在多个项目、多个工具之间切换时Key 管理会变成一团乱麻。统一通道之后CLAUDE.md 里可以写本项目统一走这个 API 入口Skills 里可以写调用模型时用这套参数两边引用同一个来源不会打架。你需要先拿到一把 API Key。进入控制台创建即可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 。生成后先复制保存页面刷新后就不再完整显示。如果你更习惯先看看模型对话效果再决定怎么配可以直接在模型对话页面试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。想先读文档再动手的接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意Key 只放在本地环境变量或本地配置文件里不要提交到 Git 仓库。下面所有配置示例里的sk-xxxx都请替换成你自己的真实 Key。4. 可复制配置settings.json 与 config.toml 骨架这一节是全文最实操的部分。我会给出两套配置骨架一套是 Claude Code 风格的settings.json一套是通用 Agent 的config.toml。你可以按自己用的工具选一套或者两套都留着。4.1 settings.json 配置骨架Claude Code 的配置通常放在项目根目录的.claude/settings.json或者用户级的~/.claude/settings.json。下面这份骨架把 API 通道、环境变量、权限边界都写清楚了。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-xxxx, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Glob, Grep, Edit, Bash(pnpm *), Bash(git status), Bash(git diff *) ], deny: [ Bash(rm -rf *), Bash(git push --force *), Read(./.env), Read(./secrets/**) ] }, includeCoAuthoredBy: false }几个参数说明一下。ANTHROPIC_BASE_URL指向统一 API 入口注意这里用的是https://taotoken.net/api不带任何查询参数。ANTHROPIC_AUTH_TOKEN填你的 Key。permissions.deny里把.env和secrets目录挡掉这是防止 Agent 误读敏感文件的底线建议每个项目都加上。如果你用的是 Claude Code 的 coding plan 模式配置入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。长期做编码和 Agent 任务的走这个通道会更省心。4.2 config.toml 配置骨架如果你用的是通用 Agent 框架或者自己写的脚本config.toml会更合适。下面这份骨架把模型参数、上下文策略、Skill 目录都列出来了。[api] base_url https://taotoken.net/api api_key sk-xxxx timeout_seconds 120 max_retries 3 [model] name claude-sonnet-4-20250514 max_tokens 8192 temperature 0.2 [context] # CLAUDE.md 常驻注入路径相对于项目根目录 project_rules_file ./CLAUDE.md # Skills 按需加载目录下每个子目录是一个 Skill skills_dir ./skills skill_auto_match true max_loaded_skills 3 [logging] level info log_dir ./logs这里有两个参数值得单独说。max_loaded_skills 3是防止一次任务命中太多 Skill 把上下文撑爆实测下来 3 个是比较稳的上限。temperature 0.2是编码场景的常用值太低会死板太高会乱改代码。4.3 CLAUDE.md 与 Skill 的目录结构配置写好了目录结构也得对。推荐这样组织my-project/ ├── CLAUDE.md ├── .claude/ │ └── settings.json ├── config.toml ├── skills/ │ ├── api-error-handling/ │ │ └── SKILL.md │ ├── nextjs-patterns/ │ │ └── SKILL.md │ └── weekly-report/ │ └── SKILL.md └── src/CLAUDE.md 放在项目根目录Skills 放在skills/下每个 Skill 一个子目录里面放SKILL.md。这样config.toml里的skills_dir指向./skills就能自动扫描到。4.4 什么时候写 CLAUDE.md什么时候写 Skill把判断标准再具体化一下。写在 CLAUDE.md 的项目永远不变的事实技术栈、版本要求、包管理器每次都想让 Agent 知道的约束命名规范、禁止操作、API 路径前缀简短、普适、高频的规则写成 Skill 的特定场景才需要的专业知识某框架的最佳实践有固定流程的多步骤任务周报生成、代码审查、迁移流程你希望在多个项目间复用的能力内容较长、只在特定时候需要的5. 验证请求一次实际调用确认配置生效配置写完不能只看得跑一次确认。下面用一个最小请求验证 API 通道是否通再验证 CLAUDE.md 和 Skill 是否被正确加载。5.1 先验证 API 通道用 curl 直接打一次 API确认 Key 和地址没问题。curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-xxxx \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [ {role: user, content: 只回复两个字通了} ] }如果返回的 JSON 里content字段包含通了说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查base_url是否写成了https://taotoken.net/api而不是别的路径。5.2 再验证 CLAUDE.md 是否被注入在项目根目录启动 Agent然后问一个只有 CLAUDE.md 里才有答案的问题。比如你的 CLAUDE.md 里写了使用 pnpm那就问这个项目用什么包管理器如果 Agent 回答pnpm说明 CLAUDE.md 被正确注入了。如果它反问你想用哪个说明注入没生效检查project_rules_file路径是否正确。5.3 最后验证 Skill 是否按需加载给一个能命中 Skill 的指令比如给所有 API 加统一错误处理。观察 Agent 的行为如果它开始引用 RFC 7807 或者你 Skill 里定义的错误格式说明api-error-handling这个 Skill 被匹配并加载了。你也可以在config.toml里把logging.level调成debug日志里会打印每次加载了哪些 Skill方便排查。[debug] loaded skills: api-error-handling [debug] context tokens: 12480 / 200000看到这行日志就说明整套配置跑通了。6. 本篇常见错排查配置过程中最容易踩的坑我整理成了一张排查表。遇到问题先对照这里能省不少时间。现象可能原因排查动作401 UnauthorizedKey 错误或未生效重新生成 Key确认无多余空格404 Not Foundbase_url 路径写错确认是https://taotoken.net/apiAgent 不遵守 CLAUDE.md文件路径不对或未注入检查project_rules_file路径Skill 一直不加载目录结构或匹配规则问题确认skills_dir和SKILL.md存在上下文爆掉CLAUDE.md 太长或 Skill 加载过多精简 CLAUDE.md调低max_loaded_skillsSkill 和 CLAUDE.md 冲突两边写了重复或矛盾内容通用约束留 CLAUDE.md细节移入 Skill6.1 误区一把所有规则都塞进 CLAUDE.md结果就是上下文被大量规则占满留给推理的空间变少Agent 反而变笨。正确做法是 CLAUDE.md 只放高频约束低频的放 Skills。6.2 误区二Skills 和 CLAUDE.md 写重复内容两边写一样的东西不仅浪费上下文冲突时 Agent 还可能混乱。正确做法是 CLAUDE.md 写通用约束Skills 写领域细节互不重叠。6.3 误区三以为 Skill 能覆盖 CLAUDE.mdSkill 不匹配就不会加载重要约束会直接丢失。通用硬约束必须写在 CLAUDE.md这条没有例外。6.4 误区四Key 硬编码进配置文件后提交了这是最危险的一个。Key 一旦进了 Git 历史就算后面删掉也还在。建议用环境变量引用{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: ${TAOTOKEN_API_KEY} } }然后在 shell 里export TAOTOKEN_API_KEYsk-xxxx配置文件本身不含明文 Key可以放心提交。7. 继续往下走按你的场景选入口配置跑通之后接下来怎么走取决于你的使用场景。我把几个入口按场景分一下你对号入座就行。如果你主要在做排障和接入比如 Key 报错、通道不通、配置不生效优先看 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 。文档里有完整的错误码对照。如果你主要想验证模型效果比如对比不同模型在编码任务上的表现直接去模型对话页面试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 。它的定位就是给高频编码场景用的。最后回到 CLAUDE.md 和 Skills 的关系上。我自己的习惯是CLAUDE.md 控制在 50 行以内只写那些如果 Agent 不知道就会犯错的硬约束Skills 按领域拆每个 Skill 只解决一类任务能跨项目复用就复用。这样一套下来上下文干净Agent 的行为也可预测。你可以先从精简 CLAUDE.md 开始把低频规则挪进 Skills跑一周看看 token 消耗和输出质量的变化。
