<!-- title: 把提示词做成斜杠快捷命令 -->

# Claude Code 自定义斜杠命令入门：把常用提示词做成一键指令

## 概述

如果你发现自己在 Claude Code 里反复手敲同一段长提示词——"帮我审查这次改动"、"按 Conventional Commits 写提交信息"、"先解释这段再重构"——那它们就该被做成斜杠命令。本教程面向零基础用户，目标是用一个下午的时间掌握自定义斜杠命令（Custom Slash Commands）：从认识内置命令、创建第一个 `/commit` 命令，到参数化、Bash 注入、命名空间化，最终搭建一套跨项目复用的"个人效率命令包"。适合从未写过 `.claude/` 配置、但已经能在终端里跑通 `claude` 命令的新手。

## 前置条件

- 已安装 Node.js（建议 18 LTS 及以上）与 Claude Code CLI，能在终端运行 `claude --version`
- 有一个可用的 Claude 账号并完成首次登录（首次会引导登录或填 API Key）
- 会基本的终端操作：`cd`、`mkdir`、编辑文本文件（VS Code、Vim 均可）
- 一个用来练手的 Git 仓库（可以是新建的空仓库，用于验证提交命令）
- 本文命令与字段基于 2026 年版 Claude Code，不同小版本字段名可能略有差异，以 `/help` 实际提示为准

## 第一步：先认清"内置命令"与"自定义命令"

进入任意项目目录，运行 `claude` 启动交互式会话，输入 `/` 会弹出一个命令列表。这些是**内置斜杠命令**，由 Claude Code 自带，常见有：

| 命令 | 作用 |
|------|------|
| `/init` | 扫描项目，生成 `CLAUDE.md` 项目记忆文件 |
| `/clear` | 清空当前会话上下文 |
| `/compact` | 压缩历史对话，保留要点以节省上下文 |
| `/config` | 打开图形化配置面板 |
| `/model` | 切换模型（如 Opus / Sonnet / Haiku） |
| `/cost` | 查看本次会话 token 花费 |
| `/help` | 列出全部可用命令 |
| `/review` | 对当前改动做代码审查 |
| `/agents` | 管理子代理 |

内置命令解决的是"通用需求"。**自定义命令**解决的则是"你的需求"——把你或团队的私有流程封装成 `/your-command`，调用方式与内置命令完全一致。二者的本质区别只有一个：自定义命令是你自己放在 `.claude/commands/` 里的 Markdown 文件。

> **预期结果**：在终端输入 `/` 后能看到一长串以斜杠开头的命令，并能在输入框里用方向键预览每个命令的说明文字。

## 第二步：理解命令的三种"住址"

自定义命令本质是 `.md` 文件，文件名即命令名。它有三个可选的存放位置，决定了它的**作用范围**与**是否随仓库共享**：

| 位置 | 作用范围 | 是否进 Git | 典型用途 |
|------|----------|------------|----------|
| `~/.claude/commands/` | 你电脑上的**所有项目** | 否（在你的主目录里） | 个人习惯命令，走到哪都能用 |
| `<项目>/.claude/commands/` | 仅当前项目 | 是（提交后团队共享） | 团队约定流程，如 PR 检查清单 |
| `<项目>/.claude/commands/local/` | 仅当前项目、仅你自己 | 否（自动被忽略） | 含个人 token 或临时试验的命令 |

这条规则是后面所有实践的基础，务必记牢：**想让全团队复用 → 放项目目录；只想自己用 → 放家目录或 `local/`**。

## 第三步：创建第一个命令 `/commit`（零参数版）

我们来做一个所有人都爱的命令：根据已暂存的改动，自动写一条 Conventional Commits 风格的提交信息。

**操作**：

```bash
mkdir -p .claude/commands
```

新建文件 `.claude/commands/commit.md`，内容如下：

```markdown
---
description: 根据 git 已暂存改动生成 Conventional Commits 提交信息
argument-hint: （无需参数）
---

你是一位资深工程师，请按以下步骤工作：

1. 读取 `git diff --cached` 的内容，理解本次改动做了什么、为什么做。
2. 用 Conventional Commits 规范写一条**单行**提交信息，格式为：
   `<type>(<scope>): <subject>`
   - type 从 feat / fix / docs / style / refactor / perf / test / chore 中选最贴切的
   - scope 用小写英文表示影响模块，没有则省略
   - subject 用中文，不超过 30 字，不加句号
3. 如果改动复杂，再补一段空行后的正文，说明动机与关键决策。
4. 最后给出可直接复制的最终提交信息，不要替我执行 git commit。
```

**预期结果**：在会话里输入 `/commit` 回车，Claude 会读取暂存区改动并输出一条建议提交信息。你在仓库里 `git add` 一些改动后再调用，效果最佳。

**常见问题**：

- **命令没出现在 `/` 列表里**：确认文件后缀是 `.md`、文件放在 `.claude/commands/` 根目录下（不是嵌套在别的文件夹里），并重启或新开一个会话。
- **文件名里有空格或中文**：命令名取自文件名，建议只用小写英文和短横线，如 `commit.md`、`pr-ready.md`，避免 `/` 列表里出现怪异字符。
- **`description` 不显示**：YAML 头部必须用三个短横线包裹，且 `description:` 后要有内容，否则自动补全里看不到说明。

## 第四步：用 `$ARGUMENTS` 做带参数命令 `/explain`

很多场景需要"命令 + 一段自由文本"。比如让 Claude 用新手能懂的方式解释一段代码或一个概念。`$ARGUMENTS` 占位符会把你在命令后输入的所有文字原样塞进提示词。

新建 `.claude/commands/explain.md`：

```markdown
---
description: 用小学生能懂的话解释一段代码或一个概念
argument-hint: <要解释的代码或概念>
allowed-tools: Read
---

请用"费曼学习法"的方式解释下面这段内容，要求：

- 先用一句话总结它在做什么
- 再用一个生活化的比喻说明
- 最后点出三处最容易踩的坑

要解释的内容：
$ARGUMENTS
```

**操作与验证**：

```
/explain Promise.all 和 Promise.allSettled 的区别
```

Claude 会把你这句话替换到 `$ARGUMENTS` 的位置，生成一段结构化的解释。你也可以把一段贴进来的代码作为参数。

**进阶**：除了 `$ARGUMENTS`（整段输入），新版还支持**位置参数** `$1`、`$2`……它们按空格拆分。例如定义一个比较两个文件的命令：

```markdown
---
description: 对比两个文件的实现差异
argument-hint: <文件A> <文件B>
---

请逐行对比这两个文件的实现差异，指出设计取舍：
- 文件A：$1
- 文件B：$2
```

调用：`/diff-review src/old.js src/new.js`，`$1` 与 `$2` 分别被替换。

## 第五步：用 `!` 注入 Bash 命令输出做 `/branch`

有时候你需要让命令"先收集环境信息，再交给 Claude"。在正文里以 `!` 开头的行会被当作 **Bash 命令执行**，其标准输出会被注入到提示词里。这让命令拥有了"感知当前项目状态"的能力。

新建 `.claude/commands/branch.md`：

```markdown
---
description: 根据当前分支名与最近提交，建议下一个分支名
---

请基于以下信息，建议一个符合 Git Flow / Trunk-based 习惯的新分支名，并说明理由：

!git branch --show-current
!git log --oneline -5
```

**预期结果**：调用 `/branch` 时，Claude 会先看到你当前所在分支和最近 5 条提交，然后建议类似 `feat/payment-refund` 这样的分支名。

**常见问题**：

- **`!` 命令执行报错或被拦截**：`!` 命令仍受权限系统约束。若命令需要写文件等敏感操作，会在首次执行时弹出确认。只读命令（`git status`、`ls`、`cat`）一般直接放行。
- **想隐藏 stderr 干扰**：如果命令的报错信息会污染提示词，可以改写命令把 stderr 丢弃，例如 `!grep -r TODO src 2>/dev/null`。
- **不要把密钥写进 `!` 命令**：`!` 的内容会进入提示词上下文，等于把密钥交给模型——永远通过环境变量读取。

## 第六步：用子目录做命名空间 `/git:pr-ready`

当命令越来越多，全堆在 `commands/` 根目录会很乱。把文件放进子目录，命令名会变成 `目录名:文件名`。

```
.claude/commands/
├── commit.md            →  /commit
├── explain.md           →  /explain
├── branch.md            →  /branch
└── git/
    └── pr-ready.md      →  /git:pr-ready
```

新建 `.claude/commands/git/pr-ready.md`，做一个"提 PR 前的最终自检"：

```markdown
---
description: 提交 PR 前的自检：测试、文档、改动摘要
---

请在发起 PR 前完成以下自检，逐项给出 ✅ 或 ❌ 并附证据：

1. 本地测试是否全部通过：
   !npm test 2>&1 | tail -5
2. 是否有未提交或未推送的改动：
   !git status --short
3. 改动摘要（基于本次分支与主干的差异）：
   !git log --oneline main..HEAD
4. 是否需要更新 CLAUDE.md 或 README：
   请扫描改动涉及的模块，提醒我补文档的位置。
```

调用方式是 `/git:pr-ready`（冒号分隔）。命名空间让团队命令包可以按 `git:`、`db:`、`deploy:` 等前缀分门别类，`/` 列表里也更清爽。

## 第七步：frontmatter 进阶三件套

命令文件顶部 `---` 包裹的 YAML 是**前置元数据**，决定命令的行为：

```yaml
---
description: 在 /help 与自动补全里显示的一句话说明
argument-hint: <参数提示>      # 输入命令时灰色显示的参数占位
allowed-tools: Read, Grep, Glob  # 限制该命令运行时可用的工具
model: opus                    # 可选：让这个命令固定用某个模型
---
```

逐项说明：

- **`description`**：务必写。它是你将来在 `/` 列表里认出命令的唯一线索，不写就只能靠记文件名。
- **`argument-hint`**：填 `<文件路径>`、`<模块名>` 之类的提示，团队同事一看就知道要传什么。
- **`allowed-tools`**：**安全护栏**。比如 `/explain` 只读代码，就限定 `Read, Grep, Glob`，从根上杜绝它去改文件或跑命令。把高风险命令（`/deploy`）的 `allowed-tools` 收窄，是团队协作时的好习惯。
- **`model`**：把"烧脑"的任务（架构设计）固定给 Opus，把"机械"的任务（格式化）固定给 Haiku，能省钱又保质量。

> 注意：`allowed-tools` 是"能力上限"，不是"自动授权清单"。即便写了 `Bash`，首次执行敏感命令仍会弹确认。

## 实战案例：一套"个人效率命令包"

把上面学到的拼起来，我们在 `~/.claude/commands/` 下搭一套跨项目复用的命令包，让它在你电脑上任何项目里都可用。

```bash
mkdir -p ~/.claude/commands
cd ~/.claude/commands
```

文件一 `~/.claude/commands/todos.md`——把一句话需求拆成可勾选清单：

```markdown
---
description: 把一句话需求拆成带验收标准的待办清单
argument-hint: <需求描述>
allowed-tools: Read, Glob, Grep
---

请把下面的需求拆成可执行的待办清单：
- 每条以"- [ ]"开头，控制在能独立完成的粒度
- 每条末尾用括号注明"验收：怎样算完成"
- 涉及到的现有文件，先 Read 再判断要不要改

需求：$ARGUMENTS
```

文件二 `~/.claude/commands/refactor.md`——解释后再重构：

```markdown
---
description: 先解释当前改动，再给出重构建议
allowed-tools: Read, Glob, Grep
---

请分两步处理我当前的改动：

第一步（解释）：用表格列出每个被改动的文件、改了什么、为什么。
!git diff --stat

第二步（重构）：在不改变行为的前提下，给出 3 条可落地的重构建议，
按"收益/风险"从高到低排序，每条标注涉及的文件。

注意：只给建议，不要真的去改文件。
```

文件三 `~/.claude/commands/db/schema.md`——命名空间示例，连接只读 DB 看表结构：

```markdown
---
description: 概览当前项目的数据库表结构
allowed-tools: Bash(read_only), Read
---

请用只读方式列出本项目数据库的所有表与字段，按业务模块归类：
!sqlite3 "$(grep -h DATABASE_URL .env | cut -d= -f2)" ".tables" 2>/dev/null || echo "未找到 sqlite，请改用项目自带的脚本"
```

搭建完成后，在任意项目目录运行 `claude`，输入 `/`，你应该能看到 `/todos`、`/refactor`、`/db:schema` 三个命令。试着在某个真实项目里调用 `/todos 加一个用户头像上传功能`，观察 Claude 如何先 Read 相关文件、再产出带验收标准的清单。

## 整体工作流程

```mermaid
flowchart TD
    A["需求：反复手敲同一段提示词"] --> B{"作用范围?"}
    B -->|"全团队复用"| C[".claude/commands/xxx.md<br/>提交进 Git"]
    B -->|"仅自己/跨项目"| D["~/.claude/commands/xxx.md<br/>家目录"]
    B -->|"仅自己/仅本项目"| E[".claude/commands/local/xxx.md<br/>自动忽略"]
    C --> F["写 frontmatter<br/>description / argument-hint / allowed-tools"]
    D --> F
    E --> F
    F --> G["写正文<br/>$ARGUMENTS / !bash / @文件"]
    G --> H["在会话中输入 /命令名 调用"]
    H --> I{"效果达标?"}
    I -->|"否"| G
    I -->|"是"| J["沉淀为团队/个人命令包"]
```

## 常见问题与排错速查

- **命令不生效**：90% 是路径或文件名问题。确认是 `.claude/commands/xxx.md`（注意是点开头的 `.claude` 不是 `claude`），文件名全小写、无空格。
- **修改后旧版本还在跑**：Claude Code 会缓存命令列表，改完文件后新开一个会话，或在当前会话里重新输入 `/` 触发刷新。
- **`$ARGUMENTS` 没被替换**：检查是否真的在命令后跟了内容；`$ARGUMENTS` 必须独占一段或作为占位出现，注意不要被反引号包裹成纯文本。
- **`!` 命令没执行**：确认 `!` 在**行首**且该行只有命令本身；命令仍受权限管控，被拒时换更窄的只读写法。
- **想给团队下发的命令含私有路径**：放在 `local/` 子目录，它会被自动忽略提交，避免泄露个人配置。
- **与新版 Skills 关系**：Claude Code 近期把"可复用能力"的重心移向 Skills（`SKILL.md` + 资源目录）。自定义斜杠命令更轻量、更适合"固定提示词模板"，二者可并存——把高频提示词做成命令，把复杂多步骤能力做成 Skill。

## 延伸阅读

- 官方文档 · Slash Commands：命令字段、`!` 注入与命名空间的权威说明（见文末参考来源第 1 条）
- 官方文档 · Skills：当你需要比命令更复杂的"带资源的能力"时进入
- 官方文档 · Settings / `allowed-tools`：理解权限模型，把 `allowed-tools` 写得更安全
- 社区模板：在 GitHub 搜索 `claude-code commands` 可找到大量现成命令包，直接复制进 `.claude/commands/` 即可二次定制

## 训练营适用性评估

- **适合训练营**：面向开发者的"Claude Code 入门营 / 工程效率营"，作为第 1–2 天的"配置与定制"模块
- **教学时长**：讲师演示 + 学员动手约 **90 分钟**（讲解 30 分钟，搭建个人命令包 45 分钟，答疑 15 分钟）
- **前置衔接**：建议放在"安装与首个项目"之后、"CLAUDE.md 项目记忆"与"Skills 进阶"之前，形成"先能用 → 再定制提示词 → 最后封装能力"的递进
- **作业建议**：要求学员提交至少 3 个自定义命令的 `.md` 文件到练习仓库，其中至少 1 个使用 `$ARGUMENTS`、1 个使用 `!` 注入、1 个使用 `allowed-tools` 护栏
- **进阶方向**：完成本课后可自然过渡到 Hooks（让命令在特定时机自动触发）与 Skills（把命令升级为带脚本资源的能力）

## 参考来源

1. [Slash commands — Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code/slash-commands) — 自定义命令的目录约定、frontmatter 字段与 `!` Bash 注入的权威定义
2. [Slash Commands in the SDK — Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/slash-commands) — 在 Agent SDK 中以程序方式调用斜杠命令的说明
3. [Create Custom Slash Commands in Claude Code (2026) — MCSA Guru](https://mcsaguru.com/create-custom-slash-commands-claude-code) — 含命名空间、参数与团队共享实践
4. [How to Write a Custom Slash Command in Claude Code — Build This Now](https://www.buildthisnow.com/blog/guide/mechanics/claude-code-custom-slash-commands) — 以 Markdown 文件落地可复用提示词的机制讲解
5. [Custom Commands and Slash Commands — Samanvya](https://samanvya.dev/blog/claude-code-custom-commands) — 把 Claude Code 改造成个人 CLI 的实战案例

> 本文由「51学通信」与站长爱卫生（微信：gprshome201101）整理分享，专注通信与 AI 工程化落地。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)