Claude Code Skills 使用技巧：打造高效的自定义命令

1. 为什么你的 Claude Code 总在重复劳动用 Claude Code 写代码的人大概都经历过这个阶段每次让它做代码审查都要重新打一遍「请检查这段代码的风格、潜在 bug、安全问题、性能优化点」每次提交前让它生成 commit message又要把 Conventional Commits 的规则复述一遍。一天下来光是重复描述需求就消耗掉不少时间。Claude Code Skills 就是来解决这个问题的。简单说Skills 是 Claude Code 的自定义命令扩展机制它允许你把一套固定的任务流程、提示词、执行边界封装成一个文件之后只需要输入一个斜杠命令比如/review、/commitClaude Code 就会按照你预设的逻辑去执行。它适合谁适合所有日常用 Claude Code 做开发、并且发现自己反复在描述同一类需求的人——无论是个人开发者还是想把团队规范沉淀成共享指令的技术负责人。我试过在没有 Skills 的情况下靠记忆和复制粘贴来维持一套「代码审查模板」结果就是每次的检查维度都不太一样有时候漏了安全项有时候忘了看性能。后来把流程固化进 Skills才算真正稳定下来。这篇文章会从零开始带你搭出一套可复用的自定义命令工作流目录结构怎么放、命令定义模板怎么写、触发规则怎么设、在终端里怎么验证命令真的生效以及踩过的坑怎么排查。全程给可复制的配置你跟着做就能跑起来。需要先说明一点Claude Code 本身是 Anthropic 推出的命令行 AI 编程助手而 Skills 是它内置的扩展能力不需要额外装插件。你只要有一个能正常调用 Claude Code 的环境就能开始配置。如果你在接入模型服务时需要统一管理 API Key 和模型入口可以顺带了解一下 TaoToken 这类聚合接入方式后面第二节会讲怎么把它和 Claude Code 的环境变量配合起来用。2. TaoToken 前置准备让 Claude Code 稳定拿到模型能力在写 Skills 之前得先保证 Claude Code 能正常跑起来。Claude Code 默认走 Anthropic 的接口但很多开发者的实际环境里需要把请求指向一个统一的接入层方便管理 Key、切换模型、做用量统计。TaoToken 就是这样一个入口它提供兼容的 API 地址你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力API 端点则是 https://taotoken.net/api这个地址不加 UTM 参数直接用于配置。配置的核心思路是把 Claude Code 的 Base URL 指向 TaoToken 的 API 地址把 API Key 换成你在 TaoToken 控制台生成的 Key然后指定要用的 Model ID。这三件套——Base URL、Key、Model ID——是任何接入场景都绕不开的。下面给出具体的环境变量写法你可以直接复制到 shell 配置文件里。# 写入 ~/.bashrc 或 ~/.zshrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-20250514保存后执行source ~/.zshrc或对应你的 shell 文件让变量生效。这里要注意ANTHROPIC_BASE_URL后面不要带斜杠也不要拼/v1Claude Code 会自己处理路径拼接。Key 的获取路径是登录 TaoToken 后进入控制台在 API Keys 页面新建一个密钥复制出来即可。如果你还没生成 Key可以先去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 创建。Model ID 这一项建议填你实际要用的模型标识。不同模型的 ID 不一样填错了会直接报模型不存在。你可以在模型对话页面先验证一下模型是否可用地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite在里面选一个模型发一句话确认能返回结果再把对应的 Model ID 抄到环境变量里。配置完成后用一条最简单的命令验证 Claude Code 能不能通claude -p 回复 ok如果终端返回了ok或类似的正常响应说明接入层已经通了。如果报 401多半是 Key 写错或没生效如果报连接失败检查 Base URL 是否拼错。这一步过了再往下配 Skills 才有意义否则你会分不清是 Skills 配置问题还是接入问题。对于需要长期跑编码任务、或者想让多个 Agent 共享同一套模型入口的场景可以考虑用 Coding Plan 来统一管理额度与调用入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。它的好处是你不用在每个项目里单独配 Key团队协作时也更容易对齐。3. 可复制配置Skills 目录结构与命令定义模板这一节是全文的核心直接给你能落地的目录结构和文件模板。Claude Code 的 Skills 默认放在项目根目录下的.claude/skills/里每个技能一个子目录子目录里放一个skill.md作为主定义文件。整体结构长这样项目根目录/ └── .claude/ └── skills/ ├── review/ │ └── skill.md ├── commit/ │ └── skill.md └── docgen/ └── skill.md每个skill.md用 Markdown 写但它的内容会被 Claude Code 当作指令解析所以结构要清晰。一个可用的模板包含四块描述、触发条件、执行步骤、注意事项。下面是一个代码审查技能的完整skill.md你可以直接复制到.claude/skills/review/skill.md# Code Review Skill ## 描述 对用户指定的代码文件或目录进行全面审查输出结构化的问题清单。 ## 触发条件 当用户输入 /review 时触发。如果用户附带路径参数则审查该路径否则审查当前工作目录下的变更文件。 ## 执行步骤 1. 读取用户指定的文件若未指定则用 git diff 获取本次变更文件列表 2. 按以下维度逐项检查 - 代码风格与命名规范 - 潜在 bug 与边界条件 - 安全问题注入、越权、敏感信息硬编码 - 性能优化点 - 可维护性与重复代码 3. 每个问题给出文件路径、行号、问题描述、修改建议 4. 最后输出一个按严重程度排序的汇总表 ## 注意事项 - 只读取和分析不直接修改文件 - 如果文件不存在提示用户并终止 - 不要对未变更的代码提出重构建议这里有几个关键点。第一## 触发条件里的/review就是你在终端里要输入的命令名它和目录名review保持一致最不容易乱。第二## 执行步骤要写得像给一个新同事的交代越具体越稳定Claude Code 会按这个顺序执行。第三## 注意事项是执行边界明确告诉它什么不该做能大幅减少误操作。再给一个 Git 提交助手的模板放到.claude/skills/commit/skill.md# Commit Skill ## 描述 分析当前暂存区的代码变更生成符合 Conventional Commits 规范的提交信息。 ## 触发条件 当用户输入 /commit 时触发。 ## 执行步骤 1. 执行 git diff --staged 获取暂存区变更 2. 判断变更类型feat / fix / docs / style / refactor / test / chore 3. 提取变更的核心内容生成一行不超过 72 字符的标题 4. 如有必要补充正文说明变更原因和影响范围 5. 输出完整的 commit message等待用户确认后再执行 git commit ## 注意事项 - 暂存区为空时提示用户先 git add - 不要自动执行 git commit必须等用户确认 - 不要修改任何代码文件如果你用的是支持 JSON 配置的工具链比如某些编辑器插件或 MCP 客户端Skills 的元信息也可以用 JSON 表达。下面是一个settings.json片段示例用于声明技能目录和默认模型{ skills: { directory: .claude/skills, autoLoad: true }, model: claude-sonnet-4-20250514, baseUrl: https://taotoken.net/api }注意baseUrl和model这两项要和你在第二节里配的环境变量保持一致否则会出现「Skills 加载了但调用失败」的情况。路径.claude/skills是相对项目根目录的如果你在子目录里启动 Claude Code它可能找不到技能所以建议始终在项目根目录启动。模板里的变量占位符也值得说一下。你可以在skill.md里用{{args}}接收用户输入的参数用{{cwd}}表示当前工作目录。比如在review/skill.md里写「审查路径{{args}}」用户输入/review src/utils时{{args}}就会被替换成src/utils。这个机制让同一个技能能处理不同目标不用为每个目录单独建技能。4. 验证请求在终端里确认命令真的生效配置写完不代表生效必须实际跑一遍。验证分三步确认技能被加载、确认命令能触发、确认执行结果符合预期。第一步进入项目根目录启动 Claude Codecd /path/to/your/project claude启动后先输入一个斜杠看看命令列表里有没有你新建的技能。不同版本的 Claude Code 展示方式略有差异有的会在你输入/时弹出补全列表你能看到review、commit、docgen这些名字。如果列表里没有说明技能没被加载先检查目录名和文件位置。第二步直接触发命令。假设你要审查src/utils/format.js输入/review src/utils/format.js正常情况下Claude Code 会读取这个文件然后按skill.md里定义的维度输出问题清单。你会看到类似这样的返回结构## 审查结果src/utils/format.js ### 严重 - 第 23 行字符串拼接未做转义存在注入风险 建议使用参数化方式或对输入做校验 ### 一般 - 第 45 行函数超过 80 行建议拆分 建议按职责拆成 formatDate 和 formatNumber ### 汇总 | 严重程度 | 数量 | |---------|------| | 严重 | 1 | | 一般 | 1 |如果返回的是这种结构化内容说明技能生效了。如果它只是泛泛地回了几句「这段代码看起来不错」那多半是skill.md里的执行步骤写得太模糊Claude Code 没有按你的意图走。第三步验证带参数的场景。输入/review不带路径看它是否按skill.md里写的「用 git diff 获取变更文件」来执行。你可以先改一个文件但不提交然后触发命令观察它是否只审查了变更部分。这一步能验证{{args}}和默认逻辑是否都正常。对于 commit 技能验证方式类似。先git add一个文件然后输入/commit看它生成的 message 是否符合 Conventional Commits 格式比如feat: 新增日期格式化工具函数。注意它应该停下来等你确认而不是直接提交——如果它自动提交了说明## 注意事项里的约束没起作用需要把「不要自动执行 git commit」写得更靠前、更明确。验证过程中建议开两个终端一个跑 Claude Code一个用来改文件、看 git 状态。这样你能实时对照它的行为和你预期的差异。如果某个技能反复不按预期走最有效的办法是把skill.md里的执行步骤拆得更细每一步都写成可观察的动作比如「先执行 git diff --staged」而不是「分析变更」。5. 常见报错排查401、local proxy failed 与 OAuth 问题配 Skills 的过程中报错基本集中在接入层和加载层。下面按真实遇到的错误逐条排查。401 Unauthorized。这是最常见的通常出现在你触发技能后 Claude Code 去调用模型时。原因有三个Key 没配、Key 配错、Key 没生效。先确认环境变量echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL如果输出为空说明变量没写进当前 shell检查你改的是不是当前 shell 对应的配置文件bash 是~/.bashrczsh 是~/.zshrc。如果变量有值但还是 401去 TaoToken 控制台确认这个 Key 是否被禁用或额度耗尽。还有一种情况是 Key 复制时带了空格或换行重新复制一次。local proxy failed。这个报错说明 Claude Code 尝试走本地代理但没连上。检查你的环境里有没有设置HTTP_PROXY或HTTPS_PROXY变量如果有先临时取消unset HTTP_PROXY unset HTTPS_PROXY然后重启 Claude Code 再试。如果你确实需要通过统一入口访问确保ANTHROPIC_BASE_URL指向的是https://taotoken.net/api而不是本地地址。reading choices 相关报错。这类错误通常出现在返回体解析阶段提示读取choices字段失败。原因是接口返回的格式和 Claude Code 预期的格式不一致。排查方向确认 Base URL 没有多拼/v1或/chat/completionsClaude Code 会自己补路径确认 Model ID 填的是真实存在的模型填错模型时有些接入层会返回错误结构导致解析失败。你可以先用模型对话页面发一条消息确认模型可用再把同样的 Model ID 填进环境变量。OAuth 相关报错。如果你之前用账号登录方式配置过 Claude Code可能会残留 OAuth 凭证和现在的 API Key 方式冲突。解决办法是清理旧的凭证缓存通常在~/.claude/或~/.config/claude/下找到凭证文件后移除然后重新用 API Key 方式启动。清理前建议备份避免误删配置。技能不加载。命令列表里看不到你的技能先确认三点目录是不是.claude/skills/子目录名和命令名是否一致skill.md文件名是否拼对不是skills.md也不是SKILL.md大小写敏感的环境下要完全匹配。另外如果你在子目录启动 Claude Code它可能只扫描当前目录下的.claude所以务必在项目根目录启动。技能加载了但行为不对。这不算报错但很常见。表现是你输入/review它却去做了别的事。根因是skill.md里的触发条件和执行步骤有歧义。把触发条件写成明确的「当用户输入 /review 时触发」把执行步骤写成有序列表每一步都是具体动作能解决大部分问题。排查时有个通用技巧先用最简单的技能验证链路。建一个.claude/skills/ping/skill.md内容只有「当用户输入 /ping 时回复 pong」。如果这个能跑通说明接入和加载都没问题再去排查复杂技能的逻辑。如果这个都跑不通问题一定在接入层回到第二节检查三件套。6. 把重复任务沉淀成团队共享指令Skills 真正的价值不在于省几次打字而在于把「怎么做代码审查」「怎么写提交信息」这类隐性规范变成显性文件。当这些文件进了 Git 仓库团队里每个人拉下来就有一套统一的指令新人不用问「我们 commit 格式是什么」直接/commit就行。落地时有几个实用建议。第一技能要小而专一个技能只做一件事review就只管审查不要让它顺便改代码。第二skill.md里多写使用示例比如在描述里加一句「用法/review src/main.js」用户一看就懂。第三定期根据实际使用反馈迭代发现某个检查维度总是漏就把它写进执行步骤里。如果你想让多个项目共享同一套技能可以把.claude/skills/做成一个独立的 Git 仓库然后在各项目里用软链接或子模块引入。这样改一次所有项目同步更新。对于需要跨团队协作、统一模型调用入口的场景可以结合 Coding Plan 来管理调用额度避免每个人各自配 Key 导致混乱。最后留一个可以直接开始的清单在项目根目录建.claude/skills/review/skill.md把第三节的模板复制进去启动 Claude Code输入/review加一个文件路径看它是否按你定义的维度输出。跑通这一个剩下的commit、docgen就是复制结构、改内容的事。遇到报错就回到第五节对照排查链路问题优先查三件套逻辑问题优先改skill.md的执行步骤。