opencode-subagent-patterns

name

opencode-subagent-patterns

description

Design and implement effective subagent patterns in OpenCode. Use when creating custom agents, orchestrating multi-agent workflows, delegating batch processing tasks, optimizing tool permissions to avoid approval spam, selecting appropriate models for agents, or implementing any multi-agent coordination pattern. Covers agent creation, orchestration, delegation strategies, tool selection, permission management, and prompt templates.

OpenCode Subagent Patterns

Overview

Sub-agents are specialized AI assistants that primary agents can delegate tasks to. Each sub-agent has its own context window, configurable tools, and custom system prompt. This skill provides patterns and best practices for creating effective sub-agent workflows in OpenCode.

Subagent Prompt Anatomy

For reliable behavior, structure subagent prompts in this order:

1. Role - what specialist this agent is
2. Scope - what it owns for this task
3. Hard boundaries - what it must not do
4. Tool routing rules - which tools to prefer and avoid
5. Workflow - ordered execution steps
6. Output contract - exact format and constraints
7. Done-when - completion criteria and stop conditions

Minimal Skeleton

You are a [role].

Scope:
- [owned area]

Boundaries:
- Do not [forbidden action]; instead [safe fallback]
- If task requires [out-of-scope area], stop and report "Requires [specialist]"

Tool routing:
- Prefer [tool set] for [job]
- Use bash only for [specific reason]

Workflow:
1. [step]
2. [step]
3. [step]

Output:
- [format contract]

Done when:
- [acceptance condition]

Why Use Subagents: Context Hygiene

The primary value of subagents isn't just specialization—it's keeping your main context clean.

Do not delegate by default. Use subagents when isolated context, broad discovery, specialized judgment, or parallel work improves the result. Work directly for small direct answers, single-file inspections, obvious edits, or tasks where the primary context already contains enough evidence.

Without subagent (context bloat):

Main context accumulates:
├─ git status output (50 lines)
├─ npm run build output (200 lines)
├─ test results (100 lines)
├─ deployment logs (100 lines)
└─ Context: 📈 450+ lines consumed

With subagent (context hygiene):

Main context:
├─ "Deploy to production"
├─ [agent summary - 30 lines]
└─ Context: 📊 ~50 lines consumed

Subagent context (isolated):
├─ All verbose tool outputs
├─ All intermediate reasoning
└─ Discarded after returning summary

The math: A deploy workflow runs ~10 tool calls. That's 450+ lines in main context vs 30-line summary with a subagent. Over a session, this compounds dramatically.

When this matters most:

• Repeatable workflows (deploy, migrate, audit, review)
• Verbose tool outputs (build logs, test results, API responses)
• Multi-step operations where only the final result matters
• Long sessions where context pressure builds up

Built-in Subagents

OpenCode includes built-in subagents available out of the box:

General Agent

General-purpose agent for complex, multi-step tasks requiring both exploration AND action.

• Mode: Subagent
• Capabilities: Read AND write
• Tools: All tools except todo
• When to use: Complex research, multi-step operations, code modifications

Explore Agent

Fast, lightweight agent optimized for read-only codebase exploration.

• Mode: Subagent
• Capabilities: Strictly read-only
• Tools: Glob, Grep, Read, Bash (read-only commands)
• When to use: Searching/understanding codebase without making changes

You can also invoke these by @ mentioning them: @general or @explore

Creating Custom Subagents

Agent Locations

Type	Location	Scope	Priority
Project	.opencode/agents/	Current project only	Highest
User	~/.config/opencode/agents/	All projects	Lower

When names conflict, project-level takes precedence.

Configuration Methods

Method 1: Interactive Creation

opencode agent create

This interactive command will:

1. Ask where to save the agent (global or project)
2. Request description of what the agent should do
3. Generate appropriate system prompt and identifier
4. Let you select which tools the agent can access
5. Create a markdown file with the configuration

Method 2: JSON Configuration

Configure agents in your opencode.json config file:

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues. Use after code changes.",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "tools": {
        "read": true,
        "grep": true,
        "glob": true,
        "bash": false
      }
    }
  }
}

Method 3: Markdown Files

Place markdown files in .opencode/agents/ or ~/.config/opencode/agents/:

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
tools:
  read: true
  grep: true
  glob: true
  bash: false
---

You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

The markdown file name becomes the agent name. For example, review.md creates a review agent.

Core Configuration Fields

Required Fields

• description: What the agent does and when to use it. Use normal trigger wording by default; reserve "MUST BE USED" for mandatory gates.
• mode: Set to "subagent" for sub-agents, "primary" for primary agents, or "all" for both.

Optional Fields

• model: Override model for this agent (e.g., "anthropic/claude-sonnet-4-20250514"). If omitted, inherits from primary agent.
• temperature: Control randomness (0.0-1.0). Lower = focused, higher = creative. Default varies by model.
• tools: Object specifying which tools are enabled (true/false). Omit to inherit all tools.
• permission: Control tool permissions ("ask", "allow", "deny"). Applies to edit, bash, webfetch, and task tools.
• prompt: Custom system prompt file path (relative to config location)
• hidden: Set to true to hide from @ autocomplete (subagent only)
• color: UI color (hex like "#FF5733" or theme color like "accent")
• steps: Maximum agentic iterations before forced text-only response

Example with All Options

{
  "agent": {
    "security-auditor": {
      "description": "Performs security audits. Use proactively for security reviews.",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.1,
      "tools": {
        "read": true,
        "grep": true,
        "glob": true,
        "bash": false,
        "write": false,
        "edit": false
      },
      "permission" 
         
         
      
       
    
  

Using Subagents

Automatic Delegation

Primary agents proactively delegate based on:

• Task description in your request
• description field in subagent config
• Current context and available tools

Use normal trigger wording such as "Use when..." by default. Reserve "use PROACTIVELY" or "MUST BE USED" for cases where underuse is materially worse than overuse, such as security review gates or mandatory validation workflows.

Explicit Invocation

Use @ mention to explicitly invoke a specific subagent:

> @code-reviewer look at my recent changes
> @test-runner fix the failing tests
> @explore find where user authentication is handled

Session Navigation

When subagents create child sessions, navigate between parent and children:

• +Right (or session_child_cycle) - Cycle forward through sessions
• +Left (or session_child_cycle_reverse) - Cycle backward through sessions

Advanced Patterns

For detailed guidance on specific patterns, see the reference files:

Orchestration

See references/orchestration.md

How to create orchestrator agents that delegate to multiple specialists:

• Enabling orchestration with the task tool
• Orchestrator pattern examples
• Multi-specialist workflows
• Parallel research patterns
• Nesting depth considerations
• Task permission control

Delegation

See references/delegation.md

Best practices for delegating tasks to subagents:

• The sweet spot: repetitive tasks requiring judgment
• Core prompt template (5-step structure)
• Batch sizing guidelines
• Complete workflow pattern
• Commit strategies
• Error handling
• Context considerations
• Persona-based routing

Prompt Templates

See references/prompt-templates.md

Proven templates for common patterns:

• Audit/Validation pattern
• Bulk Update pattern
• Research/Comparison pattern
• Migration pattern
• Template customization guidelines
• Authority vs reporting
• Output format consistency

Tool Selection

See references/tool-selection.md

Choosing appropriate tools and managing permissions:

• Available tools in OpenCode
• Tool access principle
• Recommended tool sets by agent type
• Avoiding bash approval spam
• Permission modes and levels
• Bash command permissions
• Task tool permissions
• Configuration examples

Model Selection

See references/model-selection.md

Choosing appropriate models for different agent types:

• Quality-first approach
• Model selection by task type
• Configuration examples
• Temperature settings
• Reasoning model parameters
• Context window considerations
• Cost optimization strategies
• Best practices

Boundary-First Prompting

For specialized agents, define boundaries before workflow details.

• State what the agent owns and what it must not touch
• Specify stop-and-report behavior for out-of-scope work
• Avoid mixed-domain prompts that cause drift into adjacent systems

Boundary-first prompts are more reliable than long capability lists.

Result Contract Design

Every subagent prompt should answer three questions:

1. What should the agent return (summary, JSON, checklist, diff notes)?
2. Who consumes it (user directly or parent orchestrator)?
3. What must be omitted (tool logs, speculative filler, irrelevant narration)?

If this is undefined, multi-agent workflows become noisy and hard to merge.

Quick Reference

Built-in subagents:
  @general  → Full tools, read/write
  @explore  → Read-only, fast exploration

Create agents:
  opencode agent create (interactive)
  .opencode/agents/*.md (markdown)
  opencode.json agent.{name} (JSON)

Config fields:
  description (required) - What and when to use
  mode (required) - "subagent", "primary", or "all"
  model, temperature, tools, permission (optional)

Tool access principle:
  ⚠️ Don't give bash unless agent needs CLI execution
  File creators: read, write, edit, glob, grep (no bash!)
  Script runners: read, write, edit, glob, grep, bash (only if needed)

Model selection (quality-first):
  Default: Standard tier (Sonnet/GPT-4)
  Creative: Premium tier (Opus/GPT-5)
  Scripts only: Fast tier (Haiku/Flash/Mini)
  ⚠️ Avoid fast tier for content - quality drops significantly

Delegation:
  Batch size: 5-8 items per agent
  Parallel: 2-4 agents simultaneously
  Prompt: 5-step (read → verify → check → evaluate → FIX)

Orchestration:
  Enable: Add "task" to agent's tools
  Depth: Keep to 2 levels max
  Use: Multi-phase workflows, parallel specialists

Common Use Cases

Code Review Agent

---
description: Reviews code for quality, security, and best practices. Use after code changes.
mode: subagent
tools:
  read: true
  grep: true
  glob: true
  bash: false
---

You are a senior code reviewer. Focus on:
- Code quality and maintainability
- Security vulnerabilities
- Performance implications
- Best practices adherence

Provide specific, actionable feedback with examples.

Test Runner Agent

{
  "agent": {
    "test-runner": {
      "description": "Runs tests and fixes failures. Use for test-related tasks.",
      "mode": "subagent",
      "tools": {
        "read": true,
        "write": true,
        "edit": true,
        "bash": true
      },
      "permission": {
        "bash": {
          "*": "ask",
          "npm test": "allow",
          "npm run test*": "allow"
        }
      }
    
  

Documentation Writer

---
description: Writes and maintains project documentation
mode: subagent
tools:
  read: true
  write: true
  edit: true
  glob: true
  grep: true
  webfetch: true
---

You are a technical documentation writer.

Create clear, comprehensive documentation using the write and edit tools only.
Focus on clarity, structure, code examples, and user-friendly language.

Release Orchestrator

{
  "agent": {
    "release-orchestrator": {
      "description": "Coordinates release preparation. Use before releases.",
      "mode": "subagent",
      "tools": {
        "read": true,
        "grep": true,
        "glob": true,
        "task": true
      },
      "permission": {
        "task": {
          "code-reviewer": "allow",
          "test-runner": "allow",
          "doc-validator": "allow",
           
        
      
    
  

Best Practices

1. Start minimal: Give agents only essential tools, add more if needed
2. No bash for file creators: Use write/edit tools to avoid approval spam
3. Put tool instructions first: Critical usage rules go at top of prompts
4. Be consistent: Don't show bash examples if you want write tool usage
5. Default to standard tier models: Quality matters more than cost savings
6. Calibrate activation wording: Use normal "Use when..." descriptions by default; reserve "MUST BE USED" for mandatory gates
7. Test before deploying: Run agent with sample tasks to verify behavior
8. Use task permissions: Prevent unintended orchestration with allowlists
9. Keep orchestration shallow: 2 levels max for agent nesting
10. Agents don't commit: Review changes before committing
11. Define hard boundaries early: Put scope and "must not" rules before workflow steps
12. Define result contracts: Make output format and audience explicit
13. Prefer specialized tool routing: Search/read tools for discovery, bash only when execution is required

Performance Considerations

Consideration	Impact
Context efficiency	Subagents preserve main context, enabling longer sessions
Latency	Subagents start fresh, may add latency gathering context
Thoroughness	Explore agent's speed vs completeness tradeoff
Deep operations	Agents with 90+ tool calls work fine for meaningful work