Claude Code 指南第 8 章进阶

自定义命令与技能把常用流程固化成一个斜杠命令

同一段话说到第三遍,就该把它变成命令。一个 Markdown 文件就是一个斜杠命令;流程更长的,做成带说明书和附件的技能。两者都放在仓库里,团队一起用。

更新于 2026年10月17日 · 依据 Claude Code 2.1.301 官方文档核对 · AGI Dawn 编辑部 · 审定 kk

全部章节
本页

先说结论

  • 发现自己反复输入同一段指令(「按我们的规范写一个 API 端点」「生成提交信息」),就把它写成一个技能,之后输入 /命令名 就够了。
  • 简单的写成一个文件 .claude/skills/<名字>/SKILL.md;流程长、要用模板或脚本的,把附件放进同一个目录。
  • 命令和技能都是仓库的一部分,和 CLAUDE.md、Hooks 一样提交、评审、迭代。

最简单的命令

在项目里建 .claude/skills/new-endpoint/SKILL.md:

markdown
---
description: 按项目规范新增一个 API 端点
---

新增一个 API 端点:$ARGUMENTS

要求:

1. 路由注册在 src/routes/ 对应模块,遵守现有命名。
2. 输入用 zod 校验,错误统一走 HttpError。
3. 补一个最小的测试用例并运行通过。
4. 完成后用一句话总结改了哪些文件。

之后在会话里输入 /new-endpoint 订单查询,GET /orders/:id,就等于把整段话连同参数发给它。

  • $ARGUMENTS 是命令后面的全部参数;$0、$1 依次取第一个、第二个参数,含空格的参数要加引号。
  • 正文里可以写 @文件路径 把文件带进来,也可以写 !`git diff --stat`,把命令输出嵌进去。
  • 早期的 .claude/commands/<名字>.md 单文件写法仍然有效,效果相同。

放在 ~/.claude/skills/ 下的是个人技能,所有项目可用;放在项目 .claude/skills/ 下的随仓库走。输入 / 会列出全部可用的命令。

起名先查重。Claude Code 自带不少命令(/code-review、/doctor、/compact 等),自定义的名字和内置的相同时,会替换掉内置命令,容易造成困惑。动手前输入 / 看一眼列表。

几个团队常写的:

  • /commit-msg:读 git diff --staged,按团队格式写提交信息并提交。
  • /team-review:对当前分支相对主分支的改动做审查,只报确定的问题。
  • /fix-issue 123:读 issue、定位、修复、补测试,最后写一句总结。
  • /changelog-draft:从上一个 tag 以来的提交生成更新日志草稿。

技能:带说明书的流程

当一件事需要多个步骤、有判断分支、要参考模板或调用脚本时,把附件放进技能目录:

.claude/skills/weekly-report/
├── SKILL.md          # 什么时候用、怎么做(必需)
├── template.md       # 输出模板
└── collect.sh        # 取数脚本

SKILL.md 开头说明用途与触发条件,正文写步骤:

markdown
---
name: weekly-report
description: 生成本周运营周报。用户提到「周报」「本周数据」时使用。
---

1. 运行 collect.sh 取本周数据(输出 JSON)。
2. 按 template.md 的结构填写,数字保留一位小数,环比写清正负。
3. 环比超过 ±30% 的指标单独列一节「需要关注」。
4. 不要编造数据;取不到的指标写「本周无数据」。

它会在任务相关时自动加载这个技能,你也可以直接输入 /weekly-report 调用。从一个文件开始,长到放不下再加附件,不必一开始就纠结形式。

写得好的命令长什么样

  • 说清验收标准,而不是操作步骤:「测试通过、lint 零错误、改动不超过三个文件」比「第一步打开某文件」有用。
  • 引用项目自己的规范:写 @docs/api-style.md,比复述一遍可靠。
  • 给一个例子:一个正确输出的样例胜过三段描述。
  • 把会变的部分留给参数,不变的部分写死。
  • 短:超过 40 行,就把细节挪进附件,正文只留步骤。

团队怎么用

把 .claude/ 目录整个提交进仓库,新人 clone 下来就有同一套命令、Hooks 和 CLAUDE.md。改命令和改代码一样走评审。慢慢地,团队的工作方式会沉淀在这个目录里,而不是留在某个人的脑子里。更多做法见 团队用法。

常见问题

命令和 CLAUDE.md 怎么分工?

CLAUDE.md 是每次都生效的背景,命令是按需触发的任务模板。规范写在前者,流程写成后者。

技能会不会被误触发?

description 写得越具体越不会,比如写明「用户提到 X 或 Y 时使用」。

一个命令能调用另一个吗?

可以在正文里写「然后按 /team-review 的标准检查一遍」,它会照做;更复杂的编排适合写进技能的步骤里。