command-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Command Creation for OpenCode

OpenCode 命令创建指南

Create custom slash commands for repetitive tasks that execute specific prompts with dynamic arguments.

为重复任务创建自定义斜杠命令，这些命令可通过动态参数执行特定提示词。

MUST FOLLOW

必须遵守的规则

Commands must only specify
agent
in their frontmatter — never
model
. Model selection is managed at the agent level in

opencode.json

. Adding a

model

field to a command bypasses centralized configuration and creates inconsistency across the project.

Always ask the user which agent should run the command. The

agent:

field is required and must never be omitted. The two primary choices are:

```
build
```
— For commands that create or modify files, run tests, build, or deploy
```
plan
```
— For commands that analyze, review, or read without making changes

yaml

---
description: Brief description
agent: build   # or: plan
---

Do not add

model:

to command frontmatter. To change the model used by a command, configure the target agent's model in

opencode.json

命令的前置元数据中只能指定
agent
——绝对不能指定
model
。模型选择在

opencode.json

的Agent层面统一管理。在命令中添加

model

字段会绕过集中配置，导致项目内配置不一致。

务必询问用户应该由哪个Agent来运行该命令。

agent:

字段是必填项，绝对不能省略。主要有两个选项：

```
build
```
— 用于创建或修改文件、运行测试、构建或部署的命令
```
plan
```
— 用于分析、评审或仅读取内容而不做修改的命令

yaml

---
description: 简短描述
agent: build   # 或: plan
---

不要在命令前置元数据中添加

model:

字段。若要修改命令使用的模型，请在

opencode.json

中配置目标Agent的模型。

What Commands Are

命令是什么

Custom commands let you define reusable prompts that can be triggered with

/command-name

in the OpenCode TUI. They provide:

Repetitive task automation - Common workflows like testing, deployment, code review
Dynamic arguments - Pass parameters to customize command behavior
Shell integration - Include bash command output in prompts
File references - Automatically include file contents
Agent and model selection - Route commands to specific agents or models

Commands execute immediately when invoked, sending the configured prompt to the LLM.

自定义命令允许你定义可复用的提示词，在OpenCode TUI中通过

/command-name

触发。它们具备以下特性：

重复任务自动化 - 测试、部署、代码评审等常见工作流
动态参数 - 传递参数以自定义命令行为
Shell集成 - 在提示词中包含bash命令输出
文件引用 - 自动包含文件内容
Agent与模型选择 - 将命令路由到特定Agent或模型

命令被调用后会立即执行，将配置好的提示词发送给大语言模型（LLM）。

Quick Start

快速开始

Create a command in three steps:

Create command file:

bash

mkdir -p .opencode/commands
touch .opencode/commands/test.md

Add frontmatter and content to

test.md

markdown

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Use the command in TUI:
```
/test
```

That's it! The command will execute the prompt with the configured settings.

通过三步创建命令：

创建命令文件:

bash

mkdir -p .opencode/commands
touch .opencode/commands/test.md

为
test.md
添加前置元数据和内容:

markdown

---
description: 带覆盖率的测试运行
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

运行完整测试套件并生成覆盖率报告，展示所有失败用例。
重点关注失败测试并提出修复建议。

在TUI中使用命令:
```
/test
```

完成！命令会按照配置好的设置执行提示词。

File Locations

文件位置

Create command files in these locations:

Project-local:

```
.opencode/commands/command-name.md
```

Global (user-wide):

~/.config/opencode/commands/command-name.md

Use project-local for repository-specific commands. Use global for general-purpose commands you use across projects.

可在以下位置创建命令文件：

项目本地:

```
.opencode/commands/command-name.md
```

全局（全用户范围）:

~/.config/opencode/commands/command-name.md

项目本地命令用于特定仓库，全局命令适用于跨项目的通用场景。

Creating Commands

创建命令的方法

Method 1: Markdown Files (Recommended)

方法1：Markdown文件（推荐）

Create a markdown file in the

commands/

directory. The filename becomes the command name.

Structure:

.opencode/commands/
├── test.md          # /test command
├── review.md        # /review command
└── component.md     # /component command

Example -

.opencode/commands/review.md

markdown

 
---
description: Review code changes
agent: plan
---

Review recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements.

Frontmatter fields:

```
description
```
- Brief description shown in TUI (optional)
```
agent
```
- Which agent should execute the command (optional)
```
subtask
```
- Force subagent invocation (optional boolean)
~~model~~
- Do not use — model is managed in
```
opencode.json
```
at the agent level

The content after frontmatter becomes the command template.

在

commands/

目录下创建Markdown文件，文件名即为命令名称。

结构:

.opencode/commands/
├── test.md          # /test 命令
├── review.md        # /review 命令
└── component.md     # /component 命令

示例 -

.opencode/commands/review.md

markdown

 
---
description: 评审代码变更
agent: plan
---

评审最近的Git提交：
!`git log --oneline -10`

评审这些变更并提出改进建议。

前置元数据字段:

```
description
```
- 在TUI中显示的简短描述（可选）
```
agent
```
- 执行命令的Agent（必填）
```
subtask
```
- 强制触发子Agent调用（可选布尔值）
~~model~~
- 禁止使用 — 模型在
```
opencode.json
```
的Agent层面统一管理

前置元数据之后的内容即为命令模板。

Method 2: JSON Configuration

方法2：JSON配置

Add commands to

opencode.jsonc

using the

command

option:

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

Use JSON for simple commands or when you want all configuration in one file.

在

opencode.jsonc

中通过

command

选项添加命令：

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "运行测试并报告失败用例。\n重点关注失败测试并提出修复建议。",
      "description": "带覆盖率的测试运行",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

简单命令或希望所有配置集中在一个文件时，可使用JSON方式。

Command Templates

命令模板

Templates support special syntax for dynamic behavior:

模板支持特殊语法以实现动态行为：

1. Arguments with $ARGUMENTS

1. 使用$ARGUMENTS传递参数

Pass arguments to commands using the

$ARGUMENTS

placeholder:

.opencode/commands/component.md

markdown

 
---
description: Create a new component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

Usage:

/component Button

This replaces

$ARGUMENTS

with

Button

通过

$ARGUMENTS

占位符向命令传递参数：

.opencode/commands/component.md

markdown

 
---
description: 创建新组件
---

创建一个名为$ARGUMENTS的React组件，支持TypeScript。
包含正确的类型定义和基础结构。

使用方式:

/component Button

此命令会将

$ARGUMENTS

替换为

Button

。

2. Positional Arguments ($1, $2, $3, ...)

2. 位置参数（$1, $2, $3, ...）

Access individual arguments using positional parameters:

.opencode/commands/create-file.md

markdown

 
---
description: Create a new file with content
---

Create a file named $1 in the directory $2
with the following content: $3

Usage:

/create-file config.json src "{ \"key\": \"value\" }"

This replaces:

```
$1
```
→
```
config.json
```
```
$2
```
→
```
src
```
```
$3
```
→
```
{ "key": "value" }
```

通过位置参数访问单个参数：

.opencode/commands/create-file.md

markdown

 
---
description: 创建带内容的新文件
---

在目录$2中创建名为$1的文件
内容如下：$3

使用方式:

/create-file config.json src "{ \"key\": \"value\" }"

替换规则：

```
$1
```
→
```
config.json
```
```
$2
```
→
```
src
```
```
$3
```
→
```
{ "key": "value" }
```

3. Shell Output with !

command

3. 使用!

command

注入Shell输出

Inject bash command output into prompts using !
command
syntax:

.opencode/commands/analyze-coverage.md

markdown

 
---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

More examples:

markdown

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

Current branch status:
!`git status`

Package versions:
!`npm list --depth=0`

Commands run in your project's root directory and their output is included in the prompt.

通过

command``语法将bash命令的输出注入到提示词中：

.opencode/commands/analyze-coverage.md

markdown

 
---
description: 分析测试覆盖率
---

当前测试结果如下：
!`npm test`

基于这些结果，提出提升覆盖率的改进建议。

更多示例:

markdown

 
最近的提交：
!`git log --oneline -10`

当前分支状态：
!`git status`

包版本：
!`npm list --depth=0`

命令会在项目根目录执行，其输出会被包含在提示词中。

4. File References with @

4. 使用@引用文件

Include file contents using

followed by the filename:

.opencode/commands/review-component.md

markdown

 
---
description: Review component
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

The file content is automatically included in the prompt.

Multiple files:

markdown

 
Compare @src/old-api.ts and @src/new-api.ts.
Identify breaking changes and migration steps.

使用

后跟文件名来包含文件内容：

.opencode/commands/review-component.md

markdown

 
---
description: 评审组件
---

评审@src/components/Button.tsx中的组件。
检查性能问题并提出改进建议。

文件内容会自动包含在提示词中。

多文件引用:

markdown

 
对比@src/old-api.ts和@src/new-api.ts。
识别破坏性变更和迁移步骤。

Configuration Options

配置选项

template (required for JSON)

template（JSON方式必填）

The prompt sent to the LLM when the command executes.

JSON:

json

{
  "command": {
    "test": {
      "template": "Run tests and report failures."
    }
  }
}

Markdown: Content after frontmatter is the template.

命令执行时发送给LLM的提示词。

JSON示例:

json

{
  "command": {
    "test": {
      "template": "运行测试并报告失败用例。"
    }
  }
}

Markdown方式: 前置元数据之后的内容即为模板。

description (optional)

description（可选）

Brief description shown in the TUI when typing the command.

JSON:

json

{
  "command": {
    "test": {
      "description": "Run tests with coverage"
    }
  }
}

Markdown:

yaml

---
description: Run tests with coverage
---

在TUI中输入命令时显示的简短描述。

JSON示例:

json

{
  "command": {
    "test": {
      "description": "带覆盖率的测试运行"
    }
  }
}

Markdown示例:

yaml

---
description: 带覆盖率的测试运行
---

agent (required)

agent（必填）

Specify which agent should execute the command. Always ask the user whether the command should use
build
or
plan
— never leave this field out.

```
build
```
— For tasks that create/modify files, run tests, build, or deploy
```
plan
```
— For analysis, code review, and read-only tasks

JSON:

json

{
  "command": {
    "review": {
      "agent": "plan"
    }
  }
}

Markdown:

yaml

---
agent: plan
---

If the agent is a subagent, the command triggers a subagent invocation by default. Disable with

subtask: false

Default: Current agent if not specified.

指定执行命令的Agent。务必询问用户命令应使用
build
还是
plan
——绝对不能省略此字段。

```
build
```
— 用于创建/修改文件、运行测试、构建或部署的任务
```
plan
```
— 用于分析、代码评审和只读任务

JSON示例:

json

{
  "command": {
    "review": {
      "agent": "plan"
    }
  }
}

Markdown示例:

yaml

---
agent: plan
---

如果Agent是子Agent，命令默认会触发子Agent调用。可通过

subtask: false

禁用此行为。

默认值: 未指定时使用当前Agent。

subtask (optional)

subtask（可选）

Force the command to trigger a subagent invocation. Useful to avoid polluting primary context.

JSON:

json

{
  "command": {
    "analyze": {
      "subtask": true
    }
  }
}

Markdown:

yaml

---
subtask: true
---

This forces subagent behavior even if the agent's

mode

primary

强制命令触发子Agent调用。适用于避免污染主上下文的场景。

JSON示例:

json

{
  "command": {
    "analyze": {
      "subtask": true
    }
  }
}

Markdown示例:

yaml

---
subtask: true
---

即使Agent的

mode

为

primary

，此配置也会强制触发子Agent行为。

model (optional)

model（可选）

Override the default model for this command.

JSON:

json

{
  "command": {
    "analyze": {
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

Markdown:

yaml

---
model: anthropic/claude-3-5-sonnet-20241022
---

覆盖命令使用的默认模型。

JSON示例:

json

{
  "command": {
    "analyze": {
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

Markdown示例:

yaml

---
model: anthropic/claude-3-5-sonnet-20241022
---

Common Patterns

常见模式

Testing Commands

测试命令

.opencode/commands/test.md

markdown

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

Run the full test suite with coverage report:
!`npm test -- --coverage`

Analyze failures and suggest fixes.

.opencode/commands/test.md

markdown

 
---
description: 带覆盖率的测试运行
agent: build
---

运行完整测试套件并生成覆盖率报告：
!`npm test -- --coverage`

分析失败用例并提出修复建议。

Code Review Commands

代码评审命令

.opencode/commands/review.md

markdown

 
---
description: Review recent changes
---

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

Changed files:
!`git diff --name-only HEAD~5`

Review these changes for:
- Code quality issues
- Performance concerns
- Security vulnerabilities

.opencode/commands/review.md

markdown

 
---
description: 评审最近的变更
---

最近的提交：
!`git log --oneline -10`

变更的文件：
!`git diff --name-only HEAD~5`

从以下方面评审这些变更：
- 代码质量问题
- 性能隐患
- 安全漏洞

Component Generation Commands

组件生成命令

.opencode/commands/component.md

markdown

 
---
description: Create React component
---

Create a new React component named $1:
- Location: src/components/$1.tsx
- Include TypeScript types
- Add basic props interface
- Follow project conventions from @src/components/Example.tsx

Usage:

/component Button

.opencode/commands/component.md

markdown

 
---
description: 创建React组件
---

创建一个名为$1的React组件：
- 位置：src/components/$1.tsx
- 包含TypeScript类型定义
- 添加基础Props接口
- 遵循@src/components/Example.tsx中的项目规范

使用方式:

/component Button

Deployment Commands

部署命令

.opencode/commands/deploy.md

markdown

 
---
description: Deploy to environment
agent: build
subtask: true
---

Deploy to $1 environment:
!`git status`

Steps:
1. Run pre-deployment checks
2. Build production bundle
3. Deploy to $1
4. Verify deployment

Usage:

/deploy staging

.opencode/commands/deploy.md

markdown

 
---
description: 部署到环境
agent: build
subtask: true
---

部署到$1环境：
!`git status`

步骤：
1. 运行预部署检查
2. 构建生产包
3. 部署到$1
4. 验证部署结果

使用方式:

/deploy staging

Documentation Commands

文档生成命令

.opencode/commands/doc.md

markdown

 
---
description: Generate documentation
---

Generate documentation for $ARGUMENTS:

Code to document:
@$ARGUMENTS

Create comprehensive documentation including:
- Function/class description
- Parameters and return values
- Usage examples
- Edge cases

Usage:

/doc src/utils/parser.ts

.opencode/commands/doc.md

markdown

 
---
description: 生成文档
---

为$ARGUMENTS生成文档：

待文档化的代码：
@$ARGUMENTS

创建包含以下内容的完整文档：
- 函数/类描述
- 参数和返回值
- 使用示例
- 边界情况

使用方式:

/doc src/utils/parser.ts

Built-in Commands

内置命令

OpenCode includes built-in commands:

```
/init
```
- Initialize OpenCode in a project
```
/undo
```
- Undo last change
```
/redo
```
- Redo last undone change
```
/share
```
- Share conversation
```
/help
```
- Show help

Note: Custom commands can override built-in commands. If you define a custom command with the same name, it will replace the built-in version.

OpenCode包含以下内置命令：

```
/init
```
- 在项目中初始化OpenCode
```
/undo
```
- 撤销上一次变更
```
/redo
```
- 重做上一次撤销的变更
```
/share
```
- 分享对话
```
/help
```
- 显示帮助信息

注意: 自定义命令可以覆盖内置命令。如果你定义了与内置命令同名的自定义命令，它会替换内置版本。

Best Practices

最佳实践

DO:

Use markdown files for easier editing and version control
Include clear descriptions for discoverability
Use positional arguments for multiple parameters
Leverage shell commands for dynamic context
Test commands before sharing with team
Use subagent mode for long-running or complex tasks
Keep templates focused on a single task

DON'T:

Create overly complex templates with too many arguments
Use shell commands that modify system state
Include sensitive data in command templates
Override built-in commands unless necessary
Forget to document what arguments commands expect
Set
```
model:
```
in command frontmatter — use
```
agent:
```
only; model is managed in
```
opencode.json
```

建议:

使用Markdown文件以便于编辑和版本控制
添加清晰的描述以提升可发现性
多参数场景使用位置参数
利用Shell命令获取动态上下文
与团队共享前先测试命令
长时间运行或复杂任务使用子Agent模式
模板聚焦于单一任务

不建议:

创建包含过多参数的复杂模板
使用会修改系统状态的Shell命令
在命令模板中包含敏感数据
除非必要，否则不要覆盖内置命令
忘记记录命令所需的参数
在命令前置元数据中设置
```
model:
```
字段 — 仅使用
```
agent:
```
；模型在
```
opencode.json
```
中管理

Examples

示例

See working examples in the

examples/

directory:

test-command.md
- Test execution with coverage
component-command.md
- Component generation with arguments
review-command.md
- Code review with git integration
deploy-command.md
- Multi-step deployment workflow

在

examples/

目录中可查看可用示例：

test-command.md
- 带覆盖率的测试执行
component-command.md
- 带参数的组件生成
review-command.md
- 集成Git的代码评审
deploy-command.md
- 多步骤部署工作流

Troubleshooting

故障排除

Command doesn't appear:

Verify file is in

.opencode/commands/

~/.config/opencode/commands/

Check filename is lowercase with
```
.md
```
extension
Ensure YAML frontmatter is valid (if used)

Arguments not replaced:

Check you're using
```
$ARGUMENTS
```
or
```
$1
```
,
```
$2
```
, etc.
Verify you're passing arguments:
```
/command arg1 arg2
```

Shell command fails:

Test command in terminal first:
```
bash -c "your command"
```
Check command runs from project root
Verify command exists on system

File reference not working:

Check file path is correct relative to project root
Verify file exists:
```
ls path/to/file
```
Use forward slashes even on Windows

命令未显示:

验证文件位于

.opencode/commands/

或

~/.config/opencode/commands/

目录下

检查文件名为小写且带有
```
.md
```
扩展名
确保YAML前置元数据有效（如果使用）

参数未替换:

检查是否使用了
```
$ARGUMENTS
```
或
```
$1
```
、
```
$2
```
等语法
验证是否传递了参数：
```
/command arg1 arg2
```

Shell命令执行失败:

先在终端测试命令：
```
bash -c "your command"
```
检查命令是否能从项目根目录运行
验证系统中存在该命令

文件引用无效:

检查文件路径相对于项目根目录是否正确
验证文件存在：
```
ls path/to/file
```
即使在Windows系统中也使用正斜杠

Additional Resources

额外资源

Reference Files

参考文件

For detailed information:

references/template-syntax.md
- Complete template syntax reference
references/configuration-options.md
- All configuration options explained
references/common-patterns.md
- More command patterns and examples

如需详细信息，请查看：

references/template-syntax.md
- 完整的模板语法参考
references/configuration-options.md
- 所有配置选项的详细说明
references/common-patterns.md
- 更多命令模式和示例

Example Files

示例文件

Working examples in

examples/

test-command.md
- Test execution
component-command.md
- Component generation
review-command.md
- Code review
deploy-command.md
- Deployment workflow

examples/

目录中的可用示例：

test-command.md
- 测试执行
component-command.md
- 组件生成
review-command.md
- 代码评审
deploy-command.md
- 部署工作流

Quick Reference

快速参考

Markdown command structure:

markdown

 
---
description: Brief description
agent: agent-name
subtask: true
---

Template content with $ARGUMENTS or $1, $2
Include shell output: !`command`
Include files: @path/to/file

JSON command structure:

json

{
  "command": {
    "name": {
      "template": "Prompt text",
      "description": "Brief description",
      "agent": "agent-name",
      "model": "model-name",
      "subtask": true
    }
  }
}

Special syntax:

```
$ARGUMENTS
```
- All arguments as single string
```
$1
```
,
```
$2
```
,
```
$3
```
- Individual arguments by position
!
command
- Shell command output
```
@path/to/file
```
- File contents

Markdown命令结构:

markdown

 
---
description: 简短描述
agent: agent-name
subtask: true
---

包含$ARGUMENTS或$1、$2的模板内容
包含Shell输出：!`command`
包含文件：@path/to/file

JSON命令结构:

json

{
  "command": {
    "name": {
      "template": "提示词文本",
      "description": "简短描述",
      "agent": "agent-name",
      "model": "model-name",
      "subtask": true
    }
  }
}

特殊语法:

```
$ARGUMENTS
```
- 所有参数作为单个字符串
```
$1
```
,
```
$2
```
,
```
$3
```
- 按位置获取单个参数
```
!
```
command`` - Shell命令输出
```
@path/to/file
```
- 文件内容

command-creation

Original

Translation

Command Creation for OpenCode

OpenCode 命令创建指南

MUST FOLLOW

必须遵守的规则

What Commands Are

命令是什么

Quick Start

快速开始

File Locations

文件位置

Creating Commands

创建命令的方法

Method 1: Markdown Files (Recommended)

方法1：Markdown文件（推荐）

Method 2: JSON Configuration

方法2：JSON配置

Command Templates

命令模板

1. Arguments with $ARGUMENTS

1. 使用$ARGUMENTS传递参数

2. Positional Arguments ($1, $2, $3, ...)

2. 位置参数（$1, $2, $3, ...）

3. Shell Output with !command

3. 使用!command注入Shell输出

4. File References with @

4. 使用@引用文件

Configuration Options

配置选项

template (required for JSON)

template（JSON方式必填）

description (optional)

description（可选）

agent (required)

agent（必填）

subtask (optional)

subtask（可选）

model (optional)

model（可选）

Common Patterns

常见模式

Testing Commands

测试命令

Code Review Commands

代码评审命令

Component Generation Commands

组件生成命令

Deployment Commands

部署命令

Documentation Commands

文档生成命令

Built-in Commands

内置命令

Best Practices

最佳实践

Examples

示例

Troubleshooting

故障排除

Additional Resources

额外资源

Reference Files

参考文件

Example Files

示例文件

Quick Reference

快速参考

3. Shell Output with !
`command`

3. 使用!
`command`
注入Shell输出