创建自定义命令

自定义命令的价值不是多记几个参数，而是把你经常复制的提示词固定成 /test、/review、/release-note 这类入口。

优先使用 Markdown 命令文件。它更接近真实写提示词的方式，也更容易放进项目仓库让团队一起维护。JSON 配置适合少量集中式命令，不适合堆一大段提示词。

先理解它解决什么问题

新手最容易把自定义命令理解成“快捷输入命令”。这个理解不够准确。它真正解决的是重复提示词的质量问题：同一件事每次都临时写，范围会飘、输出会飘、遗漏也会变多。把它沉淀成命令后，你每次调用的都是同一个任务边界。

适合做成命令的场景：

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

不适合做成命令的场景：

一次性问题。
还没想清楚边界的复杂需求。
需要模型先探索、再决定流程的开放任务。

命令文件名就是命令名。`test.md` 对应 `/test`，`review-api.md` 对应 `/review-api`。

什么时候放全局

放项目级 .opencode/commands/：

和当前仓库强相关，例如测试、发布、迁移、代码审查。
需要团队共享。
提示词里引用了项目路径、测试命令或目录结构。

放全局 ~/.config/opencode/commands/：

你在所有项目都会用，例如总结 diff、整理提交信息、解释报错。
不依赖某个仓库的目录结构。

参数

命令可以接收参数。最常用的是 $ARGUMENTS，它代表命令后面的整段输入。

---
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`。但教程里不建议一开始就这样设计，参数越多，命令越难记，也越容易误用。

引用上下文

自定义命令可以引用文件和命令输出：

@src/components/Button.tsx：把文件内容带进提示词。
!`npm test` ：把命令输出带进提示词。

这两个能力要克制使用。文件引用适合代码审查、接口检查；命令输出适合测试结果、lint 结果。不要把一堆无关文件塞进命令里，否则会把上下文窗口浪费在噪音上。

JSON 配置什么时候用

如果你希望命令和其他 OpenCode 配置放在同一个 opencode.json，可以使用 command 字段：

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