opencode-agents - SKILL.md Agent Skill

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:

Exact match: "npm test": "allow"
Prefix match: "npm *": "ask"
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