1. 为什么你的 Claude Code 总是不按套路出牌如果你已经在用 Claude Code 写代码大概率遇到过这种场景明明在项目里约定好了「所有接口必须走统一响应包装」「提交前必须跑 lint」「新增组件必须补单测」但每次开新会话它还是按自己的习惯来你得反复在对话里提醒。提醒一次管一次换个会话又忘光。这不是模型笨而是你给它的约束是「临时的」。普通对话里的要求只存在于当前上下文会话一关就没了。CLAUDE.md 能解决一部分问题它定义的是项目级规则每次会话都会读但它更像「宪法」——写的是不能干什么、边界在哪而不是「某类任务具体分几步做」。Claude Code Skills 补的正是这块。一个 Skill 本质就是一个SKILL.md指令包告诉 Claude Code「在什么时机、用什么方法」完成一类任务。它是可复用的「岗位说明书」普通对话是临时工Skill 是签了合同的正式员工。你把它放到~/.claude/skills/或项目里的.claude/skills/命中触发条件时它自动加载也能通过 slash 命令手动调用。这篇面向想让 AI 稳定遵循团队规范的开发者从SKILL.md骨架、目录结构讲到 slash 触发和 MCP 协作给出可直接复制的模板和settings.json片段最后演示一次 slash 调用验证 AI 是否真的按规范输出。适合谁已经在用 Claude Code、想让重复性工作固化成流程的人如果你还没装先看安装那篇再回来。2. 前置准备TaoToken 接入与 Skills 目录约定在写 Skill 之前先把「模型从哪来」这件事理顺。Claude Code 需要一个可用的 API 入口我用的是 TaoToken 的接入方式官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的作用是给你一个统一的调用入口Claude Code 通过环境变量指向它即可不用改 Claude Code 本身的代码。先拿 Key。打开控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个密钥复制出来。这个 Key 只显示一次丢了就重建。拿到后配置环境变量macOS/Linux 写进~/.zshrc或~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你刚才复制的keyWindows 用 PowerShell 的话$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_AUTH_TOKEN sk-你刚才复制的key改完重开终端或者source ~/.zshrc让它生效。验证一下变量有没有进去echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN两个都有输出就对了。接着确认 Claude Code 能连上随便进一个目录跑一次简单对话能正常返回就说明链路通了。这一步别跳过后面 Skill 调试如果出问题先排除是不是 Key 或端点没配对。然后是 Skills 的目录约定。Claude Code 会从几个位置加载 Skill作用范围不同位置路径生效范围全局~/.claude/skills/名字/SKILL.md所有项目项目级项目/.claude/skills/名字/SKILL.md仅该项目插件自带~/.claude/plugins/cache/.../skills/名字/SKILL.md插件启用即加载较新版本起嵌套的.claude/skills目录会自动加载插件里的 skills 也不需要 marketplace 就能识别。我的建议是团队通用规范放项目级跟着仓库走同事 clone 下来就有个人跨项目习惯放全局。技能名统一用 kebab-case比如api-response-check、commit-lint别用中文或空格避免路径解析出问题。3. 可复制配置SKILL.md 骨架与 settings.json先看一份最小可用的SKILL.md。frontmatter 里name和description是必须的其中description是 Claude Code 判断「要不要调用这个 Skill」的唯一依据写得越准触发越稳。--- name: api-response-check description: 当用户新增或修改后端接口、提到接口规范响应格式统一返回时调用用于检查接口是否符合团队统一响应包装规范。不用于纯前端组件改动。 --- # API 响应规范检查 ## 触发时机 - 用户新增、修改任何 HTTP 接口 - 用户说检查接口规范响应格式对不对 - 代码 diff 中出现 controller / handler / route 相关文件 ## 前置判断 - 仅检查后端接口层不检查数据库迁移脚本 - 如果改动只是注释或文档跳过 ## 执行步骤 1. 定位本次改动涉及的接口文件 2. 检查返回体是否统一为 { code, message, data } 结构 3. 检查错误分支是否也走同一包装而不是直接抛裸异常 4. 检查 HTTP 状态码与业务 code 是否分离 5. 输出问题清单每条给出文件、行号、修改建议 ## 不要做的事 - 不自动改代码只输出检查结果 - 不检查与本次改动无关的历史文件 - 不臆造团队没定义的字段名正文按技能性质组织。刚性技能TDD、排障、规范检查写死步骤一步都别省柔性技能知识库检索、方案调研写原则加方法。典型结构就是上面这套触发时机 → 前置判断 → 执行步骤 → 不要做的事 → 参考。description的写法有个技巧把「触发条件」和「排除条件」都写进去。上面那句「不用于纯前端组件改动」就是排除条件能有效避免误触发。很多人只写「用于检查接口」结果改个前端组件它也跑出来上下文被污染。接着是settings.json。Claude Code 的配置分用户级和项目级项目级放项目/.claude/settings.json跟着仓库走。下面这份片段控制 Skill 的展示与启用{ skills: { api-response-check: { displayName: 接口规范检查, defaultEnabled: true }, commit-lint: { displayName: 提交信息校验, defaultEnabled: false, fallback: 提交信息不符合规范时提示用户手动修正 } } }displayName是给人看的名字defaultEnabled控制默认是否启用fallback定义异常时的兜底行为。这几个字段不是每个版本都完全一致如果你的版本不认删掉对应字段即可SKILL.md本身照样能加载。目录结构长这样项目/ ├── .claude/ │ ├── settings.json │ └── skills/ │ ├── api-response-check/ │ │ └── SKILL.md │ └── commit-lint/ │ └── SKILL.md一个技能一个目录目录名和 frontmatter 里的name保持一致省得自己绕晕。4. 验证请求用 slash 调用确认 AI 按规范输出配置写完得验证它真的生效。Claude Code 里 Skill 可以注册成 slash 命令用户显式输入/技能名就能调用。先重启一次会话让新 Skill 被加载。第一步确认 Skill 被识别。在 Claude Code 里输入/看命令列表或者直接问它「现在有哪些可用的 skill」。如果api-response-check出现在列表里说明加载成功。没出现就检查路径和文件名SKILL.md必须是大写目录层级别写错。第二步显式触发。假设你刚改了一个接口文件输入/api-response-check 检查一下刚才改的 user 接口预期结果是它按SKILL.md里的步骤走先定位文件再逐条检查返回体结构、错误分支、状态码分离最后输出一份带文件行号的问题清单而且不会自动改代码——因为「不要做的事」里写死了。第三步验证隐式触发。新开一个会话不提 skill 名字直接说「我加了个订单查询接口帮我看看响应格式对不对」。如果description写得准它应该自动调用这个 Skill。这一步是检验description质量的关键没触发说明描述太窄乱触发说明排除条件不够。第四步验证边界。故意改一个纯前端组件说「帮我看看这个组件」。按规范它不该触发接口检查。如果它还是跑了回去把排除条件写得更明确。实测下来隐式触发是最容易翻车的一环。我的经验是description里至少包含一个「动作词」新增、修改、检查和一个「对象词」接口、响应、提交信息再加一句排除。三者齐了触发准确率会高很多。5. 本篇常见错排查Skill 不加载。先看路径全局是~/.claude/skills/项目级是项目/.claude/skills/别把项目级写到用户目录去了。再看文件名必须是SKILL.md全大写。最后看 frontmatter---必须成对name和description缺一不可YAML 缩进别用 Tab。触发了但没按步骤走。大概率是正文结构太松。刚性流程一定要写成有序步骤别写成一段话。Claude Code 对「1. 2. 3.」这种结构的遵循度明显高于散文式描述。另外「不要做的事」要具体写「不要乱改」没用写「不自动改代码只输出检查结果」才有约束力。误触发太频繁。在description里补排除条件。比如「不用于纯文档改动」「不用于依赖升级」。也可以把defaultEnabled设为false改成纯手动 slash 调用等描述打磨好了再开自动。slash 命令找不到。确认会话重启过Skill 是启动时加载的。如果用了settings.json里的displayNameslash 命令名仍以name为准不是 displayName。版本差异也可能导致某些字段不生效先删掉可选字段用最小配置验证。和 MCP 配合时工具调不到。Skill 本身不提供工具能力它只是「脑」负责决定什么时候、怎么干MCP 提供「手」负责实际执行。如果 Skill 里写了「调用检索工具」但没配对应 MCP它就会卡住。先确认 MCP 已接入并能单独调用再在 Skill 正文里引用。两者配合才是扩展的精髓MCP 给能力Skill 给流程。改了 SKILL.md 不生效。同样要重启会话。热更新不是所有版本都支持稳妥做法就是改完重开。6. 把规范固化下来从第一个 Skill 开始Skill 的价值不在于它多复杂而在于它把「你对 Claude Code 的要求」变成了「Claude Code 自己的行为准则」。门槛低到一个 markdown 文件收益是一次配置长期复用还能跟着仓库分享给同事。如果你想让团队规范真正落地建议从最常重复的一件事开始提交信息校验、接口规范检查、单测覆盖提醒挑一个写成 Skill。写完用 slash 显式调一次再用隐式触发验一次确认稳定后再开defaultEnabled。需要长期跑编码任务、或者想让 Agent 按固定流程干活的可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。想先验证模型输出是否符合预期直接去模型对话页试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。接入过程中遇到 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 。下一个扩展点是 MCP它负责把外部工具接进来——知识库、数据库、浏览器、编辑器。Skill 定流程MCP 给能力两个配起来Claude Code 才真正变成懂你团队的那一个。