Opencode Commands

OpenCode Custom Commands

> 📚 Official Docs: For the latest information, always refer to the official documentation: > https://opencode.ai/docs/commands/

Expert skill for building, configuring, and troubleshooting OpenCode's custom command system. Covers markdown command files, JSON configuration, prompt placeholders, command options, built-in commands, keybinds, and overriding built-ins.

Overview

OpenCode's custom command system lets you define reusable prompts that execute via slash commands in the TUI (e.g., /test, /review, /deploy). Commands are triggered by typing / followed by the command name in the prompt input.

Custom commands are in addition to the built-in commands like /init, /undo, /redo, /share, /help. Custom commands can also override built-in command names — if you define a custom command with the same name as a built-in, the custom version takes precedence.

Commands support prompt placeholders ($ARGUMENTS, $1, $2, !command`, @filename`) for dynamic prompt construction, and options for agent routing, model override, and subagent invocation.

---

Create via Markdown

The primary way to create custom commands is by placing markdown files in the commands/ directory.

Location

| Scope | Path | |-----------|----------------------------------| | Project | .opencode/commands/ | | Global | ~/.config/opencode/commands/ |

The file name (minus .md extension) becomes the command name:

| File Name | Command | |-------------------------|-----------------| | test.md | /test | | review.md | /review | | deploy-staging.md | /deploy-staging | | create-component.md | /create-component |

Structure

A markdown command file has two parts:

1. Frontmatter (YAML between --- delimiters) — defines command properties
2. Content (everything after the closing ---) — becomes the prompt template sent to the LLM

Frontmatter Fields

| Field | Required | Description | |---------------|----------|-----------------------------------------------------------------------------| | description | No | Short description shown in the TUI command list when typing / | | agent | No | Which agent executes this command. If the agent is a subagent, triggers subagent invocation by default | | model | No | Override the default model for this command |

Complete Example

Create .opencode/commands/test.md:

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

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

Usage in TUI:

/test

Multi-line Prompts

The content after the frontmatter is the prompt template. You can use multiple paragraphs, code blocks, and any markdown formatting — everything is sent as-is to the LLM:

---
description: Refactor module with best practices
---

You are a senior software engineer. Analyze the following module and refactor it according to these principles:

1. Single Responsibility Principle
2. DRY (Don't Repeat Yourself)
3. Clear naming conventions
4. Proper error handling

Ensure all existing tests still pass after refactoring.

Nested Directories

Commands can be organized in subdirectories. The directory structure maps to a namespace:

.opencode/commands/
├── test.md              → /test
├── review.md            → /review
└── db/
    ├── migrate.md       → /db/migrate
    └── seed.md          → /db/seed

> Note: The exact namespace separator behavior depends on your OpenCode version. Verify with !ls .opencode/commands/ if unsure.

---

Create via JSON

You can also define commands in opencode.json (or opencode.jsonc) using the command field.

JSON Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    // This key becomes the command name
    "test": {
      // Required: the prompt sent to the LLM
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      // Shown in TUI command list
      "description": "Run tests with coverage",
      // Which agent executes (optional)
      "agent": "build",
      // Override model (optional)
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

Usage:

/test

JSON vs Markdown

| Aspect | JSON (opencode.json) | Markdown (.opencode/commands/) | |---------------------|-------------------------------|----------------------------------| | Location | Project root config file | Dedicated directory | | Template field | template (string, \n for newlines) | Content after frontmatter (natural newlines) | | Multi-command | All in one file | One file per command | | Version control | Changes mixed with other config | Isolated per command file | | Discoverability | Requires reading config | Browsable via file tree |

Recommendation: Use markdown files for most custom commands. Use JSON for quick one-off commands or when you prefer centralized configuration.

---

Prompt Placeholders

Prompt placeholders allow dynamic content injection into your command templates. They are evaluated at runtime when the command is executed.

$ARGUMENTS — All Arguments as Single String

The $ARGUMENTS placeholder is replaced with all arguments passed to the command as a single concatenated string.

Markdown example:

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

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

JSON example:

{
  "command": {
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

Usage:

/component Button

Resulting prompt:

Create a new component named Button with TypeScript support.
Include proper typing and basic structure.

Usage with multiple words:

/component UserAvatar with image loading

Resulting prompt:

Create a new component named UserAvatar with image loading with TypeScript support.
Include proper typing and basic structure.

> Note: $ARGUMENTS captures everything after the command name as one string, including spaces. It does not split on spaces.

---

$1, $2, $3 — Positional Arguments

Individual arguments are accessed via positional parameters. Arguments are split by whitespace.

Markdown example:

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

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

JSON example:

{
  "command": {
    "create-file": {
      "template": "Create a file named $1 in the directory $2\nwith the following content: $3",
      "description": "Create a new file with content"
    }
  }
}

Usage:

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

Resulting prompt:

Create a file named config.json in the directory src
with the following content: { "key": "value" }

Positional argument mapping:

| Placeholder | Value | |-------------|--------------| | $1 | config.json| | $2 | src | | $3 | { "key": "value" } |

Additional positional arguments:

• $4, $5, $6, ... — Access arguments by position (up to the number of arguments provided)
• Unreferenced positional parameters are simply ignored in the prompt

Multi-word arguments: Positional parameters split on whitespace. To pass a multi-word value as a single positional argument, quote it:

/create-file README.md . "Hello World"

This maps:

• $1 → README.md
• $2 → .
• $3 → Hello World

---

!command`` — Inject Bash Command Output

Use backtick syntax with ! prefix to run a bash command and inject its output directly into the prompt. The command runs in your project's root directory.

Syntax: !command``

Markdown example — Analyze test coverage:

---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

Markdown example — Review recent changes:

---
description: Review recent changes
---

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

Review these changes and suggest any improvements.

Markdown example — Check project structure:

---
description: Analyze project structure
---

Project file tree:
!`find . -type f -name "*.ts" | head -30`

Analyze the module organization and suggest improvements.

JSON example:

{
  "command": {
    "review-changes": {
      "template": "Recent git commits:\n!`git log --oneline -10`\n\nReview these changes and suggest any improvements.",
      "description": "Review recent changes"
    }
  }
}

Behavior:

• The bash command executes in the project's root directory
• stdout is captured and inserted into the prompt at the placeholder position
• stderr is typically not included (or handled silently)
• If the command fails, the output may be empty or contain an error message
• The command runs synchronously — the prompt is not sent until the command completes
• Multiple !command`` placeholders can be used in a single prompt

Advanced examples:

---
description: Check dependency versions
---

Current dependencies:
!`cat package.json | jq '.dependencies'`

Check for outdated or vulnerable packages.

---
description: Lint and format check
---

Lint output:
!`npm run lint 2>&1`

Format check:
!`npx prettier --check . 2>&1`

Fix any issues found.

---

@filename — Include File Content

Use @ followed by a filename to include the file's content in the prompt. The file path is relative to the project root.

Syntax: @filename or @path/to/file

Markdown example — Review a component:

---
description: Review component
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

Markdown example — Compare files:

---
description: Compare implementations
---

Compare these two implementations:
@src/utils/old-helper.ts
@src/utils/new-helper.ts

Identify the differences and explain which approach is better.

JSON example:

{
  "command": {
    "review-component": {
      "template": "Review the component in @src/components/Button.tsx.\nCheck for performance issues and suggest improvements.",
      "description": "Review component"
    }
  }
}

Behavior:

• The file content is resolved relative to the project root directory
• The file's content is included verbatim in the prompt
• The LLM receives the file content as context
• If the file does not exist, the placeholder may be included as-is or produce an error depending on the OpenCode version
• Multiple @ references can be used in a single prompt

Fuzzy file search: In the TUI prompt input (outside of commands), typing @ triggers a fuzzy file search. Inside command templates, @ references are resolved literally by path.

---

Command Options

Each custom command supports the following configuration options. These can be set in JSON (opencode.json) or via frontmatter in markdown files.

template (Required for JSON; implicit in Markdown)

The prompt that will be sent to the LLM when the command is executed.

In JSON: The template field is required. Use \n for newlines within the string.

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report.\nFocus on failures and suggest fixes."
    }
  }
}

In Markdown: The template is the content after the frontmatter. No separate field needed — everything below the closing --- becomes the template.

---
description: Run tests
---

Run the full test suite with coverage report.
Focus on failures and suggest fixes.

---

description

A brief description of what the command does. This is displayed in the TUI command list when you type / and is purely informational.

In JSON:

{
  "command": {
    "test": {
      "template": "...",
      "description": "Run tests with coverage"
    }
  }
}

In Markdown frontmatter:

---
description: Run tests with coverage
---

In TUI: When you type /, the command list shows each command's description next to its name:

/test      Run tests with coverage
/review    Review code changes
/deploy    Deploy to staging

---

agent

Optionally specify which agent should execute this command. If the specified agent is a subagent, the command will trigger a subagent invocation by default (see subtask below).

In JSON:

{
  "command": {
    "review": {
      "template": "Review the recent code changes for quality and correctness.",
      "agent": "plan"
    }
  }
}

In Markdown frontmatter:

---
description: Review code
agent: plan
---

Review the recent code changes for quality and correctness.

Behavior:

• If agent is not specified, the command uses the current agent (the one active in the session)
• If agent specifies a subagent, the command automatically invokes it as a subagent (unless subtask: false is set)
• If agent specifies the primary agent, the command runs in the primary context (unless subtask: true is set)

---

subtask

A boolean that forces the command to trigger a subagent invocation. This is useful when you want the command to run in an isolated context without polluting your primary conversation.

In JSON:

{
  "command": {
    "analyze": {
      "template": "Analyze the codebase for security vulnerabilities.",
      "subtask": true
    }
  }
}

In Markdown frontmatter:

---
description: Security analysis
subtask: true
---

Analyze the codebase for security vulnerabilities.

Behavior:

• When subtask: true, the agent acts as a subagent regardless of its mode setting in agent configuration
• When subtask: false, the agent runs in its default mode even if it's a subagent
• If not specified, defaults to false unless the agent is a subagent (in which case it defaults to true)

Use cases for subtask: true:

• Long-running analysis that shouldn't block the main conversation
• Tasks where you want results returned without full conversation context
• Parallel execution of independent tasks
• Keeping the primary context clean for focused work

---

model

Override the default model for this command. Useful when a specific task benefits from a different model (e.g., a reasoning-heavy task using a more capable model, or a simple task using a faster/cheaper model).

In JSON:

{
  "command": {
    "analyze": {
      "template": "Analyze this codebase for architectural issues.",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

In Markdown frontmatter:

---
description: Architectural analysis
model: anthropic/claude-3-5-sonnet-20241022
---

Analyze this codebase for architectural issues.

Common model override patterns:

| Use Case | Model St

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Timmy6942025
• Source: Timmy6942025/opencode-builder-skill
• License: MIT

Install and usage instructions live in the source repository linked above.