# Command Creation

> This skill should be used when the user asks to "create a command", "add a custom command", "make a slash command", "create /command", or needs guidance on creating custom commands in OpenCode.

- Skill: `the-perfect-developer/command-creation` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add the-perfect-developer/command-creation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/the-perfect-developer/command-creation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: the-perfect-developer (https://skillmd.com/u/the-perfect-developer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/the-perfect-developer/command-creation

---


# 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

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

## 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**:
   ```bash
   mkdir -p .opencode/commands
   touch .opencode/commands/test.md
   ```

2. **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.
   ```

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

### Method 2: JSON Configuration

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.

## 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`:
```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`.

### 2. Positional Arguments ($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" }`

### 3. Shell Output with !`command`

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.

### 4. File References with @

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

## Configuration Options

### template (required for 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.

### description (optional)

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

### 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**:
```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.

### subtask (optional)

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` is `primary`.

### model (optional)

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

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

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

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

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

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

## 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**:
```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