Files
opencode-primer/docs/commands.md
T
Wesam AbousaidandClaude Opus 4.8 29a69a35b0 docs: refresh for OpenCode v1.16.2 and fix correctness bugs
Update the guide to the current release (v1.16.2, 2026-06-05), verified
against opencode.ai/docs and github.com/anomalyco/opencode.

Correctness fixes:
- Plugins: tool.execute.before/after and shell.env are top-level hooks
  with an (input, output) signature, not event.type values. Rewrite both
  shipped example plugins plus the docs/migration examples so they fire.
- Permissions: bash glob maps resolve last-matching-rule-wins (catch-all
  "*" first), not most-specific-wins. Fix prose, reorder examples, and fix
  the shipped opencode.json (rm -rf* deny was shadowed by a later rm *).
- Drop non-existent permission keys repo_clone/repo_overview (15 keys, not
  17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort
  into model options; fix the `mise` install command.

Currency updates:
- v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section.
- Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4,
  gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs).
- Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and
  native GitHub commands; correct the specialist-prompt count; bump dates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-08 19:00:39 +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-8
---

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

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.