Claude Code Slash Commands 怎么写？把重复指令变命令文件新手指南

预计阅读 18 分钟 ｜ 目标：用新手能听懂的话讲清 Claude Code Slash Commands（斜杠命令），看完知道它是什么、自己该不该用、第一条命令怎么写、四大语法怎么用、怎么验证。

先别被术语吓住。把 Slash Commands 想成「把你反复对 Claude Code 说的那段话，存成一个可以一键调用的快捷按钮」。你不需要先懂源码，也不需要一次记住所有配置；这篇按「先判断该不该用 → 再上手写第一条 → 再补四大语法 → 最后讲组织与避坑」的顺序，一步步带你走。

30 秒答疑：先把结论拿走

如果你只想快速判断 Claude Code Slash Commands 值不值得学：只要你在做长期项目、有反复出现的任务、或者要和团队共享工作流，就值得；如果只是偶尔问一次 AI，它不是第一优先级。 Slash Commands 的本质是把一段高频提示词存成命令文件，之后输入 /命令名 一次调用，还能传参数、跑 bash、引文件。

先按身份对号入座，看你这类人该从哪一步开始：

最常见的新手错误：一上来就写一堆命令，结果连一个重复动作都还没跑顺——命令的价值在「被反复复用」，不在「有多少个」。

要点速览

• Slash Commands = 把高频 prompt 存成 markdown 命令文件，输入 /命令名 一键调用。
• 两个层级：Personal（~/.claude/commands/，全项目可用）和 Project（.claude/commands/，提交 git 团队共享）。
• 四大语法：frontmatter 配置 + $ARGUMENTS 传参 + ! 跑 bash + @ 引文件。
• 判断口诀：一段 prompt 重复 ≥ 3 次、边界稳定，才值得写成命令。

一、先搞懂：命令文件到底解决什么问题

Slash Commands 解决的核心问题是「重复指令不稳定」。 你大概遇到过这种情况：同一类任务每次都要重新敲一大段话，只要少写一句边界，Claude Code 就会按自己的理解去补——这次帮你顺手改了不该动的文件，下次又漏掉了测试。问题不在模型笨，而在你每次口述的边界都不完全一样。

命令文件把这段话固定下来：适用场景、需要你补的输入、禁止动作、验收标准，一次写清，以后每次调用都稳定出现。你省掉的不是打字时间，而是「每次重新解释一遍边界」的隐性成本。

💡 通俗讲：命令文件就是把一段你已经说顺了的提示词，存成一个带名字的快捷入口。它不是给 Claude Code 增加新能力，而是让同一套任务边界、输入说明和验收标准，每次都原样复现，不再靠你临场发挥。

新手最该先想清楚的，不是命令文件存哪、字段怎么填，而是「哪些话值得固化」。每天只说一次的临时需求，不值得写命令；每周都要重复的检查、整理、发布前验证、生成摘要，才适合。第一条命令也不用追求完整，你只要能复述三句话：这个命令适合什么任务、用户要给什么输入、最后怎么判断通过——能说清这三句，就能动手写。

二、为什么新手也需要懂它

新手常见误区是把 Slash Commands 当成「专家才用的高级功能」，实际恰恰相反：越是新手越需要它，因为它替你把边界写死，省掉反复出错后重启、换模型、重写 prompt 的折腾。

懂命令文件至少有三个好处。第一，重复任务不用每次重新解释，调用一下补个对象就行。第二，多项目或团队里能保持同一套执行标准，不会这个项目一个风格、那个项目又一个风格。第三，高风险动作可以在命令里提前写清确认点，而不是每次临时补一句「记得先确认」。

这里有个常被忽略的点：AI 编程效果不稳，很多时候不是模型不够强，而是每次口述的边界、上下文、工具范围都不一样。Slash Commands 的价值，正是把这些藏在脑子里的执行方式变成写在文件里的显式流程——一旦显式，就能复用、能审查、能交接给队友。

三、Slash Commands 是什么：一句定义 + 最简实例

Slash Commands 是把一段提示词写成 markdown 文件、存进 Claude Code 约定目录，输入 /文件名 即可一次性调用这段提示词。 命令名直接取自文件名（去掉 .md 扩展名）。

最简单的命令文件长这样。新建一个文件 ~/.claude/commands/changelog.md，内容只有一行正文：

把当前未提交的改动总结成三条要点，并指出其中有风险的地方（缺少错误处理、写死的值、需要更新的测试）。

存好之后，在 Claude Code 里输入 /changelog，Claude 就会按这段说明去做，不用你再敲一遍。就这么简单——一个文件、一行字，就是一条能用的命令。

这条命令现在还有个明显短板：它说「总结改动」，但没把改动真正读进来，Claude 只能凭打开的文件去猜。等到 § 六讲 ! 跑 bash，会给它补上一行 !`git diff HEAD`，让它每次先读真实改动再总结——这就是从「死模板」到「动态命令」的跨越，先记住这个伏笔。

「这不是什么」澄清：Slash Commands 不是给 Claude Code 装插件，也不是写一段会自动后台运行的脚本。它本质还是提示词，只是被存下来、加了名字、能传参数。它也不替你判断任务该不该做——命令只是入口，里面写了什么、放行了哪些工具，才决定它的边界。

⚠️ 常见踩坑：把命令文件当成「无所不能的脚本」。命令展开后仍然是交给 Claude 的提示词，涉及删除、发布、授权、付款这类动作，即使写进命令，也应该在命令里明确要求「停下来等确认」，而不是默认它会自动绕过确认去执行。

四、命令存哪：Personal 与 Project 两个层级（对号入座）

命令文件存放位置决定了谁能用它，新手只需记住 Personal 和 Project 两个层级。 下面这张表直接对号入座：

判断很简单：跨项目都想用 → Personal；只在这个项目用、还想让队友也能用 → Project。

四类人的典型选择：

• 个人开发者、多项目并行：通用命令（git 流、commit 模板）放 Personal，省得每个项目重配。
• 团队协作：核心流程放 Project 并提交 git，全队拿到同一套命令，等于共享了同一套工作规程。
• 接手别人项目：先看项目根 .claude/commands/ 里有哪些命令，能快速读懂这个项目约定了哪些标准动作。
• 既写个人项目又参与团队项目：两层都用，但严格分开——别把项目专属命令塞进 Personal，否则它会出现在每个无关项目的菜单里，造成污染。

💡 通俗讲：Personal 是你随身带的工具箱，走到哪个项目都在；Project 是钉在某个项目墙上的操作手册，只在这个项目有效，但谁进这个项目都看得到、用得上。

需要交代一个 2026 年的现状：Claude Code 已经把自定义命令并入了 skills（技能）体系。.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会创建 /deploy、行为一样；你已有的 .claude/commands/ 文件继续可用、支持相同的 frontmatter 配置。新手按本文的 .claude/commands/ 写法上手完全没问题；等你想给一条命令带上支持文件、或让 Claude 在合适时自动触发它，再了解 skills 形式即可。

五、配置之前先问一句：这段在控制什么（frontmatter 翻译）

看配置最容易被字段名吓住，处理办法是每段配置前先用一句话翻译它在控制什么，没有这句翻译就先别贴。 frontmatter（前置配置）是命令文件顶部用 --- 包起来的一段 YAML（一种靠缩进表示层级的配置写法）配置，告诉 Claude Code 这条命令的描述、参数提示、能用哪些工具等等。

下面这条带配置的命令，每个字段前都先翻译一句：

---
description: 审查指定文件的代码质量和最佳实践
argument-hint: [文件路径]
allowed-tools: Read, Grep
---

审查这个文件的代码质量和潜在问题：@$0

重点看：命名是否清晰、有没有重复逻辑、错误处理是否完整。
只读、不要修改文件。

逐字段翻译：

• description：命令描述，会显示在 / 菜单里，也帮 Claude 判断什么时候该自动调用这条命令。
• argument-hint：参数提示，输入命令名时补全菜单显示 [文件路径]，提醒你该补什么。
• allowed-tools：这条命令运行时免确认放行的工具。这里给了 Read, Grep，意思是它只读不改。

新手最该先用的就是这三个字段：description + argument-hint + allowed-tools。其余字段（如 model 指定模型、disable-model-invocation 禁止自动触发、arguments 声明命名参数）等用熟了再加。

⚠️ 常见踩坑：把模型版本号写死进 model 字段。模型名会更新，写死的版本号过一阵就成了过期信息。新手阶段大多不需要指定模型，让它跟随当前会话即可。

六、四大语法实战：让命令真正「活」起来

命令文件区别于一段静态文本的关键，是四个语法：frontmatter 配置、$ARGUMENTS 传参、! 跑 bash、@ 引文件。 frontmatter 上一节讲过，这一节讲剩下三个能让命令「随项目状态变化」的动态语法。

6.1 `$ARGUMENTS` / `$0` / `$1`：把可变信息传进命令

命令名后面跟的文字，会作为参数传进命令文件。两种取法：

• $ARGUMENTS：拿到全部参数组成的一整个字符串。例：运行 /fix-issue 123 紧急，则 $ARGUMENTS = 123 紧急。
• $0 / $1 （按位置取，索引从 0 开始）：$0 是第一个参数、$1 是第二个，以此类推（完整写法是 $ARGUMENTS[0] / $ARGUMENTS[1]，$0 是它的简写）。例：/fix-issue 123 紧急，则 $0 = 123、$1 = 紧急。

一个传单参数的命令 ~/.claude/commands/fix-issue.md：

---
description: 按编号修复一个 GitHub issue
argument-hint: [issue 编号]
---

按我们的代码规范修复 GitHub issue $ARGUMENTS：
1. 读 issue 描述，理解需求
2. 实现修复
3. 补测试
4. 生成一次提交

运行 /fix-issue 123，Claude 收到的就是「按我们的代码规范修复 GitHub issue 123……」。

💡 通俗讲：$ARGUMENTS 就像命令里挖的一个填空格，你运行命令时跟在后面打的字，会被原样填进这个空格。$0、$1 则是把这些字按空格拆开、按顺序分别填进对应的格子。

需要按位置取多个参数时，用 $0、$1、$2：

---
description: 把一个组件从一个框架迁移到另一个
argument-hint: [组件名] [源框架] [目标框架]
---

把 $0 组件从 $1 迁移到 $2，保留所有现有行为和测试。

运行 /迁移 搜索框 React Vue，$0 = 搜索框、$1 = React、$2 = Vue。

⚠️ 常见踩坑：多词参数不加引号。按位置取参数时用的是命令行式的拆词规则，/迁移 搜索框组件 React Vue 会把「搜索框组件」当一个词没问题，但如果参数本身含空格，比如想把「用户中心 搜索框」当成一个参数，就要写成 /迁移 "用户中心 搜索框" React Vue，否则空格会被拆开、对错位置。

6.2 `!` 跑 bash：让命令带上项目的真实状态

在命令文件里以 ! 开头、用反引号包起来的命令，会在 Claude 看到提示词之前先执行，输出替换掉那一行塞进提示词。 这是预处理，不是 Claude 去跑——Claude 只看到最终结果。

例如一条「总结当前改动」的命令：

---
description: 总结当前未提交的改动并标出风险
allowed-tools: Bash(git diff *), Bash(git status *)
---

## 当前改动
!`git diff HEAD`

## 你的任务
把上面的改动总结成三条要点，并指出风险（缺错误处理、写死的值、要更新的测试）。

执行 /changelog 时，!`git diff HEAD` 这行会先跑，把当前真实的代码 diff 直接填进提示词，于是 Claude 拿到的是「带着你此刻真实改动」的提示词，而不是一句空泛的「总结我的改动」。

几个要点：

• 跑 bash 需要在 allowed-tools 里放行对应命令，例如 allowed-tools: Bash(git diff *)，否则会被权限拦下。
• ! 只有在行首、或紧跟空白时才被识别为「跑 bash」；如果 ! 跟在别的字符后面（比如 KEY=!...``），它会被当成普通文本、不执行。
• 多行 bash 用 ```! 围栏代码块，把多条命令写在里面。

🔥 翔宇判断：! 跑 bash 是命令文件最被低估的能力。没有它，命令只是一段固定文字；有了它，命令就能在每次执行时「看一眼项目现在长什么样」再行动。一条「读最新 git diff 再总结」的命令，比一句「帮我总结改动」靠谱得多，因为前者每次都基于真实状态，后者全靠 Claude 猜。

6.3 @ 引文件：把文件内容塞进上下文

用 @ 开头加路径，可以把文件、目录或网址的内容直接引进命令的上下文，不用复制粘贴。 基本形式：

• @README.md：引一个文件。
• @src/components/：引整个目录。
• @https://example.com：拉取一个网址的内容（只读）。

@ 还能和参数组合。比如一条审查命令，把要审查的文件用 @$0 引进来——$0 是你传的文件路径，@ 把那个文件的内容塞进上下文：

---
description: 审查指定文件
argument-hint: [文件路径]
allowed-tools: Read
---

审查这个文件的代码质量和最佳实践：@$0

运行 `/审查 src/app.js`，`@$0` 就展开成 `@src/app.js`，把 `src/app.js` 的内容引进来。

> 💡 通俗讲：`@` 就是「把这个文件的内容贴进来给你看」的快捷方式，省得你手动复制粘贴。配合 `$0` 用，就成了「我说哪个文件、你就把哪个文件读进来」。

`!`（跑 bash 拿动态输出）和 `@`（引文件内容）组合起来，命令就成了真正的「动态提示词」——每次执行都根据当前项目状态生成不同内容。这正是命令文件比一段死的文本模板强的地方。

### 6.4 四个语法串起来：一个能直接抄走的完整命令

把四大语法合在一条命令里，你就有了一个可以照抄的范例。下面这条 `~/.claude/commands/changelog.md` 是 § 三那条简单版的完整体——补齐了 frontmatter、bash 注入和文件引用：

```text
---
description: 总结当前未提交的改动并标出风险
argument-hint: [可选：补充说明]
allowed-tools: Bash(git diff *), Bash(git status *)
---

当前改动

!git diff HEAD

变更记录约定

@docs/changelog-format.md

你的任务

$ARGUMENTS

把上面的改动按变更记录约定总结成三条要点，并指出风险（缺错误处理、写死的值、要更新的测试）。
只总结、不要修改任何文件；没有未提交改动时直接说明。

逐行看它怎么用上四个语法：frontmatter 写清描述、参数提示和放行的工具；!`git diff HEAD` 在执行前先把真实改动读进来；@docs/changelog-format.md 把团队的变更记录格式引进来当约定；$ARGUMENTS 留出口子，让你运行时补一句临时说明（比如 /changelog 只看后端改动）。最后两句是边界和失败路径——这才是让命令稳定的关键，不是语法本身。

🔥 翔宇判断：新手常把精力花在记语法上，其实四个语法半小时就能记住。真正决定一条命令好不好用的，是最后那两句边界——「只总结不修改」「没改动时直接说明」。把失败路径和禁止动作写清楚，命令在真实项目里才不会乱来；语法只是把这些边界送进去的管道。

七、命令多了怎么组织：子目录分组

命令一多就该按场景分组，做法是把命令文件放进子目录。 例如 .claude/commands/frontend/component.md 会创建 /component 命令、归在 frontend 这一组下。好处有三：

1. 命令多时按场景分组，好找。
2. 输入 / 时补全菜单会分类显示。
3. 团队里不同模块的负责人各管一组命令。

建议的分组方式：在 .claude/commands/ 下按场景建子目录，比如 git/、refactor/、test/、deploy/、db/。

什么时候开始分组？前五个命令不必分组，平铺着放最直观；超过十个命令再开始按场景归类，否则提前分组反而增加管理成本。

⚠️ 常见踩坑：太早搞复杂目录结构。新手前几条命令直接平铺在 .claude/commands/ 下就好。等命令真的多到一个菜单翻不完，再分组也不迟——过早规划目录，往往是给还没成形的命令库强加结构。

八、MCP 服务器命令：外部能力的一键调用

MCP 服务器提供的命令是 Slash Commands 的一种特殊形式，格式固定为 /mcp__服务器名__提示名。 MCP（模型上下文协议，Model Context Protocol，详见 Claude Code MCP 工具新手指南）服务器能对外暴露提示词，连上 Claude Code 后会自动变成斜杠命令。

它的几个特点：

• 命名格式固定：/mcp__服务器名__提示名，用双下划线分隔。例如连上一个 GitHub MCP 服务器后，可能就能用 /mcp__github__list_prs。
• 动态发现：连上服务器，它的命令就出现；断开，就消失。
• 需要服务器在运行：用 /mcp 管理 MCP 服务器连接。

它和你自己写的 .claude/commands/ 命令的区别：MCP 命令由服务器定义、不是你写的；服务器升级时命令可能变；命名空间固定。

所以 MCP 命令和自定义命令不是二选一，而是分工：MCP 命令是外部能力的一键调用——别人封装好的 GitHub、数据库等操作；自定义命令是你自己工作流的沉淀。两者并存最实用，用 MCP 命令调外部能力，用自定义命令把你的活儿规程化。

九、命令组织的真实路由：从一条到一套

讲完语法，给你一套按风险从低到高排的命令组织顺序——不是让你照抄，而是看清「命令库是怎么从一条自然长成一套的」。 顺序背后只有一个原则：先沉淀低风险、好验收的命令，把信任攒起来，再碰会动文件的高风险命令。

一套好用的命令库，通常是这么演化的：

1. 从一条「检查类」命令起步。最先值得写的是只读、不改文件的检查命令：发布前清单检查、依赖风险扫描、文章结构检查。它风险最低，输出好验收，最适合练手。
2. 加「摘要类」命令。把本轮改动总结成发布记录、把一个目录的任务状态整理成短报告。这类命令训练你写清输出格式，让 Claude 少自由发挥——可以要求它只输出结论、路径、下一步，不要展开成长文。
3. 最后才加「执行类」命令。会改文件、跑命令、触发工具的命令，边界要写得最窄：工作目录、允许改的文件范围、必须保留的用户改动、失败时是否停止，都要写清。
4. 按场景分组、定期清理。命令过十个就按 git/、test/、deploy/ 等子目录分组；用过几次发现不稳定、低频、边界说不清的命令，就删掉或合并。

命令命名要朴素，名字最好直接说明用途，比如 article-check、release-notes、test-summary，别为了好看起抽象名字——三个月后你自己也会忘。

判断一条命令是否成熟，有个很实在的信号：当你愿意在真实任务里直接调用它、不再每次重新解释一遍，它就成熟了；反过来，如果每次运行前都要补一堆说明，它还只是个半成品提示词。值得反复使用的有几条，比命令库里堆了多少条更说明问题。

十、5 个常见坑：别把系统做复杂

新手用 Slash Commands 最容易栽的，是把命令做得又大又宽。 五个高频坑，逐个给正确做法：

1. 一条命令塞太多职责。又想检查、又想修改、又想发布、又想写报告，结果每次都要人盯着。✅ 拆小：检查归检查、修改归修改、发布前确认归发布前确认。
2. 把命令当权限放大器。命令只是入口，不代表它能绕过确认。✅ 涉及删除、发布、授权、付款、线上配置的动作，即使写进命令，也明确要求停下来确认。
3. 写一堆判断口号，却不落到动作。✅ 真正有用的判断必须落到具体动作：哪个文件改、哪个命令跑、哪个结果算通过。
4. 参数设计太自由。参数越多、输入形态越多，出错概率越大。✅ 从一个参数起步，等命令稳定再加第二个；新手阶段宁可少给参数，也要让命令稳定执行。
5. 不写失败路径。检查时发现 Schema 不完整，是停下报告还是继续查？没有 git 仓库时怎么办？✅ 把失败时怎么办写进命令，否则它会在真实任务里开始猜，猜得越多越要人盯着。

⚠️ 常见踩坑：用「帮我优化项目」这种一句话太宽的需求去写执行类命令。这种需求边界不清，根本不适合命令化——命令要的是窄而清晰的任务，不是包罗万象的指令。

十一、进阶路径：跑两周后下一步学什么

先用两周把基础命令跑顺，再按下面三步进阶。 不要一上来就追求完整命令库。

• 第 1 天：能不能跑顺一条自定义命令——写一条检查类命令，调用一次看结果是否稳定。
• 第 1 周：能不能复用——把上周记下来的重复动作里，挑一两个写成命令，开始用 $ARGUMENTS 传参、用 @ 引文件。
• 第 1 个月：能不能沉淀成流程——命令过十个就按场景分组；把通用规则移到项目记忆文件（CLAUDE.md），命令只留任务入口；开始试 ! 跑 bash 让命令带上项目真实状态。

进阶之后还想往深走，可以顺着同系列文章了解 Claude Code 的项目记忆、权限边界和 MCP 工具——命令文件、项目记忆、权限三者配合，才是一套能放心交给它干活的工作流。

十二、自检清单：你的第一条命令合格了吗

写完一条命令，对照下面勾一遍：

• [ ] 命令文件存对位置了吗？（通用 → ~/.claude/commands/；项目专属 → 项目根 .claude/commands/）
• [ ] 写清了它适合什么任务、不适合什么任务吗？
• [ ] 写清了用户要补什么输入吗？（用 argument-hint 提示）
• [ ] 写清了不能做的危险动作吗？（删除/发布/授权要停下确认）
• [ ] 用 allowed-tools 把工具权限收窄到够用就行了吗？
• [ ] 跑了一次真实任务、结果稳定吗？
• [ ] 连续跑三次，结果是否一致？（这是命令成熟的硬验收）

验收方式很简单：同一件事连续跑三次，结果是否稳定。 如果每次都要你补充大量说明，说明命令还没把任务边界写清——继续改命令文件，不要把问题推给模型。

一句话收官 + 相关阅读

命令不是魔法，是把你已经成熟的工作方式保存下来。流程还没想清之前，先别急着命令化；一旦一段提示词你反复说了三次、边界又稳定，就把它存成命令——之后你的注意力会从「怎么跟 AI 解释」转回「我要检查什么、交付什么、哪里不能碰」。这就是 Slash Commands 给新手最实际的帮助：少一点临场发挥，多一点稳定动作。

第一条命令，建议从「检查类」开始：只读、不改文件、风险低，还能立刻验证命令设计清不清楚。比如检查文章结构是否完整、检查代码改动是否超出范围、检查发布前清单。等检查和摘要类命令都跑稳了，再去碰会改文件的执行类命令。

同系列下一步：

• Claude Code 是什么：新手完整认知
• Claude Code 完整功能总览
• Claude Code App / CLI / IDE 怎么选
• Claude Code 项目记忆 CLAUDE.md 指南
• Claude Code MCP 工具新手指南
• Claude Code 权限设置新手指南

外部参考（Claude Code 官方文档）：

• https://code.claude.com/docs/en/slash-commands
• https://code.claude.com/docs/en/commands
• https://code.claude.com/docs/en/mcp