创建自定义命令

Custom commands 让你把重复提示词做成 TUI 里的 /xxx 入口。它不是为了少打几个字，而是把任务边界、执行 agent、模型选择、参数和输出结构固定下来。

这一篇用 10 分钟换什么：你会知道什么时候该写 command、Markdown 和 JSON 两种方式怎么选、$ARGUMENTS / $1 怎么用、! 和 @ 怎么注入上下文，以及为什么不要随便覆盖内置命令。

先判断该不该沉淀成 command

一条提示词至少反复用过几次，再考虑写成 command。

flowchart LR
    Prompt["一次性提示词"] --> Repeat{"同类流程反复出现?"}
    Repeat -->|否| Keep["继续在对话里写"]
    Repeat -->|是| Stable{"边界和输出稳定?"}
    Stable -->|否| Improve["先打磨提示词"]
    Stable -->|是| Command["写成 /command"]
    Command --> Share{"团队也需要?"}
    Share -->|是| Project["放 .opencode/commands/"]
    Share -->|否| Global["放 ~/.config/opencode/commands/"]

    style Command fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Project fill:#dcfce7,stroke:#22c55e

适合做成 command：

每周都会做的固定动作，例如测试、审查、生成发布说明。
需要稳定输出结构的动作，例如“先列风险，再给改法，再列测试”。
团队希望统一做法的动作，例如 PR 自检、迁移检查、文档审查。

不适合：一次性问题、边界还没想清楚的复杂需求、开放式探索任务、已经有内置命令覆盖的动作。

1. Markdown command 推荐起步

项目级命令放在 .opencode/commands/。例如：

.opencode/commands/test.md

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report.
If anything fails, identify the failing case, likely cause, and smallest next fix.

文件名就是命令名。test.md 对应：

/test

Markdown 文件更适合长 prompt，因为它容易阅读、review、版本化。项目命令可以提交到 Git，让团队使用同一套任务入口。

2. 全局和项目级怎么选

位置	适合什么
`.opencode/commands/`	当前仓库的测试、发布、迁移、PR 审查、文档检查
`~/.config/opencode/commands/`	个人跨项目通用命令，例如总结 diff、解释报错、整理提交信息

默认从项目级开始。只要 prompt 里引用了项目路径、测试命令、目录结构或团队规则，就不要放进全局。

3. JSON command 适合短命令

也可以在 opencode.json / opencode.jsonc 里用 command 配置。

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "review": {
      "template": "Review the current git diff. Focus on bugs, regressions, security, and missing tests.",
      "description": "Review current changes",
      "agent": "plan"
    }
  }
}

template 是必填项，description 会显示在 TUI 命令列表里。JSON 适合一两个短命令；长提示词、步骤和示例更适合 Markdown 文件。

4. 参数怎么用

$ARGUMENTS 代表命令后面的整段输入。

.opencode/commands/component.md

---
description: Create a component plan
---

Create an implementation plan for $ARGUMENTS.
Include files to touch, edge cases, and tests.

运行：

/component Button

这里 $ARGUMENTS 会变成 Button。

也可以使用位置参数：$1、$2、$3。但位置参数越多，命令越像脚本，越容易误用。新手优先用 $ARGUMENTS。

5. 注入 shell 输出和文件

Command prompt 可以使用 ! 注入 shell 输出，也可以用 @ 引用文件。

.opencode/commands/review-diff.md

---
description: Review current diff
---

Current changes:
!`git diff --stat`
!`git diff`

Review only. Do not modify files.

文件引用示例：

Review @src/components/Button.tsx for performance and accessibility issues.

! 会执行命令并把输出放进 prompt。只读命令适合，删除、发布、数据库写操作和修改全局环境的命令不适合写进 command。

6. agent、subtask 和 model

Command 可以指定执行它的 agent 和 model。

几个边界要记住：

agent 可选；不指定时使用当前 agent。
如果 agent 是 subagent，官方文档说明 command 默认会触发 subagent invocation。
如果不想让 subagent 默认执行，可以设置 subtask: false。
subtask: true 可以强制让命令作为 subagent 运行，避免污染主会话上下文。
model 可以覆盖当前默认模型，但只在确实需要特殊模型时配置，不要每个 command 都硬绑模型。

7. 不要覆盖内置命令

OpenCode 已有 /init、/undo、/redo、/share、/help 等内置命令。官方文档说明 custom commands 可以覆盖内置命令。

除非你明确知道后果，否则不要创建 init.md、undo.md、share.md 这类同名 command。要改变安全边界，用 config 和 permission；不要靠覆盖内置命令制造隐性行为。

8. 怎么判断写对了

一个可交付的 command 应该满足：

名字短，一眼能看懂。
一个 command 只做一类任务。
输出结构稳定，不需要每次再补说明。
参数少，最好先用 $ARGUMENTS。
shell 注入只用只读命令。
项目级命令可 review、可删除、可追踪影响范围。

如果每次运行还要补一大段解释，说明 command 没有把任务边界写清楚。

接下来去哪

配置

理解 command 应该放在项目配置、Markdown 文件还是全局配置。

Rules

长期约束写进 rules，重复流程写成 command，不要混用。

Agents

当 command 需要固定角色、模型或权限时，再考虑自定义 agent。

TUI

Command 最终在 TUI 里使用，先理解 `/` 命令和快捷键。

官方资料

OpenCode Commands：https://opencode.ai/docs/commands
OpenCode TUI Commands：https://opencode.ai/docs/tui#commands
OpenCode Config：https://opencode.ai/docs/config
OpenCode Agents：https://opencode.ai/docs/agents

创建自定义命令

配置

Rules

Agents

TUI

本页目录