Command Creation for 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

---
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.

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.

Quick Start

Create a command in three steps:

1. Create command file:

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

2. Add frontmatter and content to test.md:

   ---
   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.
   

3. Use the command in TUI:

   /test
   

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

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.

Creating Commands

Method 1: Markdown Files (Recommended)

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:

 
---
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.

Method 2: JSON Configuration

Add commands to opencode.jsonc using the command option:

{
  "$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.

Command Templates

Templates support special syntax for dynamic behavior:

1. Arguments with $ARGUMENTS

Pass arguments to commands using the $ARGUMENTS placeholder:

.opencode/commands/component.md:

 
---
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.

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

Access individual arguments using positional parameters:

.opencode/commands/create-file.md:

 
---
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" }

3. Shell Output with !command

Inject bash command output into prompts using !command syntax:

.opencode/commands/analyze-coverage.md:

 
---
description: Analyze test coverage
---

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

Based on these results, suggest improvements to increase coverage.

More examples:

 
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.

4. File References with @

Include file contents using @ followed by the filename:

.opencode/commands/review-component.md:

 
---
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:

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

Configuration Options

template (required for JSON)

The prompt sent to the LLM when the command executes.

JSON:

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

Markdown: Content after frontmatter is the template.

description (optional)

Brief description shown in the TUI when typing the command.

JSON:

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

Markdown:

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

agent (required)

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:

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

Markdown:

---
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.

subtask (optional)

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

JSON:

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

Markdown:

---
subtask: true
---

This forces subagent behavior even if the agent's mode is primary.

model (optional)

Override the default model for this command.

JSON:

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

Markdown:

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

Common Patterns

Testing Commands

.opencode/commands/test.md:

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

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

Analyze failures and suggest fixes.

Code Review Commands

.opencode/commands/review.md:

 
---
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

Component Generation Commands

.opencode/commands/component.md:

 
---
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

Deployment Commands

.opencode/commands/deploy.md:

 
---
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

Documentation Commands

.opencode/commands/doc.md:

 
---
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

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.

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

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

Troubleshooting

Command doesn't appear:

1. Verify file is in .opencode/commands/ or ~/.config/opencode/commands/
2. Check filename is lowercase with .md extension
3. Ensure YAML frontmatter is valid (if used)

Arguments not replaced:

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

Shell command fails:

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

File reference not working:

1. Check file path is correct relative to project root
2. Verify file exists: ls path/to/file
3. Use forward slashes even on 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

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

Quick Reference

Markdown command structure:

 
---
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:

{
  "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