# Opencode Agents

> 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

- Skill: `jal-co/opencode-agents` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jal-co/opencode-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jal-co/opencode-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jal-co (https://skillmd.com/u/jal-co)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jal-co/opencode-agents

---


<overview>

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:
1. Exact match: `"npm test": "allow"`
2. Prefix match: `"npm *": "ask"`
3. 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>