自定义命令

自定义命令把一段任务提示保存为 TUI 中的 /命令名。它们与内置命令并存，但同名时会覆盖内置命令，命名时应避免无意改变 /init、/undo 等行为。

Markdown 定义

全局目录为 ~/.config/opencode/commands/，项目目录为 .opencode/commands/。文件名决定命令名，例如 review-changes.md 对应 /review-changes。

---
description: Review the requested change
agent: plan
---

Review $ARGUMENTS and explain the affected behavior and verification steps.

frontmatter 保存属性，正文成为模板。未指定 agent 时使用当前角色；本例主动选择 Plan，但具体工具行为仍取决于 Plan 权限和当前批准模式。

JSON 定义

也可在 opencode.json 的 command 对象定义。template 必填，description 在 TUI 显示，agent 与 model 可选：

{
  "command": {
    "review-changes": {
      "template": "Review $ARGUMENTS and summarize actionable findings.",
      "description": "Review a scoped change",
      "agent": "plan"
    }
  }
}

模型覆盖必须使用实际可用 ID，不应沿用官方教程旧示例里的型号作为当前推荐。

参数展开

$ARGUMENTS 表示传入参数。例如 /review-changes src/parser.ts 会把该参数放入模板。需要分别使用参数时，使用 $1、$2、$3 等位置参数。

带空格或结构化内容的参数需要按命令输入方式正确引用。设计模板时明确每个位置参数的含义，避免把文件路径、目录和文本顺序混淆。

文件与 shell 输出

模板中的 @path/to/file 会把文件内容加入提示。shell 输出注入使用感叹号紧接反引号包裹命令，例如：

Recent commits:
!`git log --oneline -10`

Summarize the important changes.

这些 shell 命令会在项目根目录运行，输出成为提示内容。它会执行命令，不是给模型看的静态代码样例；采用共享模板前应检查其中实际运行了什么。

主角色与子任务

agent 指定为子智能体时，默认触发子智能体调用；设 subtask: false 可关闭这种默认行为。

反过来，subtask: true 会强制将该命令作为子智能体调用，即使角色的 mode 是 primary。这有助于把重复任务与主上下文分开，但不应据此推断权限或模型限制被绕过。

创建后用范围小的输入试用，核对参数、上下文、实际角色和结果，再加入日常工作流。