create-command

name	create-command
description	Use when creating or modifying custom opencode commands in the `commands/` directory. Covers markdown command files, frontmatter options (description, agent, model, subtask), prompt templates with $ARGUMENTS, shell output injection, and file references.
license	MIT
metadata	{"author":"Robert Hafner","source":"https://github.com/tedivm/opencode-config"}

Quick start

Create a markdown file in .opencode/commands/ (per-project, default). Only use ~/.config/opencode/commands/ (global) if explicitly requested. The filename (without .md) becomes the command name.

---
description: Run tests with coverage
---
Run the full test suite with coverage report and show any failures. Focus on the failing tests and suggest fixes.

The command runs as /test in the TUI.

Workflow

1. Determine scope — default to per-project (.opencode/commands/). Use global (~/.config/opencode/commands/) only if explicitly requested.
2. Ask about execution context — ask the user if the command should run as a subtask or with a specific agent. Only include subtask or agent in the frontmatter if they confirm.
3. Create the file — name it <command-name>.md (lowercase, hyphens allowed)
4. Write frontmatter — set description (required). Only add agent, model, or subtask if the user specifically requested them.
5. Write the template — the body content becomes the prompt sent to the LLM
6. Test — run /command-name in the TUI

Frontmatter options

Field	Required	Description
description	Yes	Shown in TUI command list
agent	No	Which agent handles the command (triggers subagent if it's a subagent type)
model	No	Override default model for this command
subtask	No	Set true to force subagent invocation regardless of agent mode

Prompt structure

Use markdown headings and lists to structure command templates. Organize prompts into clear sections:

• Overview — one or two sentences describing what the command does
• Constraints — bullet list of rules to follow
• Context — background info, injected shell output, or file references
• Phases — numbered steps
• Checklist — validation items

---
description: Review recent changes
---
## Overview

Review the most recent git commits and suggest improvements to code quality, naming, and potential bugs.

## Constraints

- Focus on substantive issues, not stylistic nitpicks
- Flag security concerns immediately
- Do not suggest changes to generated or vendor files

## Context

Recent commits:
!`git log --oneline -10`

## Phases

1. Read the diff of each commit and identify the scope of changes
2. Check for bugs, edge cases, and security issues
3. Evaluate naming, structure, and code organization
4. Compile findings into a prioritized list

## Checklist

- [ ] All commits reviewed
- [ ] Security concerns flagged
- [ ] Suggestions are actionable and specific
- [ ] Output is organized by priority

Template features

Arguments — use $ARGUMENTS for all args, or $1, $2, $3 for positional:

---
description: Create a new component
---
## Overview

Create a new React component named $ARGUMENTS with TypeScript support.

## Phases

1. Determine the component type and props based on $ARGUMENTS
2. Create the component file with proper TypeScript types
3. Add basic structure and default exports

Run: /component Button

---
description: Create a new file with content
---
## Overview

Create a file named $1 in the directory $2 with the following content: $3

## Phases

1. Verify the directory $2 exists
2. Create the file $1 inside $2
3. Populate it with the provided content

Run: /create-file config.json src "{ \"key\": \"value\" }"

Shell output — use !command`` to inject bash output into the prompt.

File references — use @filepath to include file contents in the prompt.

Notes

• Custom commands override built-in commands if names match
• Use the markdown file approach for simplicity; JSON config for programmatic setups