把常用流程做成 Claude Code 斜杠命令

每次提交代码之前，你都要让 Claude Code 做同样三件事：看一遍暂存区的改动，整理验证情况和潜在风险，再写一段提交说明。每次都得把要求重新打一遍，偶尔还会漏掉一条。把这套流程做成一个 /prepare-commit，下次输入一行就能开始。

做成斜杠命令本身不难，难的是把它的边界写清楚。一个随手写的命令很容易出这些问题：

没有暂存改动时，它照样编出一段提交说明；
你只想要一份草稿，它顺手执行了 git commit；
参数写着“修复登录”，它就按参数描述改动，没去看实际的 diff。

这几个问题背后是同一件事：命令缺少一份“契约”。可靠的斜杠命令要按顺序回答四个问题：输入是什么，允许执行哪些动作，最终返回什么，遇到什么情况必须停下。有副作用的流程，还要由你来决定何时启动。下面先判断哪些流程值得做，再用 /prepare-commit 把这四个问题落到一份 SKILL.md 里。

01 斜杠菜单里有四类入口

斜杠菜单里的入口有不同的执行方式，可以先分为四类：

类型	例子	实际作用
内置命令	`/clear`、`/compact`、`/model`	直接控制 Claude Code 的会话或界面状态
内置 Skill	`/debug`、`/simplify`	加载官方提供的提示与工作流程，由 Claude 使用工具执行
自定义 Skill	`/prepare-commit`	加载项目或个人编写的流程，既可手动触发，也可按配置由 Claude 调用
旧式自定义 Command	`.claude/commands/review.md`	兼容旧项目，同样生成 `/review` 入口

例如，/clear 直接改变会话状态，修改 Skill 提示词不会改变它；/debug 加载排错方法，后续结果受提示与工具权限影响。入口类型不同，排查方向也不同。

看到 Command 这个词，先看它指什么：有时泛指斜杠入口，有时专指旧的 .claude/commands/ 文件。Claude Code 的 Skills 文档写得很明确：自定义命令已经并入 Skill，.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会创建 /deploy，用法相同，旧文件继续可用。新流程优先写 Skill，手动入口、脚本、模板和参考都能放在一起。

02 哪些流程值得做成命令

适合命令化的流程应反复出现，而且输入、允许动作、结果与停止条件相对稳定。提交说明准备、测试失败归纳和 API Schema 检查，都可以按这些条件判断。

判断是否值得封装，要看它能否减少下一次的重复判断。一次性小改动可以直接说明；审查标准还在变化，就先用真实任务试，等输入、步骤和标准稳定后再保存。

给复杂需求起一个 /build-payment 的短名字，并没有确定支付系统的范围和设计。还在探索的需求，先在对话中澄清关键判断，再决定哪些部分值得复用。

Claude Code 最佳实践把这类内容称为团队流程：模型再强，也不知道你们团队怎样发版、事故手册写了什么、API 文档要怎么写，这类知识适合放进 Skill。官方同时提醒，CLAUDE.md 的原则对 Skill 同样适用：只写 Claude 自己找不到的东西。

03 一个只准备、不提交的 /prepare-commit

下面创建一个只分析暂存区、不执行提交的 /prepare-commit：

.claude/
└── skills/
    └── prepare-commit/
        └── SKILL.md

SKILL.md 可以这样写：

---
name: prepare-commit
description: 检查暂存区改动并生成符合项目约定的提交说明
disable-model-invocation: true
argument-hint: "[可选：本次改动目的]"
allowed-tools: Bash(git diff *), Bash(git status *)
---

分析当前暂存区改动，并结合用户提供的目的：`$ARGUMENTS`

1. 运行 `git status --short`，确认哪些文件已经暂存。
2. 若不是 Git 仓库、命令失败或没有暂存改动，说明原因后停止，不生成虚构的提交说明。
3. 先用 `git diff --cached --stat` 确认范围，再分文件读取暂存区差异；若发现疑似凭证，只报告文件位置，不复述秘密值，并停止准备。
4. 说明主要行为变化、潜在风险和缺失的验证，生成简洁的提交标题及必要正文。
5. 返回草稿后结束，不暂存文件、不提交、不推送。

保存后，在 Claude Code 中输入：

/prepare-commit 修复刷新令牌失效逻辑

再看调用末尾那段“修复刷新令牌失效逻辑”，它会完整传入 $ARGUMENTS。这次改动目的会变，暂存区检查的方法不变，于是把前者作为参数，后者留在 Skill。下次调用只补变化的部分即可。

参数只承载每次变化的信息。除了 $ARGUMENTS，也可以用 $0、$1 按位置取，或在 frontmatter 里声明命名参数：

argument-hint: "<component> <base-ref>"
arguments:
  - component
  - base

正文就能用 $component 和 $base。

小黑启动由输入、动作、输出和停止条件组成的斜杠命令执行契约

04 写清输入、动作、结果和停止条件

一条可靠的命令要按顺序回答四个问题：

输入是什么
    ↓
允许执行哪些动作
    ↓
最终返回什么结果
    ↓
遇到什么情况必须停下

这个入口到草稿阶段就结束：根据暂存区差异和可选目的，检查状态，返回风险摘要及提交说明。没有改动、发现疑似秘密或 Git 命令失败，就停。是否提交，再由用户决定。

准备草稿时，分别核对两种范围：

看到的内容	怎样处理
已暂存修复，另有未暂存重构	只描述暂存区这次要提交的内容
参数写“修复登录”，暂存 diff 却没有	指出不一致，按实际差异判断，不能编造改动

输入提示本身不会检查参数。官方文档说明，命名参数没有收到对应输入时会展开成空字符串。所以缺参数、目标不存在、格式不对时，正文要自己说明原因并停下。部署环境和资源 ID 等输入，更不能随手补默认值。

05 有副作用的流程由你启动

会改变外部状态的部署、发布或清理流程，通常使用 disable-model-invocation: true，由用户决定启动时机。本例虽然只准备草稿，也把准备时机留给用户。官方文档举的例子正是 /commit、/deploy、/send-slack-message，理由也很直白：你不会希望 Claude 因为觉得代码看起来准备好了，就自己决定去部署。

只供 Claude 自动参考的内部材料，可以设 user-invocable: false。这样用户菜单里看不到，也不能直接输入命令调用。两种设置的完整区别和 Claude 何时自动调用，见Claude Code Skill 不触发或乱触发。

命令还要遵守底层的权限规则。allowed-tools 只提供当前轮次的免确认授权，如果命中了项目或用户配置里的 deny，仍会被直接拦截。

权限已经放开时，也要分清准备和提交。用户要求“准备提交”，即使工具允许 git commit，这次仍只做分析和草稿。反过来，即使用户要求执行，也仍要遵守工具的拒绝决定。手动启动只决定何时开始，不自动批准内部的全部副作用：任务授权和工具许可，两项都满足才行动。

06 迁移旧命令时先建新版

.claude/commands/deploy.md 仍能提供 /deploy，但同名 Skill 一旦存在，就会优先。官方文档在同名冲突的规则里写明：Skill 和 .claude/commands/ 里的同名文件同时存在时，用的是 Skill。

迁移旧入口时，先查团队现在调用的是哪一份。先建并验证新 Skill，再清理旧文件，能把版本变化看清楚，避免有人在过渡期间用到不同的方法。命令名直接说明动作，比如 /review-api-change，单看名字也知道要做什么。

新命令写好后，先用 /skills 确认它被发现了，再分别测试有暂存改动和没有暂存改动的情况：前者返回相符草稿，后者说明原因后停止。两者都符合契约；没有输入时编造总结则不符合。菜单里找不到、或调到了别的同名版本时，排查方法见自定义 Skill 不显示或调到旧版的排查方法。