Claude学院

Claude Code 自定义斜杠命令教程（附实用示例）

在 Claude Code 里自定义斜杠命令，本质上就是在项目的 .claude/commands/ 目录（或个人的 ~/.claude/commands/ 目录）下放一个 Markdown 文件，文件名就是命令名，文件内容就是这条命令执行时发给 Claude 的提示词。建好后输入 /文件名 即可触发。下面从目录结构、文件写法、参数传递到三个实战示例，完整讲一遍。

斜杠命令是什么，为什么要自定义

Claude Code 内置了一批斜杠命令，比如 /clear 清空上下文、/init 生成 CLAUDE.md 配置文件、/help 查看帮助。自定义斜杠命令则是把你团队里反复输入的那段提示词（例如"按规范评审这段代码""生成符合 Conventional Commits 的提交信息"）固化成一条 /命令，敲几个字符就能调用，省去每次复制粘贴长提示词。

它和 子代理（Subagent） 不同：斜杠命令是把一段提示词模板注入当前会话，复用的是"提示词"；子代理是独立上下文的专职助手。如果你只是想复用一段指令，斜杠命令是最轻量的方案。

两种作用域：项目级与个人级

自定义命令按存放位置分两类，决定了它对谁可见：

类型存放目录命令标记适用场景
项目级.claude/commands/(project)随仓库提交，团队共享
个人级~/.claude/commands/(user)跨所有项目，仅自己可用

项目级目录放在仓库根目录下，提交到 Git 后，团队成员拉取代码就能用同一套命令，非常适合统一代码评审、提交规范。个人级目录在你的用户主目录下（Windows 是 C:\Users\你的用户名\.claude\commands\），无论在哪个项目都能用。如果还没装好 Claude Code，先看 Windows 安装教程 或 Mac 安装教程。

创建第一个命令

以一条"用中文解释代码"的命令为例。在项目根目录执行：

mkdir -p .claude/commands
echo "请用简体中文逐行解释下面这段代码的作用和潜在问题。" > .claude/commands/explain.md

回到 Claude Code 输入 /explain，它就会把这段文本作为提示词执行。命令名取自文件名，所以 explain.md 对应 /explain。如果命令没出现，重启一下 Claude Code 会话即可重新扫描目录。

用 $ARGUMENTS 接收参数

固定提示词不够灵活，常常需要传入动态内容。Claude Code 支持两种占位符：

  • $ARGUMENTS：接收命令后面跟的全部参数（一整串）。
  • $1、$2 …：按位置接收单个参数，适合参数个数固定的场景。

例如新建 .claude/commands/fix-issue.md，内容写：

请定位并修复编号为 #$ARGUMENTS 的问题。
步骤：先在代码库中检索相关文件，说明根因，再给出最小改动的补丁。

使用时输入 /fix-issue 142，$ARGUMENTS 会被替换为 142。如果用位置参数，比如模板里写 把 $1 重命名为 $2，调用 /rename oldName newName 即可分别填入。

用 frontmatter 控制命令行为

在 Markdown 文件顶部用 YAML frontmatter（--- 包裹）可以配置元信息，常用字段如下：

字段作用
description命令的简短说明，在 / 列表里显示
argument-hint参数提示，告诉用户该传什么
allowed-tools限定该命令可用的工具，如只允许只读操作
model指定运行模型，如 Claude Opus 4.8 或 Claude Haiku 4.5

一个带完整配置的示例：

---
description: 按团队规范评审暂存区代码
argument-hint: [可选：关注点，如安全/性能]
allowed-tools: Bash(git diff:*), Read
model: claude-opus-4-8
---
请评审 git 暂存区的改动，重点关注 $ARGUMENTS。
输出格式：问题清单（按严重程度排序）+ 修改建议。

其中 allowed-tools 限定了这条命令只能跑 git diff 和读文件，避免误操作；选 合适的模型 也能在质量和速度间平衡——评审这类重任务适合 Opus 4.8，简单格式化用 Haiku 4.5 即可。

引用文件与执行命令

命令模板里还能嵌入两种动态内容，让 Claude 在执行时自动获取上下文：

  • @文件引用：用 @路径 把文件内容带进提示词。例如 请参考 @docs/style-guide.md 的规范评审代码。
  • !命令执行：以 ! 开头的行会先执行 shell 命令并把输出注入提示词（需要在 allowed-tools 中放行对应命令）。例如 !git diff --staged 会把暂存区 diff 直接喂给模型。

命名空间：用子目录分组

命令多了可以用子目录归类。比如把文件放在 .claude/commands/git/commit.md，命令就变成 /git:commit，子目录名作为命名空间前缀，便于在 / 列表里区分。

三个实用示例

1. 生成 Conventional Commits 提交信息

文件 .claude/commands/commit-msg.md：

---
description: 根据暂存区改动生成提交信息
allowed-tools: Bash(git diff:*), Bash(git status:*)
---
!git diff --staged
基于以上改动，生成一条符合 Conventional Commits 规范的提交信息。
要求：type(scope): subject 格式，subject 用中文，不超过 50 字，必要时附正文说明动机。

2. 为指定文件补单元测试

文件 .claude/commands/test.md：

---
description: 为指定文件补充单元测试
argument-hint: [文件路径]
---
请阅读 @$ARGUMENTS，为其中未覆盖的逻辑补充单元测试。
覆盖正常路径、边界值和异常分支，沿用项目现有测试框架与命名风格。

调用 /test src/utils/date.py，@$ARGUMENTS 会把该文件内容读进来。

3. 安全评审

文件 .claude/commands/security/review.md，对应 /security:review：

---
description: 对当前分支改动做安全评审
allowed-tools: Bash(git diff:*), Read, Grep
---
!git diff main...HEAD
检查以上改动是否存在：注入风险、鉴权缺失、敏感信息硬编码、不安全的依赖调用。
逐条给出位置、风险等级和修复建议。

这些命令配合 Hooks 自动化工作流 使用效果更佳，比如提交前自动触发评审。更多内置命令可参考 常用命令大全。

常见问题

自定义斜杠命令和 CLAUDE.md 有什么区别？

CLAUDE.md 是项目的常驻上下文，每次会话都会自动加载，适合放编码规范、架构说明这类"始终生效"的信息；斜杠命令是按需触发的提示词模板，只在你输入 /命令 时注入一次。前者是背景知识，后者是一次性任务指令，两者互补。

命令里能调用 Claude API 吗？

斜杠命令运行在 Claude Code 会话内部，本身是给当前模型的提示词，不直接发起 HTTP 请求。如果你想在脚本里独立调用模型，应使用 Messages API（POST /v1/messages，鉴权头 x-api-key 加 anthropic-version），可配合官方 Python SDK 编写，与斜杠命令是两条不同的使用路径。

创建了命令但 / 列表里看不到怎么办？

先确认文件扩展名是 .md、放在 .claude/commands/ 或 ~/.claude/commands/ 下，且目录名拼写正确；然后退出并重新进入 Claude Code 会话让它重新扫描目录。若仍不行，检查 frontmatter 的 YAML 缩进是否合法（用空格不用 Tab）。其他疑难可对照 问题排查清单。

← Claude Code