1. 为什么你的 Claude Code 越用越像“复读机”Skills 到底解决什么问题如果你用 Claude Code 超过两周大概率会遇到一个尴尬场景每次开新会话都要把同一套要求重新说一遍。比如“改代码前先列影响面”“提交信息用中文、动词开头”“写 React 组件优先用函数式 hooks”“生成文档时别用‘值得注意的是’”。说一次两次还行说二十次就是纯体力活。Claude Code Skills 就是冲着这个痛点来的。你可以把它理解成给 Claude Code 装“技能包”把一段稳定的工作流、一套规范、一批脚本写成一个带元信息的 Markdown 文件放进约定目录之后 Claude 会在合适的时候自动加载并触发它。它和普通提示词的区别在于——提示词是“你这次说的话”Skill 是“沉淀下来的能力”可复用、可版本管理、可分享。它适合谁三类人最明显一是天天用 Claude Code 写业务代码、反复交代同一套规范的开发者二是做内容、需要固定文风或检查清单的创作者三是想把团队内部流程比如代码审查、发布检查固化成工具的技术负责人。这篇就聚焦一件事怎么挑选与组织 Skills把重复提示词沉淀成可复用技能包并给出目录结构、命名规范、一份可直接复制的 SKILL.md 模板以及在 Claude Code 里加载、触发、验证技能生效的完整命令。先把结论放前面Skills 的核心不是“多”而是“边界清晰”。一个 Skill 只干一件事触发条件写得越具体Claude 越不容易乱用。下面从目录结构讲起。1.1 Skills 的目录结构与命名规范Claude Code 识别 Skill 靠的是文件系统约定。一个 Skill 就是一个目录目录里必须有一个SKILL.md其余文件脚本、模板、参考文档按需放。典型结构长这样.claude/ └── skills/ ├── code-review/ │ ├── SKILL.md │ └── checklist.md ├── commit-message/ │ └── SKILL.md └── doc-polish/ ├── SKILL.md └── rules/ └── ai-tone-rules.md项目级放在仓库的.claude/skills/跟着 Git 走团队共享个人级放在用户目录下的~/.claude/skills/只对自己生效。两者同名时项目级优先。命名规范我踩过的坑是别用中文目录名别用空格。用短横线连接的小写英文动词或动宾结构最好比如code-review、commit-message、api-mock。名字要能一眼看出“这个技能干什么”而不是my-skill-1这种。因为 Claude 在判断是否触发时会参考目录名和SKILL.md里的name、description字段名字含糊会直接拉低触发准确率。1.2 SKILL.md 的字段含义SKILL.md顶部是 YAML frontmatter至少包含name和description。description是触发判断的关键要写清楚“什么时候用”而不是“这是什么”。对比一下# 差的写法 description: 一个代码审查技能 # 好的写法 description: 当用户要求审查代码、检查 PR、或提交前做质量把关时使用。覆盖命名、边界条件、错误处理、测试覆盖四个维度。后者把触发场景写进去了Claude 匹配时命中率明显更高。正文部分就是具体的指令、步骤、检查清单可以引用同目录下的其他文件。2. 前置准备TaoToken 接入 Claude Code 的配置Skills 要跑起来前提是 Claude Code 能正常调用模型。如果你还没配好接入层先把这一步做掉。我用 TaoToken 做统一入口好处是 Base URL 和 Key 集中管理换模型不用改一堆地方。先拿 Key打开https://taotoken.net/api-keys登录后创建一个 API Key复制保存。注意 Key 只在创建时完整显示一次。然后配置 Claude Code 的环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量。在 macOS/Linux 下可以写进~/.zshrc或~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的KeyWindows PowerShell 用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的Key如果你用的是 Claude Code 的 settings 文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key } }这里有个细节Base URL 结尾不要多加/v1Claude Code 会自己拼路径多写反而容易 404。配完执行source ~/.zshrc让变量生效再用echo $ANTHROPIC_BASE_URL确认输出正确。模型 ID 方面Claude Code 默认会请求 Anthropic 系列模型名TaoToken 侧做了兼容映射你不需要额外指定。如果要在配置里显式写模型用claude-sonnet-4-5这类标准 ID 即可。三件套记牢Base URL、Key、Model ID缺一个都跑不通。3. 可复制的 SKILL.md 模板与配置片段这一节给一份能直接抄的模板。假设我们要做一个“提交信息规范化”技能目录是.claude/skills/commit-message/。先建目录mkdir -p .claude/skills/commit-message然后创建.claude/skills/commit-message/SKILL.md内容如下--- name: commit-message description: 当用户要求生成提交信息、写 commit message、或执行 git commit 前需要规范文案时使用。输出中文、动词开头、单行不超过 72 字符。 --- # 提交信息规范化 ## 何时触发 - 用户说“帮我写 commit”“生成提交信息”“提交前检查文案” - 用户执行 git commit 且未提供 message ## 输出规则 1. 语言用中文动词开头例如“修复”“新增”“重构”“补充”。 2. 首行不超过 72 个字符不加句号。 3. 如有必要空一行后写正文说明改动原因而非罗列文件。 4. 禁止出现“本次提交”“如下所示”这类填充词。 ## 示例 输入改了登录接口的空指针问题 输出 修复登录接口在 token 为空时的空指针异常 ## 检查清单 - [ ] 是否动词开头 - [ ] 是否超过 72 字符 - [ ] 是否说明了“为什么”而非“改了什么文件”如果你用 TOML 管理配置部分工具链场景可以这样写[skills.commit-message] path .claude/skills/commit-message enabled true trigger [commit, 提交信息]description里的触发词要和实际使用习惯对齐。你平时说“写 commit”还是“生成提交信息”就写哪个别只写书面语。4. 加载、触发与验证技能生效文件放好后Claude Code 不会自动热加载需要重启会话或执行重新加载。启动 Claude Code 后用斜杠命令查看已识别的技能/skills正常会列出commit-message及其描述。如果没出现先检查三件事目录层级对不对必须是.claude/skills/name/SKILL.md、frontmatter 的---有没有闭合、name字段是否和目录名一致。触发验证在会话里输入“帮我写个 commit我改了支付回调的重试逻辑”。如果技能生效Claude 会按模板输出类似“修复支付回调在超时场景下的重试逻辑”而不是随便给一句英文。你可以故意让它违反规则比如要求“写长一点”看它是否仍守住 72 字符约束——守住了说明指令被真正加载。再验证一次模型链路是否通curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-5,max_tokens:64,messages:[{role:user,content:回复 ok}]}返回里有content字段且文本正常说明接入层没问题。如果这里就报错Skills 再对也用不了先修接入。5. 常见报错排查401、local proxy failed、reading choices、OAuth401 Unauthorized九成是 Key 错了或没生效。先echo $ANTHROPIC_API_KEY看有没有值再确认 Key 没被复制时带上空格。如果用的是 settings.json检查 JSON 有没有语法错误逗号多一个都会导致整段失效。local proxy failed / connection refused通常是 Base URL 写错比如结尾多了/v1或少了https://。改成https://taotoken.net/api再试。另外检查本机网络是否能正常访问该域名公司网络限制出口的情况也会报这个。reading choices 相关报错这类多半出现在响应结构不符合预期时常见原因是模型 ID 写错请求打到了不存在的模型。确认 Model ID 用标准写法别自己拼。OAuth 报错Claude Code 某些版本会尝试走 OAuth 登录流程如果你用的是 API Key 模式确保没有残留的登录态干扰。清掉旧的凭据缓存重新用环境变量方式启动。排查顺序建议固定先 curl 测通模型 → 再看/skills是否识别 → 最后测触发。这样能把“接入问题”和“技能问题”分开不至于混在一起瞎改。6. 把技能包用起来从单点到组合单看一个commit-message技能好像没什么但当你把code-review、doc-polish、api-mock都按同一套结构沉淀下来Claude Code 的工作方式会明显变化它不再每次从零理解你的偏好而是带着一套稳定的“操作手册”进场。组织上建议按“一件事一个技能”切分宁可多几个小技能也不要一个大而全的everything。触发描述写具体场景正文写可执行步骤和检查清单。团队协作时把.claude/skills/提交进仓库新人拉下来就自带规范。如果你还在挑模型或想先验证效果可以直接在模型对话里试触发逻辑长期做编码和 Agent 任务的话用 Coding Plan 更划算。接入文档里有完整的 Base URL、Key、Model ID 说明照着配一遍就能跑。技能包这东西写第一个最费劲后面就是复制粘贴改字段的事了。