# Opencode Commands

> Create and manage OpenCode slash commands. Use for defining /command shortcuts, template syntax, argument interpolation, and workflow composition. Use proactively when user says "create a command", "slash command", "/command", "shortcut for", or asks about command frontmatter options. Examples: - user: "Create a /review command" → design command with description, optional agent routing - user: "How do I pass arguments to commands?" → explain $ARGUMENTS, $1, $2, `!shell`, @file - user: "Make a command that runs tests" → create command with shell interpolation

- Skill: `jal-co/opencode-commands` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jal-co/opencode-commands`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jal-co/opencode-commands/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jal-co (https://skillmd.com/u/jal-co)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jal-co/opencode-commands

---


<overview>

Create user-accessible slash commands that streamline workflows.

</overview>

<rules>

## Command Fundamentals

### Location

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

Commands MAY also be defined inline in `opencode.json`:

```jsonc
{
  "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`) |

</rules>

<examples>

## Command Patterns

### Simple Command

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

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

### Agent-Routed Command

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

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

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

Perform comprehensive research on: $ARGUMENTS

Return findings in a structured report.
```

</examples>

<constraints>

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

</constraints>

<guidelines>

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

</guidelines>

<examples>

## Validation

After creating a command:

```bash
opencode run "test"
```

Then test with:

```
/your-command test arguments
```

</examples>