| name | kickstart-creator-command |
| description | Create OpenCode custom commands. Use when user wants to create a new command,
make a slash command, add a command, or define reusable prompts for TUI.
Activates for phrases like "/create command", "create a command", "add a custom command",
"make a slash command", "I want to create a command that...". |
<core_approach>
Command creation is collaborative and iterative, not mechanical.
- Identify where the user is in the loop and jump in from there — don't restart from scratch if they already have a draft.
- Explore before asking. Use read-only tools to answer what the context can already tell you, then interview for what remains genuinely unclear.
- Explain the why behind instructions rather than issuing rigid MUSTs. Today's models generalize better from reasoning than from rules.
- Stay flexible — if the user says "just vibe with me and skip the evals", do that.
- Generated commands can include 5 XML sections (
<core_approach>, <workflow>, <reference>, <examples>, <quality_checklist>) just like skills, but this is optional — simpler commands without XML tags are also valid.
</core_approach>
Command file location
- Project-level:
.opencode/commands/<name>.md
- Global:
~/.config/opencode/commands/<name>.md
Command file structure
Commands are .md files with YAML frontmatter:
---
description: What this command does
agent: build
model: anthropic/claude-3-5-sonnet-20241022
subtask: false
---
Command prompt template here.
Use $ARGUMENTS for user input.
Use !`command` for shell output.
Frontmatter options
| Option | Required | Description |
|---|
| description | No | Brief description shown in TUI |
| agent | No | Agent to use (e.g., "build", "plan") |
| model | No | Specific model to override |
| subtask | No | Force as subtask (true/false) |
Template placeholders
| Placeholder | Description |
|---|
$ARGUMENTS | All arguments passed to command |
$1, $2, $3 | Individual positional arguments |
| ``!`command``` | Shell output injected into prompt |
@filename | File content referenced in prompt |
Extended command structure (optional)
For complex commands, include 5 XML-tagged sections just like skills:
| Tag | Purpose |
|---|
<core_approach> | Guiding philosophy and interaction style |
<workflow> | Step-by-step instructions (should include Explore and Interview phases) |
<reference> | Context tables, config formats, lookup data |
<examples> | Input/output pairs |
<quality_checklist> | Pre-delivery self-check |
Configuration alternative
Commands can also be defined in opencode.jsonc:
{
"command": {
"test": {
"template": "Run the full test suite...",
"description": "Run tests with coverage",
"agent": "build"
}
}
}
Writing style guidelines
- Use imperative form in instructions ("Read the file", not "You should read the file")
- Explain why over issuing hard constraints — lean on model intelligence
- Avoid all-caps ALWAYS/NEVER unless genuinely critical
- Prefer general principles over narrow, example-specific rules
- After drafting, re-read with fresh eyes and trim anything not pulling its weight
Example 1: Simple command
User input: "create a command to run tests"
Output: Creates .opencode/commands/test.md
---
description: Run the full test suite
---
Run the test suite and report any failures.
Example 2: Command with arguments
User input: "create a component command that accepts a name"
Output: Creates .opencode/commands/component.md
---
description: Create a new component
---
Create a new React component named $ARGUMENTS.
Include TypeScript types and basic structure.
Usage: /component Button
Example 3: Command with shell output
User input: "create a command to analyze coverage"
Output: Creates .opencode/commands/analyze-coverage.md
---
description: Analyze test coverage
---
Here are the current test results:
!`npm test`
Based on these results, suggest improvements.
Example 4: Command using specific agent
User input: "create a review command using plan agent"
Output: Creates .opencode/commands/review.md
---
description: Review code changes
agent: plan
---
Review the recent code changes for quality and suggest improvements.
Example 5: Complex command with XML structure
User input: "create a command for deploying to production with approval stages"
Output: Creates .opencode/commands/deploy.md with full XML sections
---
description: Deploy to production with approval workflow
agent: build
---
<core_approach>
Deployments require careful approval at each stage...
</core_approach>
<workflow>
1. Check current branch is production-ready
2. Request user confirmation before each stage
3. Execute deployment steps sequentially
</workflow>
<reference>
## Deployment stages
| Stage | Action |
|-------|--------|
| 1 | Build and test |
| 2 | Stage deployment |
| 3 | Production rollout |
</reference>
<examples>
**Input**: `/deploy`
**Output**: Runs through deployment workflow with approvals
</examples>
<quality_checklist>
- [ ] Stage gates in place
- [ ] Rollback plan documented
- [ ] User confirms each stage
</quality_checklist>
Phase 1: Explore
Before asking any questions, explore the available context to understand structure and conventions.
Use read, grep, and other read-only tools to:
- Find existing commands in the project — understand current patterns
- Check
.opencode/commands/ directory
- Look for related skills or agents that might influence command design
- Identify any project-specific conventions
Do NOT ask questions that the available context can already answer.
Phase 2: Interview
Based on your exploration, use the question tool to clarify only what is genuinely unclear or has multiple valid answers.
Ask about:
- Name: What should the command be called?
- Purpose: What prompt/template should the command execute?
- Complexity: Simple one-liner or multi-phase workflow?
- Agent: Should it use a specific agent (build, plan) or current agent?
- Arguments: Are there any arguments the command should accept?
- XML structure: Should the command include 5 XML sections (like skills), or keep it simple?
If the user requests a complex command, recommend including XML sections for better structure.
Wait for all answers before proceeding to Phase 3.
Phase 3: Create the command
Create the command file in .opencode/commands/<command-name>.md.
For simple commands:
---
description: <description>
agent: <agent-name>
---
<template prompt>
For complex commands (recommended 5-section structure):
---
description: <description>
agent: <agent-name>
---
<core_approach>
Guiding philosophy for this command.
</core_approach>
<workflow>
1. Step one
2. Step two
</workflow>
<reference>
Context tables and lookup data.
</reference>
<examples>
**Input**: `/command-name`
**Output**: Expected behavior
</examples>
<quality_checklist>
- [ ] Item one
- [ ] Item two
</quality_checklist>
After drafting, re-read with fresh eyes and trim anything not pulling its weight.
Phase 4: Review & Iterate
Show the user the created file and explain how to use it:
- Command invoked via
/<command-name> in TUI
- Can also add via
command in opencode.jsonc config
Propose 1-2 realistic test prompts and iterate based on feedback.
<quality_checklist>
Pre-delivery checklist
Before sharing the command:
</quality_checklist>
