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>
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-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-helpinstead.
📚 Full Commands guide: opencode.ai/docs/commands.