Files
opencode-primer/docs/commands.md
T
Wesam Abousaid 9522c859fd docs(guides): add 10 deep-dive guides verified against opencode.ai/docs
- 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.
2026-05-18 19:59:28 +02:00

5.0 KiB

Custom Commands

A custom command is a prompt template you've named. Drop a markdown file in .opencode/commands/<name>.md and 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-help instead.

📚 Full Commands guide: opencode.ai/docs/commands.