第 2 章 · 02 自定义命令:配置语法与参数机制

第 2 章 · 02 自定义命令:配置语法与参数机制

本节摘要:一条自定义命令就是一个带 frontmatter 的 Markdown 文件。本节讲透语法:frontmatter 字段(name/description/argument-hint/allowed-tools/model/disable-model-invocation/user-invocable/context/agent/hooks)、参数机制($ARGUMENTS 取全部参数,$0/$1 取单个参数)、动态上下文注入(!`cmd` 执行 shell 并把输出拼进提示词)、文件引用(@path/to/file 注入文件内容)。配一个完整的 commit 命令示例,并说明副作用命令的安全写法。

学习目标

阅读完本节,你应当能够:

1. 写出 frontmatter 全部常用字段及其含义。
2. 解释 $ARGUMENTS 与 $0/$1 的区别,给出 /review-pr 456 high 的取值结果。
3. 用 !`cmd` 注入动态上下文并解释其价值。
4. 说出 disable-model-invocation: true 的适用场景。

一、frontmatter 字段

---
name: my-command            # 命令名(变 /name);默认取目录名
description: 作用与触发时机    # 默认取第一段
argument-hint: [可选参数]     # 自动补全提示
allowed-tools: Bash(git *)  # 免权限工具白名单
model:                      # 指定模型
disable-model-invocation: true  # true 时仅用户可调用
user-invocable: false       # false 时不出现在 / 菜单
context: fork               # 在隔离 subagent 中运行
agent: general-purpose      # context: fork 时的 agent 类型
hooks:                      # skill 级 hooks
---
​

要点:name+description 是必填(name 缺省时用文件名);allowed-tools 声明执行本命令所需的免权限工具(如 Bash(git *)),避免每个动作都弹权限确认;context: fork 让命令在隔离 subagent 中运行(适合需要独立上下文的场景)。

二、参数机制

• $ARGUMENTS:全部参数(/fix-issue 123 → 123);
• $0/$1:单个参数(/review-pr 456 high → $0="456", $1="high");
• argument-hint 提供自动补全提示(如 [message])。

三、动态上下文注入(原书核心技巧)

---
name: commit
description: 使用上下文创建 git commit
allowed-tools: Bash(git *)
---
## 上下文
- 当前 git 状态:!`git status`
- 当前 diff:!`git diff HEAD`
- 当前分支:!`git branch --show-current`
- 最近提交:!`git log --oneline -5`
​

!`cmd` 会把 shell 命令的输出直接注入提示词——命令因此"看见"仓库的实时状态,而不是假设 Claude 知道当前状态。文件引用:@src/utils/helpers.js 可将文件内容注入 prompt(比复制粘贴更可靠)。

四、安全写法:副作用命令

像 deploy 这类有副作用的命令,用 disable-model-invocation: true 使其仅用户可调用——模型不会在自主执行中意外触发它们。

小结

命令 = frontmatter(声明)+ 正文(指令)。参数机制让它可复用,动态注入让它有上下文感知,allowed-tools 与 disable-model-invocation 让它安全。下一节看八个生产级示例如何综合运用这些语法。