When to ask: Vague request ("make a command"), or multiple implementation approaches exist.

</question_tool>

Command Locations

Scope	Path
Project	`.opencode/command/<name>.md`
Global	`~/.config/opencode/command/<name>.md`

Template Placeholders (CRITICAL)

Single Insertion: Each placeholder ($ARGUMENTS, $1, @filename, etc.) MUST be inserted ONLY ONCE in the command body.
Dedicated Blocks: Use dedicated XML blocks for user inputs and file contents to keep the objective and instructions clean.
Preference: Prefer using a single argument ($ARGUMENTS) over complex positional ones unless strictly necessary.

BAD: "Do $ARGUMENTS and then check $ARGUMENTS for errors."

GOOD:

<user_guidelines>
$ARGUMENTS
</user_guidelines>

<context>
@src/schema.ts
</context>

<objective>
Analyze findings based on user guidelines and the provided schema.
</objective>

Placeholder	Description	Example
`$ARGUMENTS`	All arguments passed	`/cmd foo bar` → "foo bar"
`$1`, `$2`, `$3`	Positional arguments	`/cmd foo bar` → $1="foo", $2="bar"
`!command`	Shell output injection	`!ls -F`
`@filename`	Include file content	`@src/index.ts`

Terminology Standard

Direct Address: You MUST use "you" (referring to the agent executing the command) instead of "the agent" or "opencode".

Command File Format

---
description: 3-word command summary
agent: build # Optional: build, plan, or custom agent
model: provider/model-id # Optional: override model
subtask: true # Optional: run as subagent
---

<summary>
Line 1: You MUST [purpose].
Line 2: You SHOULD [inputs].
Line 3: You MUST [outcome].
</summary>

<user_guidelines>
$ARGUMENTS
</user_guidelines>

Template body goes here.

Frontmatter Options

Field	Purpose	Required
`description`	Shown in command list	RECOMMENDED
`agent`	Route to specific agent	No
`model`	Override model	No
`subtask`	Force subagent invocation	No

Conceptual Boundary (CRITICAL)

Commands are for USERS: They are high-level shortcuts for humans to trigger an agent with specific context.
Agents CANNOT use commands: Agents lack a terminal interface to "type" commands. They execute the template body provided by the command.
One-Way Street: User -> Command -> Agent.
NEVER tell an agent to use a command "proactively"—they literally cannot.
If logic needs to be shared, put it in a Skill (script/instruction), not a Command.

Shell Commands in Templates

Use the !command syntax to inject bash output into your prompt. The shell execution is triggered by an exclamation mark followed by the command wrapped in backticks:

Review recent changes:

!`git log --oneline -10`

Suggest improvements.

File References

Use @ to include file content:

Given the schema in @prisma/schema.prisma, generate a migration for $ARGUMENTS.

Phase 1: Understand the Task

"What task do you want to automate?"
- Get the repetitive prompt/workflow
- Examples: "run tests", "review this file", "create a component"
"Can you show me how you'd normally ask for this?"
- Get the actual prompt they'd type
- This becomes the template body

Phase 2: Inputs & Routing

"Does it need arguments?"
- If they mention "this file", "a name", "the function" → yes
- Explain: /command foo bar → $ARGUMENTS = "foo bar", $1 = "foo", $2 = "bar"
"Should it make changes or just analyze?"
- Changes → default agent (build)
- Analysis only → set agent: plan
"Should it run as a background subtask?"
- Long-running or parallel work → set subtask: true
- Interactive or quick → leave unset
"Project-specific or use everywhere?"
- Project → .opencode/command/
- Global → ~/.config/opencode/command/

Phase 3: Review & Refine

Show the draft command, ask for feedback
- "Here's what I've created. Want to adjust anything?"
- Iterate until user is satisfied

Be flexible: If user provides lots of info upfront, adapt—MUST NOT rigidly ask every question.

/test - Run and Fix Tests

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

<summary>
You MUST run the full test suite.
You SHOULD identify and fix failures.
You MUST re-verify fixes.
</summary>

<objective>
You MUST run the full test suite, find the root cause of any failures, and fix the issue.
</objective>

1. Show the failing test
2. Identify the root cause
3. Fix the issue
4. Re-run to verify

/review - Code Review (Read-Only)

---
description: Review code for issues
agent: plan
---

<summary>
You MUST review $ARGUMENTS for issues.
You SHOULD check for bugs, security, and performance.
You MUST provide actionable feedback.
</summary>

<objective>
You MUST review $ARGUMENTS for bugs, security, and performance issues and provide actionable feedback without making changes.
</objective>

- Bugs and edge cases
- Security issues
- Performance problems

/commit - Smart Commit with Prefixes

---
description: Stage and commit with conventional prefix
---

<summary>
You MUST analyze changes and stage files.
You SHOULD choose a conventional commit prefix.
You MUST commit with a concise message.
</summary>

<context>
!`git status`
!`git diff`
</context>

<objective>
You MUST analyze changes, stage relevant files, and commit with a concise message.
</objective>

1. Analyze all changes
2. Choose appropriate prefix: docs:, feat:, fix:, refactor:, test:, ci:
3. Write concise commit message (imperative mood)
4. Stage relevant files and commit

/spellcheck - Check Spelling

---
description: Check spelling in markdown files
subtask: true
---

<summary>
You MUST find unstaged markdown files.
You SHOULD check them for spelling errors.
You MUST report any found errors.
</summary>

Check spelling in all unstaged markdown files:

<context>
!`git diff --name-only | grep -E '\.md$'`
</context>

<objective>
You MUST check for and report any spelling errors found in unstaged markdown files.
</objective>

/issues - Search GitHub Issues

---
description: Search GitHub issues
model: anthropic/claude-3-5-haiku-20241022
subtask: true
---

<summary>
You MUST search GitHub issues for $ARGUMENTS.
You SHOULD limit results to the top 10.
You MUST summarize the relevant issues.
</summary>

Search GitHub issues matching: $ARGUMENTS

<context>
!`gh issue list --search "$ARGUMENTS" --limit 10`
</context>

<objective>
You MUST summarize the top 10 relevant GitHub issues found for $ARGUMENTS.
</objective>

/component - Create Component

---
description: Create a new React component
---

<summary>
You MUST create a React component named $1.
You SHOULD include TypeScript props and basic styling.
You MUST provide a unit test file.
</summary>

Create a React component named $1 in $2 with:

<objective>
You MUST create a React component with TypeScript props and basic styling, and provide a corresponding unit test file.
</objective>

- TypeScript props interface
- Basic styling
- Unit test file

Usage: /component UserProfile src/components

/migrate - Database Migration

---
description: Generate database migration
---

<summary>
You MUST read the Prisma schema.
You SHOULD generate a migration for $ARGUMENTS.
You MUST ensure the migration matches the schema.
</summary>

Given the schema in @prisma/schema.prisma:

<context>
@prisma/schema.prisma
</context>

<objective>
You MUST generate a Prisma migration for $ARGUMENTS that matches the provided schema.
</objective>

<quality_checklist>

Before delivering:

Asked what task to automate
Got example of how they'd normally prompt it
Determined if arguments needed ($ARGUMENTS vs $1, $2)
Set appropriate agent (plan for read-only)
Considered subtask for long-running work
Chose project vs global scope
Showed draft and got feedback

</quality_checklist>

<best_practices>

Do	Don't
Keep templates focused	Cram multiple tasks in one
Use `$1`, `$2` for structured args	Rely only on $ARGUMENTS for multi-arg
Use !`cmd` to gather context	Hardcode dynamic values
Use `@file` for config/schema refs	Copy-paste file contents
Set `agent: plan` for read-only	Forget agent for reviews
Set `subtask: true` for parallel work	Block main session unnecessarily

</best_practices>

command-creator

Command Creator