Claude Code斜杠命令编写：重复指令转为命令文件新手指南

30 秒答疑：先把结论拿走

如果你正纠结 Claude Code Slash Commands 是否值得投入时间学习，直接看结论：当你从事长期项目、面临重复性任务，或需要与团队共享标准化工作流时，它绝对是高价值工具。若只是偶尔向 AI 提问一次，它确实不是你的优先选项。Slash Commands 的核心逻辑很简单——将你高频使用的提示词保存为命令文件，之后只需输入 /命令名 即可一次性调用。它不仅支持参数传递，还能运行 bash 命令、引用外部文件内容。

不同角色的用户，上手路径各有侧重。先找到你的定位：

你的身份	当前处境	推荐行动
零基础新手	刚安装 Claude Code，还在熟悉对话模式	先别急着写命令。用普通对话跑两周，把反复说过的指令记录下来
独立开发者	已经多次重复同一类任务	创建第一条「检查类」命令（只读、低风险），存入 Personal 层
团队成员	多人共用同一套流程	编写「项目级」命令，提交 git，确保全队执行标准一致
进阶用户	命令数量超过十个，感觉有些杂乱	按场景用子目录分组，定期清理不稳定或低频的命令

新手最容易踩的坑是什么？一上来就批量编写命令，结果连一个重复动作还没跑顺。请记住：命令的价值不在于「你写了多少条」，而在于「被反复复用」。

核心要点速览：

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

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

Slash Commands 要解决的核心痛点，说白了就是——重复指令的不稳定性。你可能遇到过这种情况：同一类任务每次都要重新输入一大段描述，只要少写一句边界条件，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 安装插件，也不是编写一段自动后台运行的脚本。它本质上还是提示词，只是被保存下来、加了名称、能传参数。它也不会替你判断任务该不该做——命令只是入口，里面写了什么、放行了哪些工具，才决定它的执行边界。

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

命令文件的存放位置决定了谁能使用它。新手只需记住两个层级：Personal 和 Project。下面这张表帮你快速定位：

层级	存储路径	使用范围	适合存放的内容
Personal（个人级）	~/.claude/commands/	你的所有项目都能用，不随项目共享	跨项目通用：提交信息模板、代码审查清单、变更摘要
Project（项目级）	<项目根>/.claude/commands/	只在当前项目生效，提交 git 后团队共享	项目专属：发布前检查、特定模块重构、本项目测试流程

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

四类用户的典型选择：

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

需要说明一个 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 声明命名参数）等用熟练后再添加。

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

命令文件区别于静态文本的核心，在于四个语法：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 issueargument-hint: [issue 编号]---按我们的代码规范修复 GitHub issue $ARGUMENTS：1. 读 issue 描述，理解需求2. 实现修复3. 补测试4. 生成一次提交

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

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

---description: 把一个组件从一个框架迁移到另一个argument-hint: [组件名] [源框架] [目标框架]---把 $0 组件从 $1 迁移到 $2，保留所有现有行为和测试。

运行 /迁移 搜索框 React Vue，$0 = 搜索框、$1 = React、$2 = 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 用 ```! 围栏代码块，把多条命令写在其中。

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 注入和文件引用：

---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/。

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

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

MCP 服务器提供的命令是 Slash Commands 的一种特殊形式，格式固定为 /mcp__服务器名__提示名。MCP（模型上下文协议，Model Context Protocol）服务器能够对外暴露提示词，连接上 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