Claude Code 深度学习手册

主题

Slash Commands（斜杠命令） ​

在 Claude Code 中用 / 触发的命令；自定义命令已合并进 Skills，由 SKILL.md（或旧的 .claude/commands/*.md）定义，可由你手动触发或让 Claude 自动加载。

你的真实情况 ​

官方已把"自定义斜杠命令"并进 Skills（详见 Skills 一节）——你 ~/.claude/skills/ 里每个就对应一个 /命令，插件技能带前缀（/code-review、/commit）。所以"自定义命令"对你来说 = 写 SKILL.md。

这一节专讲内置斜杠命令（不是技能、Claude Code 自带的），下面「内置命令大全」节列全；你最常用的几个：/context、/cost、/memory、/permissions、/agents、/mcp、/plugin、/doctor、/compact、/rewind、/config。

去真实体验 ​

  • 输入 / 看自动补全列表（你的 ~50 技能 + 插件命令 + 内置命令都在）。
  • 自定义一个：/skill-creator 或手写 ~/.claude/skills/<name>/SKILL.md。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

官方文档 https://code.claude.com/docs/en/slash-commands 现已重定向到「Extend Claude with skills」页面，因为 Custom commands have been merged into skills（自定义斜杠命令已合并进 Skills）。一个 .claude/commands/deploy.md 文件和一个 .claude/skills/deploy/SKILL.md 都会创建 /deploy，二者行为一致；已有的 .claude/commands/ 文件继续可用。Skills 在此基础上增加了：支持文件目录、控制由你还是 Claude 调用的 frontmatter、以及 Claude 在相关时自动加载的能力。Skills 遵循 Agent Skills 开放标准（agentskills.io），Claude Code 在其上扩展了 invocation control、subagent execution、dynamic context injection。built-in commands（如 /help、/compact）和 bundled skills（如 /code-review、/batch、/debug、/loop、/claude-api）见 /en/commands 参考页。

怎么工作 ​

  • 命令名来自文件位置：.claude/skills/<dir>/SKILL.md 的命令名取自目录名（如 deploy-staging → /deploy-staging）；.claude/commands/x.md 取自去扩展名的文件名（→ /x）。frontmatter 的 name 字段只是列表里的显示标签，不改变你输入的 / 命令名（plugin 根 SKILL.md 是唯一例外）。
  • 常规会话里只把 skill 的 description 注入上下文供 Claude 判断何时使用；完整 SKILL.md 内容仅在被调用时才加载（subagent preload 例外，启动即注入完整内容）。
  • 调用后 rendered SKILL.md 作为一条 message 进入对话并在整个 session 中保留，Claude Code 不会在后续轮次重新读取该文件——所以要把贯穿任务的指引写成 standing instructions。
  • Auto-compaction 时按 token 预算把已调用 skill 带过摘要：每个 skill 保留前 5,000 tokens，所有重新附加的 skill 共享 25,000 tokens 预算，从最近调用的开始填，旧的可能被整个丢弃。
  • 参数替换在内容里展开：$ARGUMENTS=全部参数原样；$ARGUMENTS[N] / $N=按 0 基下标取单个参数（shell 风格引号，多词要加引号）；若 skill 不含 $ARGUMENTS 但你传了参数，会在内容末尾追加 ARGUMENTS: <你的输入>。
  • 动态上下文注入：!`<command>` 在发给 Claude 之前先执行 shell 命令，用输出替换占位符（preprocessing，不是 Claude 执行）。只替换一次，输出不会被再次扫描；! 只在行首或紧跟空白时识别，KEY=!\cmd`这种会被当字面文本。多行命令用 ```! ` 围栏代码块。
  • context: fork 让 skill 在 forked subagent 里隔离运行：SKILL.md 内容成为 subagent 的 prompt，不带主对话历史；agent 字段决定执行环境（model/tools/permissions），省略则用 general-purpose。
  • skill 描述列表有字符预算：预算按模型 context window 的 1% 缩放，溢出时优先丢弃你最少调用的 skill 的描述；每条 description+when_to_use 合并文本上限 1,536 字符。
  • Live change detection：Claude Code 监听 skill 目录，在 ~/.claude/skills/、项目 .claude/skills/、--add-dir 目录下的 .claude/skills/ 增删改会在当前 session 内即时生效；但新建一个 session 启动时不存在的顶层 skills 目录需要重启。

怎么配置 / 用法 ​

文件位置（按优先级 enterprise > personal > project，plugin 用 plugin-name:skill-name 命名空间不冲突）：Personal=~/.claude/skills/<skill-name>/SKILL.md（所有项目可用）；Project=.claude/skills/<skill-name>/SKILL.md（仅本项目，提交进 VCS 共享）；Plugin=<plugin>/skills/<skill-name>/SKILL.md；旧式 Custom command=.claude/commands/<name>.md。SKILL.md 结构：--- 之间是 YAML frontmatter（所有字段可选，仅推荐写 description），其后是 markdown 指令。最小例：---\ndescription: ...\n---\n## Instructions\n...。动态注入例：!git diff HEAD``。参数例：Fix GitHub issue $ARGUMENTS 配 /fix-issue 123。fork 例：frontmatter 加 context: fork 和 agent: Explore。权限预批准：allowed-tools: Bash(git add *) Bash(git commit *)。禁止 Claude 自动调用：disable-model-invocation: true。从 / 菜单隐藏：user-invocable: false。设置文件层面覆盖可见性用 .claude/settings.local.json 的 skillOverrides（/skills 菜单里 Space 切换、Enter 保存）。

什么时候用 ​

  • 当你反复把同一套指令/检查清单/多步流程粘贴进对话，或 CLAUDE.md 里某段已经长成了一套流程（procedure）而不是事实（fact）时——做成 skill；它的正文只在被用到时才加载，长参考材料平时几乎零成本。
  • Task content（部署、提交、代码生成等有副作用、需你掌控时机的动作）：用 disable-model-invocation: true 做成只你能 /name 手动触发的命令，比如 /commit、/deploy、/send-slack-message。
  • Reference content（约定、风格指南、领域知识）：让 Claude 在相关时自动加载、内联应用；只供 Claude 用、用户不该直接触发的背景知识用 user-invocable: false。
  • 需要让命令拿到实时数据时用 !`<command>` 注入（如 git diff、gh pr diff），而不是让 Claude 自己去跑。
  • 需要隔离/不污染主上下文的探索或研究任务用 context: fork（搭配 agent: Explore/Plan）。
  • 别用 fork 的场景：skill 只是「用这些 API 约定」这类没有明确任务的 guideline——subagent 拿到指引却没有可执行 prompt，会空转返回。

限制 / 坑 ​

  • slash-commands 页面已合并/重定向到 skills 页面：自定义命令本身不再是独立概念，而是 skills 的一种形态。
  • skill 调用后内容常驻整个 session、不重读文件，每行都是 recurring token 成本；正文建议 <500 行，详细参考材料拆到单独文件。
  • compaction 后旧 skill 可能被整个丢弃（25,000 tokens 共享预算，每个保留前 5,000 tokens，从最近的开始填）；若失效可在 compaction 后重新调用。
  • description+when_to_use 合并文本被截断在 1,536 字符（用 maxSkillDescriptionChars 可配）；skill 多时描述会因预算被缩短甚至丢关键词，用 /doctor 查是否溢出。
  • ! 仅在行首或紧跟空白时触发命令注入；紧跟其他字符（如 KEY=!\cmd``）会被当字面文本不执行。命令注入只跑一次，输出不会被二次扫描展开新的占位符。
  • user-invocable: false 只控制 / 菜单可见性，不阻止 Skill tool 编程调用；要彻底屏蔽 Claude 调用须用 disable-model-invocation: true。
  • context: fork 用 Explore/Plan agent 时会跳过 CLAUDE.md 和 git status；普通 fork 会加载 CLAUDE.md。
  • --add-dir / /add-dir 是文件访问授权而非配置发现，但 .claude/skills/ 是例外会自动加载；permissions.additionalDirectories 设置只给文件访问、不加载 skills；subagents/commands/output styles 都不从附加目录加载。
  • plugin skills 不受 skillOverrides 影响，需通过 /plugin 管理。
  • disableSkillShellExecution: true 会把每个命令替换为 [shell command execution disabled by policy]；bundled 和 managed skills 不受影响。

硬事实速查（21 条） ​

  • 官方文档 https://code.claude.com/docs/en/slash-commands 现重定向到 skills 页（标题 Extend Claude with skills）。原文：Custom commands have been merged into skills。
  • 路径：Personal ~/.claude/skills/<skill-name>/SKILL.md；Project .claude/skills/<skill-name>/SKILL.md；Plugin <plugin>/skills/<skill-name>/SKILL.md；旧式 .claude/commands/<name>.md。
  • 优先级：enterprise 覆盖 personal，personal 覆盖 project；plugin 用 plugin-name:skill-name 命名空间；同名时 skill 优先于 command。
  • 命令名来源：skills 目录名（.claude/skills/deploy-staging → /deploy-staging）；commands 去扩展名文件名（.claude/commands/deploy.md → /deploy）；plugin skills/ 子目录用目录名并加 plugin 前缀（my-plugin/skills/review → /my-plugin:review）；plugin 根 SKILL.md 用 frontmatter name、缺省回退到 plugin 目录名。
  • frontmatter 字段：name、description（recommended）、when_to_use、argument-hint、arguments、disable-model-invocation（默认 false）、user-invocable（默认 true）、allowed-tools、disallowed-tools、model、effort、context、agent、hooks、paths、shell。
  • effort 选项：low / medium / high / xhigh / max（按模型可用）。
  • shell 字段：bash（默认）或 powershell；powershell 需 CLAUDE_CODE_USE_POWERSHELL_TOOL=1。
  • 字符串替换变量：$ARGUMENTS、$ARGUMENTS[N]、$N（$0 为第一个）、$name（来自 arguments 列表，按顺序映射）、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT}（low/medium/high/xhigh/max；ultracode 不是独立等级、上报为 xhigh）、${CLAUDE_SKILL_DIR}（SKILL.md 所在目录）。
  • 动态注入：行内 !`<command>`；多行用 ```! 围栏块；在发给 Claude 前执行、输出替换占位符。
  • description+when_to_use 合并文本在 skill 列表中截断于 1,536 characters；可用 maxSkillDescriptionChars 配置。
  • skill 列表预算默认为模型 context window 的 1%，用 skillListingBudgetFraction（如 0.02=2%）或环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET（固定字符数）调整；用 /doctor 查溢出。
  • compaction：每个重新附加 skill 保留前 5,000 tokens；所有重新附加 skill 共享 25,000 tokens 预算。
  • 建议 SKILL.md 保持 < 500 lines。
  • context: fork 用 agent 字段选 subagent：Explore / Plan / general-purpose 或 .claude/agents/ 自定义；省略则 general-purpose；Explore/Plan 会跳过 CLAUDE.md 和 git status。
  • Skill tool 权限：/permissions 里 deny Skill 禁用全部；Skill(name) 精确匹配、Skill(name *) 前缀匹配；少数 built-in 命令可经 Skill tool 调用，含 /init、/review、/security-review，而 /compact 等不可。
  • skillOverrides 四种状态：on（名+描述，菜单可见）、name-only（仅名，菜单可见）、user-invocable-only（对 Claude 隐藏，菜单可见）、off（全隐藏）；缺省视为 on；写入 .claude/settings.local.json。
  • Bundled skills：/code-review、/batch、/debug、/loop、/claude-api；/run、/verify、/run-skill-generator 需 Claude Code v2.1.145 或更高，记录的 per-project skill 存于 .claude/skills/run-<name>/。
  • disableSkillShellExecution: true（settings）禁用 user/project/plugin/additional-directory 来源的 shell 注入；bundled 与 managed skills 不受影响。
  • 附加目录：.claude/skills/ 在 --add-dir//add-dir 目录下会自动加载（例外）；permissions.additionalDirectories 不加载 skills；附加目录 CLAUDE.md 默认不加载，需 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。
  • skill 目录结构：SKILL.md（必需入口）+ 可选 template.md / examples/ / scripts/ 等支持文件。
  • 在 skill 内容任意位置写 ultrathink 可请求更深推理。

官方出处：https://code.claude.com/docs/en/slash-commands