- quickstart.md: 5-minute path from curl to first commit - zen.md: model gateway with full lineup, pricing, BYOK, patterns - tui.md: keybinds, leader chords, themes, customization, sessions - agents.md: custom agents and subagents, full frontmatter, permission map - commands.md: custom slash commands, placeholders, patterns, override rules - skills.md: discoverable workflows, SKILL.md format, description-as-trigger - plugins.md: lifecycle hooks, full event catalog, four real patterns - mcp.md: local/remote MCP, OAuth (DCR), token budget, featured servers, with mermaid N×M → N+M diagram - migration.md: Claude Code, Cursor, Copilot, Aider — with "what X does better" subsections so the comparisons aren't one-sided - workflows.md: seven real recipes (TDD, bug investigation, multi-agent review, cross-repo research, migrations, CI, visual iteration) — CI example shows GitHub Actions + GitLab CI to avoid platform bias Every model slug, permission key, config key, env var, and CLI flag verified against the JSON schema or the live docs site.
5.0 KiB
Custom Commands
A custom command is a prompt template you've named. Drop a markdown file in
.opencode/commands/<name>.mdand it becomes/<name>in the TUI — with arguments, file refs, and shell output stitched in.
When to use a command vs. a skill vs. an agent
| Custom Command | Agent Skill | Custom Agent | |
|---|---|---|---|
| Invocation | Manual — user types /<name> |
Auto — model loads when description matches | Mode-dependent (Tab or @) |
| Best for | Repeatable user-driven prompts | Domain expertise the model should discover | A persistent role / tool surface |
| File | .opencode/commands/<name>.md |
.opencode/skills/<name>/SKILL.md (folder) |
.opencode/agents/<name>.md |
A good rule of thumb: commands run a workflow; skills teach the agent how to handle a class of task; agents are the role doing the work.
File format
---
description: Run tests with coverage and triage failures
agent: build
model: anthropic/claude-sonnet-4-5
subtask: false
---
Run the full test suite with coverage and surface failures.
Focus on the failing tests and suggest precise fixes.
Arguments: $ARGUMENTS
Frontmatter
| Key | Type | Required | Purpose |
|---|---|---|---|
description |
string | yes | One-liner shown in the slash-command palette |
agent |
string | no | Which agent runs the command (build, plan, or custom) |
model |
provider/model-id |
no | Override model just for this command |
subtask |
bool | no | If true, runs as a subagent (fresh, isolated context) |
Body placeholders
| Syntax | Substitutes |
|---|---|
$ARGUMENTS |
Everything after the command name |
$1, $2, … |
Positional args (whitespace-split) |
@<path> |
File content (fuzzy resolved) |
`!<cmd>` |
Shell stdout |
Placeholders are resolved at invocation time, so each run picks up fresh file content and shell output.
Where commands live
| Scope | Path |
|---|---|
| Project (committed) | .opencode/commands/ |
| Global | ~/.config/opencode/commands/ |
Project commands override globals; both override built-in commands of the same name.
Examples
Test runner
---
description: Run tests, triage failures
agent: build
---
!pnpm test --reporter=verbose
If any tests failed above, open the relevant source files and propose a fix.
Otherwise, summarize coverage and any flaky-looking tests.
Targeted code review
---
description: Review changed files for the current branch
agent: plan
---
!git diff --name-only main...HEAD
Review each changed file above for security, perf, and style. Suggest fixes
with code snippets — but do not edit files. Prioritize anything under
`src/auth/` or `src/api/`.
Scaffolding with positional args
---
description: Scaffold a new React component
agent: build
---
Create a new React component named `$1` under `src/components/$1/`:
- `index.tsx` — named export, Props type, default boilerplate
- `$1.test.tsx` — render test using @testing-library/react
- `$1.module.css` — only if styling is needed
Match the patterns in `src/components/Button/`. TypeScript strict mode.
Invoke with: /scaffold-component UserAvatar
Subtask isolation
---
description: Deep architectural review (isolated context)
agent: build
subtask: true
model: opencode/claude-opus-4-7
---
You are reviewing the architectural integrity of $ARGUMENTS.
Spend your context on:
- Coupling and cohesion
- Layer violations
- Missing abstractions / premature abstractions
- Long-term maintainability
Produce a report with findings and recommendations. Run as a subagent —
your work won't pollute the main session's context.
subtask: true runs the prompt as a general subagent in a child session, so the heavy reading and analysis stays separate from your main conversation.
Patterns
Chain commands
A command can reference outputs from previous commands via the conversation context:
/test
# (failures observed)
/review src/api/auth.ts
The /review invocation sees the test output in the conversation history and can use it.
Capture team-wide workflows
Commit .opencode/commands/ to your repo. Every contributor's opencode now has the same /test, /review, /pr commands with the same exact behavior — like committed git hooks for prompts.
Pre-baked arguments via frontmatter
If a command always runs with a particular model or agent, put it in the frontmatter so the user can't forget:
---
description: Long, deep refactor planning (Opus only)
agent: plan
model: opencode/claude-opus-4-7
---
Built-in commands and overriding
OpenCode's built-in commands (/init, /help, /share, etc. — see reference/slash-commands.md) can be overridden by a same-named file in your .opencode/commands/.
⚠️ Override sparingly. If you replace
/help, users in your repo lose access to the real help dialog. Pick a unique name like/repo-helpinstead.
📚 Full Commands guide: opencode.ai/docs/commands.