Define specialized agents with precise tool access and permissions.

</overview> <rules>

Agent Fundamentals

Location

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

Agents MAY also be defined in opencode.json:

jsonc

{
  "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

</rules> <guidelines>

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:

yaml

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

</guidelines> <rules>

Permission System

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

Permission Structure

yaml

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:

•Exact match: "npm test": "allow"
•Prefix match: "npm *": "ask"
•Wildcard: "*": "deny"

yaml

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

</rules> <guidelines>

Tools Configuration

Enable or disable specific tools:

yaml

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

</guidelines> <examples>

Agent Archetypes

Analyzer (Read-Only)

yaml

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

Builder (Full Access)

yaml

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

Researcher (Web + Read)

yaml

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

Specialist (Skill-Based)

yaml

---
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:

markdown

---
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]

</examples> <constraints>

Validation

After creating an agent:

bash

opencode run "test"

Then test by routing to it:

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

</constraints>