OpenCode Agent Creator

Use this skill when creating OpenCode agents - specialized AI assistants configured for specific tasks and workflows.

When to Use

Use this skill when the user wants to:

•Create new OpenCode agents (primary or subagent)
•Configure specialized AI assistants for specific tasks
•Set up agents with custom prompts, models, and tool access
•Define agent permissions and behaviors

Agent Types

Primary Agents

Main assistants you interact with directly. Users can cycle through them using Tab key or the switch_agent keybind.

Built-in examples:

•Build: Full development with all tools enabled
•Plan: Analysis and planning with restricted permissions

Subagents

Specialized assistants invoked by primary agents or manually via @mention. Used for specific tasks.

Built-in examples:

•General: Multi-step tasks with full tool access (except todo)
•Explore: Fast, read-only codebase exploration

Agent Structure

OpenCode agents can be defined in two ways:

1. Markdown Files (Recommended)

Create .md files in:

•Global: ~/.config/opencode/agents/
•Per-project: .opencode/agents/

Format:

markdown

---
description: Brief description of agent purpose
mode: primary|subagent|all
model: provider/model-id (optional)
temperature: 0.0-1.0 (optional)
maxSteps: number (optional)
tools:
  write: true|false
  edit: true|false
  bash: true|false
permission:
  edit: allow|ask|deny
  bash:
    "*": allow|ask|deny
    "specific command": allow|ask|deny
  webfetch: allow|ask|deny
  task:
    "*": allow|ask|deny
    "agent-name": allow|ask|deny
hidden: true|false (optional, for subagents)
disable: true|false (optional)
---

System prompt content here.
Define the agent's purpose, behavior, and guidelines.

Filename becomes agent name: code-reviewer.md → code-reviewer agent

2. JSON Configuration

Add to opencode.jsonc:

jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "agent-name": {
      "description": "Brief description",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/agent.txt}",
      "temperature": 0.3,
      "maxSteps": 10,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      },
      "permission": {
        "edit": "allow",
        "bash": {
          "*": "ask",
          "git status": "allow"
        }
      }
    }
  }
}

Configuration Options

Required

•description: Brief description of agent's purpose and when to use it

Mode

•
mode: "primary", "subagent", or "all" (default: "all")
- •primary: User-facing agent, switchable via Tab
- •subagent: Invoked by other agents or via @mention
- •all: Can be used as both

Optional

•prompt: Custom system prompt (inline or {file:path})
•model: Override default model (format: provider/model-id)
•
temperature: Control randomness (0.0-1.0)
- •0.0-0.2: Focused/deterministic (code analysis)
- •0.3-0.5: Balanced (general development)
- •0.6-1.0: Creative (brainstorming)
•maxSteps: Maximum agentic iterations before text-only response
•disable: Set true to disable agent
•hidden: Hide subagent from @mention autocomplete (subagents only)

Tools

Control which tools are available:

yaml

tools:
  write: true
  edit: false
  bash: false
  mymcp_*: false  # Wildcard to disable MCP server tools

Permissions

Control what actions require approval:

yaml

permission:
  edit: ask          # ask, allow, or deny
  bash:
    "*": ask         # Default for all commands
    "git status": allow
    "git log*": allow
    "git push": ask
  webfetch: deny
  task:              # Which subagents can be invoked
    "*": deny
    "code-*": allow  # Allow code-prefixed subagents
    "reviewer": ask

Values: "allow" (no approval), "ask" (prompt user), "deny" (disable)

Provider-Specific Options

Any additional options pass through to the provider:

yaml

reasoningEffort: high      # OpenAI reasoning models
textVerbosity: low         # OpenAI reasoning models

Examples

Documentation Writer

markdown

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Security Auditor

markdown

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
permission:
  bash:
    "*": deny
---

You are a security expert. Focus on identifying potential security issues.

Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Code Reviewer

markdown

---
description: Reviews code for best practices and potential issues
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
permission:
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
---

You are a code reviewer. Focus on security, performance, and maintainability.

Review checklist:
1. Code quality and best practices
2. Potential bugs and edge cases
3. Performance implications
4. Security considerations

Provide constructive feedback without making direct changes.

Debug Agent

markdown

---
description: Focused debugging with investigation tools
mode: primary
temperature: 0.2
tools:
  write: false
permission:
  bash:
    "*": allow
  edit: ask
---

You are a debugging specialist. Systematically investigate issues.

Approach:
1. Reproduce the issue
2. Gather relevant logs and context
3. Identify root cause
4. Suggest minimal fix
5. Recommend preventive measures

Deep Thinker (Reasoning Model)

markdown

---
description: High-effort reasoning for complex problems
mode: subagent
model: openai/gpt-5
temperature: 0.1
reasoningEffort: high
textVerbosity: low
maxSteps: 20
---

You solve complex problems with deep reasoning.

For each problem:
1. Break down into components
2. Analyze dependencies
3. Consider edge cases
4. Propose robust solutions
5. Validate approach

Best Practices

•Clear descriptions: Help users and agents understand when to invoke
•Appropriate mode: Choose primary for main work, subagent for specialized tasks
•Tool restrictions: Only enable tools the agent needs
•Permission granularity: Use ask for risky operations, allow for safe ones
•Temperature tuning: Lower for analytical tasks, higher for creative ones
•Prompt clarity: Be specific about agent's role and constraints
•
File location:
- •Global: General-purpose agents across projects
- •Project: Project-specific workflows and conventions

Implementation Steps

When creating an agent:

•
Determine scope:
- •Primary agent for main workflows
- •Subagent for specialized tasks
•
Choose location:
- •Global (~/.config/opencode/agents/) for reusable agents
- •Project (.opencode/agents/) for project-specific agents
•
Define configuration:
- •Required: description, mode
- •Optional: model, temperature, maxSteps, tools, permission
•
Write system prompt:
- •Clear role definition
- •Specific guidelines and constraints
- •Expected behaviors
•
Test the agent:
- •For primary: Switch to it with Tab
- •For subagent: Invoke with @agent-name or let primary agents use it
•
Refine:
- •Adjust temperature based on output quality
- •Fine-tune permissions based on usage
- •Update prompt for better results

Usage

Primary Agents

•Press Tab to cycle through primary agents
•Or use configured switch_agent keybind

Subagents

•Automatic: Primary agents invoke based on descriptions
•Manual: @agent-name message to invoke directly
•Navigation: <Leader>+Right/Left to switch between parent/child sessions

Interactive Creation

Use the built-in command:

bash

opencode agent create

This will:

•Ask for agent location (global/project)
•Request description
•Generate system prompt and identifier
•Let you select tools
•Create markdown file with configuration

Notes

•Markdown filename determines agent name
•Custom agents can work alongside built-in agents
•Agent changes require OpenCode restart
•Model format: provider/model-id (e.g., anthropic/claude-sonnet-4-20250514)
•Hidden subagents (hidden: true) don't appear in autocomplete but can still be invoked programmatically
•Task permissions control which subagents an agent can invoke