自定义命令与技能把常用流程固化成一个斜杠命令
同一段话说到第三遍,就该把它变成命令。一个 Markdown 文件就是一个斜杠命令;流程更长的,做成带说明书和附件的技能。两者都放在仓库里,团队一起用。
全部章节
本页
先说结论
- 发现自己反复输入同一段指令(「按我们的规范写一个 API 端点」「生成提交信息」),就把它写成一个技能,之后输入
/命令名就够了。 - 简单的写成一个文件
.claude/skills/<名字>/SKILL.md;流程长、要用模板或脚本的,把附件放进同一个目录。 - 命令和技能都是仓库的一部分,和
CLAUDE.md、Hooks 一样提交、评审、迭代。
最简单的命令
在项目里建 .claude/skills/new-endpoint/SKILL.md:
---
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 开头说明用途与触发条件,正文写步骤:
---
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 的标准检查一遍」,它会照做;更复杂的编排适合写进技能的步骤里。