opencode-agents

name

opencode-agents

description

Define and configure OpenCode agents with proper permissions, tools, and behaviors. Use for agent creation, tool access control, permission patterns, and mode selection. Use proactively when user says "create an agent", "agent permissions", "tool access", "subagent", "restrict agent", or asks about agent configuration. Examples: - user: "Create a security reviewer agent" → design agent with read-only permissions, appropriate skills - user: "How do I restrict bash access?" → explain permission.bash patterns with allow/ask/deny - user: "Make an agent use the question tool" → configure tools.question: "enabled" or ensure no tools restrictions - user: "What's the difference between primary and subagent?" → explain mode options

Define specialized agents with precise tool access and permissions.

Agent Fundamentals

Location

Scope	Path
Project	.opencode/agent/<name>.md
Global	~/.config/opencode/agent/<name>.md

Agents MAY also be defined in opencode.json:

{
  "agent": {
    "my-agent": {
      "description": "Brief description",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}

Frontmatter Schema

Field	Type	Default	Description
description	string	REQUIRED	Trigger description (see below)
mode	string	"all"	primary, subagent, or all
model	string	inherited	Model override (e.g., anthropic/claude-opus-4-5)
temperature	number	1.0	0.0-2.0, lower = deterministic
maxSteps	number	100	Maximum tool calls per turn
disable	boolean	false	Disable without deleting
tools	object	all enabled	Tool-specific enable/disable
permission	object	all allowed	Permission restrictions

Agent Modes

Mode	Visible in Menu	Task Tool Target	Use Case
primary	Yes	No	User-facing, main agents
subagent	No	Yes	Orchestrated by other agents
all	Yes	Yes	Versatile, both contexts

Description Guidelines

Mode	Description Style
primary	3 words max (shown in TUI menu)
subagent	MUST include trigger examples for task tool routing
all	Both: short label + trigger examples

Subagent description example:

description: |-
  Security vulnerability scanner. Use for code audits, dependency checks, and security reviews.
  
  Examples:
  - user: "Review this code for security issues" → scan for vulnerabilities
  - user: "Check for hardcoded secrets" → search for credentials

Permission System

CRITICAL: By default, agents have ALL tools and permissions. Only add permission blocks to RESTRICT access.

Permission Structure

permission:
  edit: "deny"           # deny all file edits
  bash: 
    "*": "ask"           # ask before any bash
    "npm test": "allow"  # but allow npm test
    "rm -rf *": "deny"   # never allow rm -rf
  webfetch: "allow"      # allow web fetching
  skill:
    "*": "deny"          # deny all skills by default
    "security-*": "allow" # allow security-prefixed skills

Permission Levels

Level	Behavior
allow	Execute without confirmation
ask	Prompt user before executing
deny	Block entirely

Bash Pattern Matching

Patterns are matched in order of specificity:

1. Exact match: "npm test": "allow"
2. Prefix match: "npm *": "ask"
3. Wildcard: "*": "deny"

permission:
  bash:
    "*": "deny"              # Default deny
    "git *": "allow"         # Allow git commands
    "npm *": "allow"         # Allow npm commands
    "rm *": "ask"            # Ask for rm
    "rm -rf *": "deny"       # MUST NOT allow rm -rf

Tools Configuration

Enable or disable specific tools:

tools:
  question: "enabled"    # Force enable question tool
  webfetch: "disabled"   # Disable web fetching
  task: "disabled"       # Prevent delegation

Key Tools

Tool	Purpose
question	Interactive Q&A with user (clarification)
delegate	Async background task delegation
task	Sync subagent delegation
todowrite	Task list management
todoread	Read current task list
skill	Load specialized skills

Agent Archetypes

Analyzer (Read-Only)

---
description: Code analysis expert
mode: subagent
temperature: 0.1
permission:
  edit: "deny"
  bash:
    "*": "deny"
    "git log *": "allow"
    "git diff *": "allow"
---

Builder (Full Access)

---
description: Implementation specialist
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.4
---
# No permission block = full access

Researcher (Web + Read)

---
description: Documentation researcher
mode: subagent
temperature: 0.2
permission:
  edit: "deny"
  bash:
    "*": "deny"
---

Specialist (Skill-Based)

---
description: |-
  Security vulnerability scanner. Use for audits and reviews.
mode: subagent
temperature: 0.2
permission:
  edit: "deny"
  bash:
    "*": "deny"
  skill:
    "*": "deny"
    "security-*": "allow"
---

System Prompt Structure

The markdown body becomes the agent's system prompt:

---
description: My agent
mode: primary
---

# Role

You are a [specific role] specializing in [domain].

## Objective

[Clear mission statement]

## Instructions

- MUST [required behavior]
- SHOULD [recommended behavior]
- MAY [optional behavior]
- MUST NOT [prohibited behavior]

## Workflow

1. [First step]
2. [Second step]
3. [Third step]

## Output Format

[Expected output structure]

Validation

After creating an agent:

opencode run "test"

Then test by routing to it:

• If primary: Select from agent menu
• If subagent: Use task tool to invoke