使用 Commands

Command 不是另一套扩展系统，而是 Claude Code 会话里的入口层。它可以打开 CLI 内置功能，也可以调用 Skill，还可以触发 MCP server 暴露的 prompt。先分清背后是哪一类能力，才知道该去哪里配置。——翔宇

这一章用 12 分钟换什么：前面已经讲完 Skills、Subagents、Hooks。现在把 / 命令体系收口。读完你应该能判断一个命令是 CLI 内置逻辑、官方 bundled skill、自定义 Skill，还是 MCP prompt，并知道常用命令该怎么归类、怎么传参、怎么排障。

1. Command 解决什么问题

Claude Code 的 slash command 是会话内控制入口。

它负责：

切模型、调 effort、看用量。
管理权限、MCP、记忆、Hooks、Plugins。
清理、压缩、恢复上下文。
打开 diff、状态、配置、诊断面板。
运行官方 bundled skills。
运行你写的 Skills。
运行 MCP server 暴露的 prompts。
启动 web / remote / schedule / review 等工作流。

基础规则：

输入 / 可以看到当前可用命令。
输入 / 后继续打字可以过滤。
命令只在消息开头识别。
命令后的文本会作为参数传入。
可用命令取决于平台、计划、登录状态、版本、配置和环境变量。

第一性原理：/command 是入口，不一定是同一种实现。排障时先判断它背后是 built-in、bundled skill、自定义 Skill，还是 MCP prompt。

flowchart TD
    Slash["用户输入 /command"]
    BuiltIn["Built-in command"]
    Bundled["Bundled skill"]
    Custom["Custom Skill command"]
    Legacy["Legacy custom command"]
    MCP["MCP prompt"]

    CLI["Claude Code CLI 固定逻辑"]
    Skill["Skill 机制"]
    CommandFile[".claude/commands/*.md"]
    MCPServer["MCP server 暴露 prompt"]

    Slash --> BuiltIn
    Slash --> Bundled
    Slash --> Custom
    Slash --> Legacy
    Slash --> MCP
    BuiltIn --> CLI
    Bundled --> Skill
    Custom --> Skill
    Legacy --> CommandFile
    MCP --> MCPServer

    style BuiltIn fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Bundled fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style MCP fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

2. 四类命令入口

第一类：Built-in commands。

这些命令行为由 Claude Code CLI 实现。例如：

/help
/clear
/compact
/config
/model
/permissions
/mcp
/memory
/hooks
/plugin
/status

它们通常打开界面、修改会话状态、管理配置或调用固定功能。

第二类：Bundled skills。

官方文档把带 Skill 标记的命令称为 bundled skills。它们和你自己写的 Skill 用同一套机制：本质是一个 prompt handed to Claude。典型例子包括：

/debug
/simplify
/batch
/loop
/claude-api
/fewer-permission-prompts

第三类：Custom Skill commands。

你在 .claude/skills/<name>/SKILL.md 里写 Skill，就会得到：

/<name>

第四类：MCP prompts。

MCP server 可以暴露 prompts，Claude Code 会把它们显示成：

/mcp__<server>__<prompt>

判断背后机制：管理状态多半是 built-in；执行流程多半是 Skill；连接外部系统的 prompt 多半来自 MCP。

3. Built-in command 和 bundled skill 的区别

Built-in command：

行为写在 Claude Code CLI 里。
通常直接改变会话、配置、权限、模型或 UI。
不依赖 Claude 自己理解一段 prompt 后执行。
典型例子：/model、/compact、/permissions、/mcp。

Bundled skill：

是官方内置 Skill。
给 Claude 一段详细流程，让 Claude 按任务执行。
可以像普通 Skill 一样被 Claude 在相关场景自动调用。
典型例子：/debug、/simplify、/batch、/loop。

这解释了一个常见差异：

/compact 会直接触发上下文压缩。
/debug 会让 Claude 启动调试工作流，读取日志、分析问题、给出处理建议。

不要把 bundled skill 当固定按钮：它仍然经过 Claude 的理解和执行。高风险动作仍要看 permissions、Hooks 和人工确认。

4. 命令参数怎么传

官方约定：

<arg> 表示必填参数。
[arg] 表示可选参数。
命令后的文本会作为参数传给命令。

例子：

/compact focus on the migration plan and unresolved test failures

/plan fix the authentication redirect bug

/batch migrate src/ from Solid to React

/debug the MCP server disconnects after OAuth

对 Skill command 来说，这些参数会进入 $ARGUMENTS。如果 Skill 声明了命名参数，也可以用 $0 或 $name 读取。

参数要像任务 brief：不要只写 /debug，能补一句现象、范围、错误文本，就补一句。

5. 命令可用性不是固定的

不是所有命令每个人都能看到。

官方说明可用性取决于：

Claude Code 版本。
平台：macOS、Windows、Linux、WSL、Web、Desktop。
登录方式和订阅计划。
是否启用 Claude Code on the web。
是否安装 gh CLI。
是否在 git repo 中。
是否设置 Bedrock / Vertex 环境变量。
是否启用 Remote Control、Plugins、Agent teams、sandbox 等功能。

例子：

/desktop 只在 macOS 和 Windows 场景出现。
/setup-bedrock 依赖 Bedrock 环境。
/setup-vertex 依赖 Vertex 环境。
/autofix-pr 依赖 gh CLI 和 Claude Code on the web 权限。
/sandbox 取决于平台和 sandbox 支持。

不要写死“所有人都有这个命令”：教程里可以讲命令类型和用途，实际可用列表以你当前 / 菜单和官方 Commands 页面为准。

6. 上下文管理类命令

这类命令控制当前会话的上下文。

/clear：开始一个空上下文的新对话。旧会话仍可在 /resume 找回。
/compact [instructions]：压缩当前对话，保留摘要继续工作。
/context：可视化当前上下文使用情况，并提示优化方向。
/resume [session]：恢复历史会话。
/branch [name]：从当前点创建会话分支。/fork 默认是 alias，但在 forked subagent 环境变量开启时含义不同。
/rewind：回到之前的对话或代码 checkpoint。
/btw <question>：问一个 side question，不加入主会话历史。

什么时候用：

上下文太重：先 /context，再 /compact。
想干净开始：用 /clear。
想回到旧会话：用 /resume。
想旁路问小问题：用 /btw。

/clear 和 /compact 不同：前者开新上下文，后者压缩当前上下文继续干同一件事。

7. 配置和权限类命令

这类命令管 Claude Code 的行为边界。

/config 或 /settings：打开设置界面，管理主题、模型、输出风格等。
/permissions 或 /allowed-tools：管理 allow、ask、deny 权限规则。
/mcp：管理 MCP 连接和 OAuth 认证。
/memory：查看和编辑 CLAUDE.md、CLAUDE.local.md、rules、auto memory。
/hooks：查看 Hook 配置。
/plugin：管理 Plugins。
/skills：列出可用 Skills，并可按 token count 排序。
/agents：管理 Subagents。
/sandbox：切换 sandbox mode，取决于平台支持。

这些命令是“看当前真实状态”的入口。排障时不要只看文件，先用命令确认当前 session 看到什么。

排障顺序：权限问题看 /permissions，MCP 问题看 /mcp，记忆问题看 /memory，Hook 问题看 /hooks，Skill 问题看 /skills。

8. 模型、用量和状态类命令

这类命令影响运行成本、速度和可观察性。

/model [model]：选择或切换模型。
/effort [level|auto]：设置 reasoning effort。
/fast [on|off]：切换 fast mode。
/usage：查看 cost、plan usage limits 和 activity stats。
/cost：/usage alias。
/stats：/usage alias，打开 Stats tab。
/status：查看版本、模型、账号、连接状态。
/doctor：诊断安装和设置。
/release-notes：查看 changelog。

什么时候用：

回答变慢或成本异常：/usage、/context。
模型不对：/model。
推理深度不合适：/effort。
安装或登录异常：/doctor。

模型切换会重新读取历史：有历史输出的会话里切模型，Claude Code 会提示确认，因为下一轮需要重新读完整历史。

9. 代码工作流类命令

这类命令围绕 git、diff、review、修复和分支。

/diff：打开交互式 diff viewer，看未提交变更和每轮 diff。
/review [PR]：在本地当前会话 review PR。
/security-review：分析当前分支 pending changes 的安全风险。
/autofix-pr [prompt]：启动 Claude Code on the web session，跟踪 PR 里的 CI 和 review comment 修复。
/ultrareview [PR]：在 cloud sandbox 做更深的 multi-agent review。
/ultraplan <prompt>：在 cloud session 草拟 plan，再执行或带回本地。
/batch <instruction>：官方 bundled skill，大规模并行改代码。
/simplify [focus]：官方 bundled skill，审查近期改动并修复可复用性、质量和效率问题。

边界：

本地小 review：/review 或 /security-review。
大范围批量迁移：/batch。
需要 cloud/web session：/autofix-pr、/ultraplan、/ultrareview。

批量和 cloud 命令要先看工作区状态：运行前先确认 git clean / 当前分支 / PR 目标，避免把未准备好的变更交给远端 workflow。

10. 自动化和长期任务类命令

这类命令让 Claude Code 持续或定时工作。

/loop [interval] [prompt]：官方 bundled skill。让 prompt 按间隔重复运行；不写 interval 时 Claude 自行节奏。
/schedule [description]：创建、更新、列出或运行 routines。
/tasks：列出和管理后台任务，也可用 /bashes。
/remote-control：让当前 session 可从 claude.ai remote control。
/remote-env：配置 web sessions 的默认 remote environment。

使用建议：

需要周期检查：/loop。
需要真正定时 routine：/schedule。
已经有后台任务：/tasks。
需要手机或网页接管本地会话：/remote-control。

长期自动化要更窄：prompt、权限、工作目录、分支、输出和通知都要收紧，不要把模糊任务放进循环。

11. 平台和集成类命令

这类命令连接外部入口。

/desktop 或 /app：把当前 session 继续到 Claude Code Desktop。
/ide：管理 IDE integration。
/chrome：配置 Claude in Chrome。
/mobile、/ios、/android：显示移动端二维码。
/install-github-app：设置 Claude GitHub Actions app。
/install-slack-app：安装 Claude Slack app。
/web-setup：用本地 gh CLI credentials 连接 Claude Code on the web。
/teleport 或 /tp：把 web session 拉回 terminal。

这些命令可用性高度依赖平台、登录状态和账号权限。

平台命令先看当前入口：你在纯终端、Desktop、Web、Remote Control、IDE 里的可用命令不完全一样。

12. 创建项目和团队交接类命令

这类命令帮助你启动或总结工作。

/init：初始化项目 CLAUDE.md。设置 CLAUDE_CODE_NEW_INIT=1 后，会进入更交互的初始化流程，覆盖 CLAUDE.md、Skills、Hooks、personal memory 等 artifact。
/team-onboarding：根据过去一段 Claude Code 使用历史生成团队 onboarding guide。
/insights：生成 session 使用报告，分析项目区域、交互模式和摩擦点。
/recap：生成当前 session 的一行 summary。
/export [filename]：导出当前会话。

/init 只是起点：生成的 CLAUDE.md 要人工审查，删噪音、补隐性团队规则，再提交。

13. 自定义命令：优先写 Skill

官方已经把 custom commands 合并进 Skills。

推荐路径：

.claude/skills/<name>/SKILL.md

示例：

.claude/skills/review-diff/SKILL.md

调用：

/review-diff

最小 Skill：

---
description: Reviews the current git diff for correctness, security risks, missing tests, and unclear error handling.
---

Review the current diff.

!`git diff HEAD`

Return:

- Findings ordered by severity
- Test gaps
- Suggested next commands

旧格式仍可用：

.claude/commands/<name>.md

但新写内容优先 Skill，因为 Skill 支持：

目录结构。
附属文件。
frontmatter。
自动加载。
disable-model-invocation。
allowed-tools。
context: fork。

不要再新建 legacy commands：除非你在维护旧仓库。新命令统一做 Skill。

14. MCP prompts：外部系统暴露命令

MCP server 可以暴露 prompts。Claude Code 会把它们显示成 command：

/mcp__<server>__<prompt>

例如：

/mcp__github__list_prs

/mcp__linear__triage_issue ENG-123

适合：

外部系统里的固定 workflow。
从 issue tracker 拉任务。
从内部 docs 做查询。
基于数据库 schema 生成分析任务。
调用内部平台暴露的 prompt。

边界：

MCP prompt 来自 server，不来自本地 .claude/skills/。
server 断开或未认证时，对应 command 可能不可用。
prompt 结果会进入当前对话。
外部系统 prompt 同样要考虑权限和 prompt injection。

MCP prompt 是入口，MCP tool 是能力：prompt 可以组织任务，但真正能读写什么仍取决于 MCP server tools、OAuth scope 和 Claude Code permissions。

15. UserPromptExpansion Hook 和命令展开

官方 Hooks reference 里有 UserPromptExpansion。它会在 slash command、custom command、Skill command 或 MCP prompt 展开后触发。

它可以看到 expansion 类型，例如：

slash_command
mcp_prompt

适合：

记录哪些命令被展开。
审计 high-risk command 使用。
对某些命令展开内容做额外检查。

不适合：

替代 command 本身。
自动批准高风险外部操作。
记录完整 prompt 或敏感参数到外部系统。

命令展开可能包含用户输入和外部内容：审计时只记录必要元信息，不要默认保存完整正文。

16. 常用命令速查

上下文：

/context：看上下文占用。
/compact：压缩当前会话。
/clear：开新上下文。
/resume：恢复历史会话。
/btw：不污染主历史的小问题。

配置：

/config：打开设置。
/permissions：管理工具权限。
/mcp：管理 MCP。
/memory：管理记忆。
/hooks：查看 hooks。
/plugin：管理 plugins。
/skills：查看 skills。
/agents：管理 subagents。

代码：

/diff：看 diff。
/review：本地 PR review。
/security-review：安全审查。
/simplify：官方 Skill，简化和修复近期改动。
/batch：官方 Skill，大范围并行修改。

运行状态：

/model：切模型。
/effort：调 reasoning effort。
/usage：看用量。
/status：看版本、账号、连接状态。
/doctor：诊断环境。

自动化：

/loop：重复运行 prompt。
/schedule：管理 routines。
/tasks：管理后台任务。

记不住命令时输入 /：实时菜单比静态教程更可靠，因为它反映你当前版本和环境。

17. 什么时候不要做 command

不要把这些做成 command：

每次会话都要知道的规则：写 CLAUDE.md 或 .claude/rules/。
必须自动执行的动作：写 Hook。
外部工具连接：接 MCP。
只用一次的提示词：直接对话。
需要用户多轮决策的复杂流程：先在普通对话里跑顺，再沉淀成 Skill。
生产发布这类高风险动作：可以有 command，但必须配 permissions、确认和回滚流程。

Command 不是规则容器：它是入口。长期规则、自动化、权限和外部连接要放到各自正确层。

18. 常见故障：命令看不到

按这个顺序查：

输入 / 看当前菜单。
确认 Claude Code 版本是否支持该命令。
确认平台和账号计划。
确认是否需要特定环境变量。
如果是 Skill command，运行 /skills 看是否被加载。
如果是 MCP prompt，运行 /mcp 看 server 是否 connected / authenticated。
如果是 plugin command，运行 /plugin 或 /reload-plugins。
如果是 legacy command，确认 .claude/commands/<name>.md 路径存在。

先分类型再排障：built-in 查版本和环境；Skill 查 /skills；MCP prompt 查 /mcp；plugin 查 /plugin。

19. 常见故障：命令没有按预期执行

常见原因：

命令不在消息开头。
参数太少，Claude 不知道范围。
Bundled skill 依赖模型判断，不是固定脚本。
自定义 Skill description 太泛或正文不具体。
MCP server 认证过期。
permissions 阻止了后续工具调用。
Hook 阻断了命令触发的工具调用。
上下文太重，Skill 内容被压缩后丢失关键部分。

处理：

把命令放在消息第一行。
参数写成具体任务 brief。
对自定义 Skill 明确输入、步骤、输出、验证。
用 /permissions 看是否被 ask / deny。
用 /hooks 看是否有阻断。
用 /debug 排查 Claude Code session 行为。

命令只是开始：命令之后仍然会进入工具调用、权限、Hooks、上下文这些系统。问题不一定在命令本身。

20. 一个项目的推荐命令沉淀方式

先不要为了“有工具感”创建一堆 slash commands。推荐顺序：

先在普通对话里跑通流程。
第二次重复时，整理成 checklist。
第三次重复时，写成 .claude/skills/<name>/SKILL.md。
如果流程有副作用，加 disable-model-invocation: true。
如果需要工具，写 allowed-tools，但安全拒绝仍放 permissions。
如果流程需要外部系统，接 MCP。
如果必须每次发生，写 Hook。
如果多个仓库复用，再打包 Plugin。

命令是沉淀出来的，不是预设出来的：真实重复出现的流程，才值得变成 /name。

21. 自检清单

学完这一章，你应该能做到：

我能解释 built-in command 和 bundled skill 的区别。
我知道 custom commands 推荐用 Skills 实现。
我知道 legacy .claude/commands/ 仍可用，但新内容优先 .claude/skills/。
我知道 MCP prompts 会显示为 /mcp__server__prompt。
我知道命令只在消息开头识别。
我知道命令可用性受平台、计划、版本、环境影响。
我知道 /clear 和 /compact 的区别。
我知道权限、MCP、记忆、Hooks、Skills、Subagents 分别用哪个命令排查。
我知道高风险流程不能只靠 command，要配 permissions 和确认。
我知道命令不是长期规则、自动化或外部连接的替代品。

22. 术语速查

Slash command：会话中以 / 开头的命令入口。
Built-in command：Claude Code CLI 实现的固定命令。
Bundled skill：官方随 Claude Code 提供的 Skill command。
Custom Skill command：由 .claude/skills/<name>/SKILL.md 生成的 /name。
Legacy custom command：由 .claude/commands/<name>.md 生成的旧式 command。
MCP prompt：MCP server 暴露成 slash command 的 prompt。
/compact：压缩当前上下文。
/clear：清空上下文并开始新对话。
/permissions：管理 allow / ask / deny 权限规则。
/mcp：查看 MCP server 和 OAuth 状态。
/memory：查看和编辑记忆文件与 auto memory。
/hooks：查看 Hook 配置。
/skills：列出可用 Skills。
/agents：管理 Subagents。
UserPromptExpansion：slash command 或 MCP prompt 展开后的 Hook 事件。