{
  "command": {
    "my-command": {
      "template": "Do the thing with $ARGUMENTS",
      "description": "One-line description"
    }
  }
}

Frontmatter Options

Field	Type	Description
`description`	string	REQUIRED. Brief description shown in command list
`agent`	string	Route to specific agent (e.g., `plan` for read-only research)
`model`	string	Override model for this command
`subtask`	boolean	If true, runs as background task via task tool

Template Placeholders

Placeholder	Expansion
`$ARGUMENTS`	All arguments after the command
`$1`, `$2`...	Positional arguments (space-separated)
`!cmd`	Output of shell command (e.g., `!git status`)
`@filename`	Contents of file (e.g., `@src/main.ts`)

Command Patterns

Simple Command

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

Run tests with coverage reporting:
\`!npm run test:coverage\`

Agent-Routed Command

---
description: Research a topic without modifying files
agent: explore
---

Research the following topic thoroughly, gathering context from the codebase and web:

$ARGUMENTS

Workflow Command with Arguments

---
description: Create a new component with tests
---

Create a new React component named "$1" in the $2 directory.

Requirements:
1. Component file with TypeScript
2. Test file with basic render test
3. Index export

Use the existing patterns from @src/components/Button/index.tsx

Background Task Command

---
description: Deep research task (runs in background)
subtask: true
agent: explore
---

Perform comprehensive research on: $ARGUMENTS

Return findings in a structured report.

Best Practices

MUST

Keep descriptions under 80 characters
Use agent: explore or agent: plan for read-only operations
Use subtask: true for long-running operations
Include example arguments in the description when helpful
Use @file to inject context from existing code

MUST NOT

Create commands that duplicate existing tools
Use commands for one-off tasks (just ask directly)
Forget to test with opencode run "test" after changes
Route to agents that don't exist

Command vs Direct Request

Commands are USER shortcuts. Use them when:

You repeat the same request pattern frequently
You want consistent agent/model routing
You need to inject file context or shell output

For one-off tasks, just ask Claude directly.

Validation

After creating a command:

opencode run "test"

Then test with:

/your-command test arguments

Scope	Path
Project	`.opencode/command/<name>.md`
Global	`~/.config/opencode/command/<name>.md`

opencode-commands

Command Fundamentals

Location