opencode-design-commands

Command Creator

Quick Start

Create .opencode/commands/<name>.md:

---
description: Run tests and fix all failures automatically
---

Run the full test suite, identify any failures, and fix them.

1. Run `npm test`
2. For each failure, identify root cause and fix
3. Re-run to verify all pass

Invoke it in OpenCode: /test

Run bun run opencode to start, then type /<name> to invoke your command.

Mindset

Slash commands are user-to-agent shortcuts — markdown files with an instruction template. User types /test → OpenCode substitutes placeholders → agent executes.

Decision rule:

• Human wants a shortcut → Command
• Agent needs standing instructions → Skill
• Task needs a persona → Agent

When to use: Repetitive multi-step tasks that need a one-word trigger. When NOT to use: Do not create a command for one-off tasks — just type the instruction directly. Do not use commands for interactive workflows; commands are one-shot. Modes: no agent: = default build (read/write); agent: plan = read-only; subtask: true = fire-and-forget.

Template Placeholders

$ARGUMENTS — all args; $1/$2 — positional; !cmd — shell output injection; @filename — include file content.

# Dynamic context injection example
!git log --oneline -5

---
description: Deploy to staging with context
agent: plan
subtask: true
---
Deploy $ARGUMENTS using the steps in docs/deploy.md.
!git log --oneline -3

Anti-Patterns

NEVER use $ARGUMENTS more than once in a command body. WHY: The placeholder is substituted literally — using it twice creates duplicate content that confuses the agent.

# BAD — duplicate content
Review $ARGUMENTS. Focus on $ARGUMENTS for security issues.

# GOOD — wrap in XML once
<target>$ARGUMENTS</target>
Review the target file for security issues and bugs.

NEVER tell the agent to "run /command" inside a command body. WHY: Agents cannot invoke slash commands from within a command — only users can type /cmd.

# BAD
After fixing, run /test to verify.

# GOOD
After fixing, run `npm test` to verify.