Claude Code 里怎么用 Skill？从 SKILL.md 到自定义命令的配置骨架-平芜编程栈

1. 为什么你的 Claude Code 总在重复同一套指令

如果你已经在本地项目里用 Claude Code 写代码，大概率遇到过这种场景：每次提交前都要重新打一遍“先看 git diff，再总结改动，最后按 Conventional Commits 生成提交信息”。一次两次还好，一天来回十几次，手指和耐心都受不了。

Claude Code 的 Skill 机制就是来解决这个问题的。简单说，Skill 是一个放在指定目录里的SKILL.md文件，里面写清楚“什么情况下触发、按什么步骤执行、输出成什么格式”。Claude Code 启动会话时先读 Skill 的描述信息，当你的请求和描述匹配上，它才会把完整内容加载进上下文，然后照着流程走。

这套机制特别适合三类人：一是每天要重复固定工作流的开发者，比如代码审查、提交信息生成、部署前检查；二是团队里需要统一规范的场景，比如接口约定、测试要求、代码风格；三是想把长提示词沉淀下来、不想每次复制粘贴的人。

我试过把 commit message 生成做成 Skill 之后，最直观的变化是：以前要打三行字，现在一句“帮我总结这次改动”就够了，而且输出结构每次都一致，直接复制到 PR 里就能用。下面从目录结构开始，一步步把 Skill 跑通，再讲怎么通过 TaoToken 统一 Key 和 API 通道接进来。

2. TaoToken 前置：把 Key 和 API 通道先理顺

在写 Skill 之前，有个容易被忽略的前置问题：Claude Code 本身要能稳定调用模型。如果你在多个项目、多个工具之间来回切换，Key 管理会变得很乱——这个项目用这个 Key，那个脚本用那个 Key，额度分散、排查困难。

TaoToken 在这里的作用是提供一个统一的 API 通道。你可以在官网注册后拿到 Key，然后把 Claude Code 的请求指向同一个入口，不用在每个项目里单独配置不同的凭证。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。

具体操作上，先去控制台创建 API Key：

控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

拿到 Key 之后，在 Claude Code 的环境变量里配置。通常是在 shell 的配置文件里加一行，或者在项目级的.env里设置。配置完成后，Claude Code 发出的请求就会走 TaoToken 的通道，Key 只需要维护一份。

注意：Key 不要硬编码进SKILL.md或提交到 Git 仓库。Skill 文件是给模型读的操作说明，不是放凭证的地方。凭证走环境变量或本地配置文件。

如果你还没决定用哪个模型，可以先去模型对话页面试一下效果：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。确认通道通了，再往下做 Skill 配置。

3. 可复制配置：SKILL.md 骨架与目录结构

3.1 三种放置位置怎么选

Claude Code Skill 常见有三种位置，选错了会导致“明明写了却不触发”：

位置	路径	适合场景
个人级	`~/.claude/skills/<skill-name>/SKILL.md`	自己所有项目都想用的习惯
项目级	`.claude/skills/<skill-name>/SKILL.md`	当前项目或团队共享的规则
插件级	`<plugin>/skills/<skill-name>/SKILL.md`	可复用、可分发的 Skill 包

刚开始建议从个人级入手，路径固定、验证简单。等团队要一起用了，再把项目级 Skill 放进仓库的.claude/skills/目录，跟着代码做版本管理。一个实用原则是：个人习惯放个人级，项目规则放项目级，真正要分发的能力才做成插件级。

3.2 最小可用 SKILL.md

先做一个 commit-helper，作用是总结 Git 改动并生成提交信息。创建目录和文件：

mkdir -p ~/.claude/skills/commit-helper touch ~/.claude/skills/commit-helper/SKILL.md

然后写入下面这段内容：

--- name: commit-helper description: Use when the user asks to summarize git changes, review a diff, or generate a commit message. when_to_use: 当用户说“生成 commit message”“总结这次改动”“帮我看 diff”“写提交信息”时使用。 --- 你是一个 Git 提交助手。 请按以下步骤工作： 1. 先查看当前 Git 状态； 2. 阅读 git diff； 3. 用中文总结本次改动； 4. 按 Conventional Commits 格式给出 3 个提交信息候选； 5. 如果改动涉及多个主题，建议拆分提交。 输出格式： ## 改动总结 ## 风险点 ## Commit Message 候选

这里有几个关键字段要理解清楚。name最好和目录名保持一致，后续维护省事。description是最重要的部分，Claude Code 靠它判断什么时候该用这个 Skill，所以不要写得太泛，比如Help with coding这种基本等于没写。when_to_use补充触发条件，可以写用户真实会说的话。正文部分把流程、规则、输出格式、禁止事项都写清楚。

3.3 复杂 Skill 的目录组织

简单 Skill 一个SKILL.md就够了。复杂一点可以这样组织：

my-skill/ ├── SKILL.md ├── scripts/ │ └── check.py ├── references/ │ └── api-style-guide.md └── assets/ └── template.md

scripts/放可执行脚本，references/放长文档和规范，assets/放模板和静态资源。但要注意，这些目录不是魔法目录——文件放进去不代表 Claude Code 会自动知道用途。更稳妥的做法是在SKILL.md里明确写：

如需检查 API 文档格式，请参考 references/api-style-guide.md。 如需自动检查 OpenAPI 文件，请运行 scripts/check.py。 生成接口文档时，请优先使用 assets/template.md 中的模板结构。

如果脚本需要执行，记得加权限：

chmod +x scripts/check.py

3.4 把 Skill 映射成自定义命令

高频、参数固定的操作可以做成斜杠命令。比如项目级 Skill.claude/skills/deploy-staging/SKILL.md可以对应/deploy-staging命令：

--- name: deploy-staging description: Use when the user wants to deploy a service to staging. --- Deploy the $ARGUMENTS[0] service to $ARGUMENTS[1]. Before deployment: 1. Check git status. 2. Run tests. 3. Confirm environment variables. 4. Execute the deployment command. 5. Verify logs after deployment. If any step fails, stop and explain the reason before continuing.

调用时写/deploy-staging user-service staging，$ARGUMENTS[0]是第一个参数，$ARGUMENTS[1]是第二个。有些版本里也可能看到$0、$1的形式，具体以当前 Claude Code 官方文档和实际版本为准。不过没必要把所有 Skill 都做成命令，能用自然语言顺利触发的就保持自然调用，反而更轻。

3.5 settings.json 配置片段

如果你想让 Claude Code 在启动时加载特定配置，可以在项目根目录的.claude/settings.json里写：

{ "skills": { "enabled": true, "directories": [ ".claude/skills", "~/.claude/skills" ] }, "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "${TAOTOKEN_API_KEY}" } }

这里的ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口，ANTHROPIC_API_KEY从环境变量读取，避免把 Key 写死在文件里。配置完成后，Claude Code 的请求会统一走这个通道。

4. 验证请求：一次调用确认 Skill 生效

配置写完了，得验证它真的能用。进入一个 Git 项目，启动 Claude Code：

cd /path/to/your/git-project claude

然后在 Claude Code 里输入：

帮我总结这次改动，并生成 commit message

如果 Claude Code 按照“改动总结 / 风险点 / Commit Message 候选”这个结构输出，并且主动查看了 Git 状态或 diff，说明 Skill 已经生效。

如果没自动触发，可以直接点名：

请使用 commit-helper skill 帮我总结这次改动，并生成 commit message

这一步很关键，因为 Skill 的触发依赖description和when_to_use的匹配度。自动触发不稳定时，明确指定是最稳的方式。

验证通过后，你可以再试一个自定义命令。比如配置了/deploy-staging，输入：

/deploy-staging user-service staging

观察它是否按步骤检查 git status、跑测试、确认环境变量。如果中途某一步失败，它应该停下来解释原因，而不是继续往下走。

5. 本篇常见错排查：Skill 不生效怎么办

Skill 写了却不触发，通常不是玄学，按下面这个清单顺序检查一遍，基本能定位到问题。

第一，确认文件名。必须叫SKILL.md，大小写敏感，skill.md或Skill.md都可能不被识别。

第二，检查路径。个人级应该是~/.claude/skills/<skill-name>/SKILL.md，项目级应该是.claude/skills/<skill-name>/SKILL.md。路径里多一层少一层都会导致找不到。

第三，检查 YAML frontmatter 有没有闭合。开头和结尾都要有---，少一个就解析失败。这是最常见的低级错误。

第四，看description是不是太泛。只写Help with coding基本等于没写，要写清楚具体在什么场景下触发，比如Use when the user asks to review git diff。

第五，新增或修改 Skill 后，重启当前 Claude Code 会话再测试。很多时候重启一下就好了。

第六，自动触发不稳定时，直接明确告诉 Claude“请使用 xxx skill 完成这个任务”。

第七，确认脚本和参考资料是否在SKILL.md正文里被提到。只把文件放进scripts/或references/还不够，正文里要说明什么时候用它们。

第八，如果 Skill 要执行脚本，检查执行权限和运行环境，比如 Python 版本、依赖是否安装。

第九，看看是不是和其他 Skill 职责太像。多个 Skill 的description过于相似，Claude Code 会不知道该选哪个。

第十，如果用到了自定义命令、插件级 Skill，确认当前 Claude Code 版本是否支持。涉及版本差异时以官方最新文档为准。

另外，如果你在配置settings.json时遇到 API 连接问题，先确认ANTHROPIC_BASE_URL和 Key 是否正确。可以回到 TaoToken 的接入文档对照检查：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

6. 长期编码与 Agent 场景的接入建议

如果你只是偶尔用 Skill 做提交信息生成，个人级配置就够了。但如果你打算把 Claude Code 当成长期编码助手，甚至跑 Agent 类的自动化任务，那 Key 和通道的稳定性就变得很重要。

长期编码场景下，建议把 TaoToken 的 Key 统一管理，而不是每个项目单独配。这样额度、调用记录、排查都在一个地方。如果你需要跑更复杂的 Agent 工作流，可以了解一下 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它适合需要持续调用、多任务并行的场景。

对于 Claude Code 这类工具，还有一个细节值得注意：Skill 本身不是 MCP，也不会天然提供外部 API 调用能力。它告诉 Claude“应该怎么做”，但不负责“连接什么服务”。要连数据库、外部 API，那是 MCP 的活；要做事件自动化，用 Hooks；要并行处理大任务或隔离上下文，用 Subagents。这几者的分工可以简单记成：固定项目规则放CLAUDE.md，重复流程和长说明写成 Skill，连外部服务用 MCP，事件自动化用 Hooks，并行大任务用 Subagents。

最后给一个实用建议：Skill 不要贪多。一个 Skill 只解决一类问题，description写触发场景而不是宣传语，流程写清楚执行顺序，输出格式固定下来。团队共用的 Skill 放项目仓库的.claude/skills/，个人习惯放~/.claude/skills/。定期清理不用的 Skill，描述重叠太多反而会影响触发准确性。

如果你还没开始，就从那个 commit-helper 做起。它最容易验证，也最容易让你感受到 Skill 的价值——把反复告诉 Claude Code 的工作方法，沉淀成可复用、可触发、可维护的操作手册。