# Opencode Agents

> |

- **Type:** Skill
- **Install:** `agentstack add skill-timmy6942025-opencode-builder-skill-opencode-agents`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Timmy6942025](https://agentstack.voostack.com/s/timmy6942025)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Timmy6942025](https://github.com/Timmy6942025)
- **Source:** https://github.com/Timmy6942025/opencode-builder-skill/tree/main/skills/opencode-agents

## Install

```sh
agentstack add skill-timmy6942025-opencode-builder-skill-opencode-agents
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenCode Agents — Complete Reference

> **📚 Official Docs:** For the latest information, always refer to the official documentation:
> [https://opencode.ai/docs/agents/](https://opencode.ai/docs/agents/)

OpenCode supports a multi-agent architecture where specialized AI assistants handle different aspects of development. Agents come in two types — **primary agents** (direct user interaction, switchable via Tab) and **subagents** (invoked by other agents or via `@mention`/Task tool). There are also **hidden agents** (internal-use only, not user-selectable).

This guide covers every agent type, all built-in agents, every configuration option, the complete permission system, and how to create custom agents.

---

## 1. Agent Types

### Primary Agents

Primary agents are the main assistants you interact with directly. They appear in the agent selector and can be cycled through using the **Tab** key (or your configured `switch_agent` keybind). Each primary agent has its own system prompt, tool permissions, temperature, and behavioral configuration.

OpenCode ships with two built-in primary agents: **Build** and **Plan**.

Primary agents are suitable for:
- Direct user conversation and coding
- Multi-step development tasks
- Planning and architecture analysis
- Read-only exploration

You can switch between primary agents mid-session by pressing **Tab**.

### Subagents

Subagents are specialized assistants that primary agents can invoke for specific tasks. They run in isolated contexts and return results to the invoking agent. You can invoke them:

- **Automatically** — the primary agent decides when to delegate based on subagent descriptions
- **Manually** — by `@mentioning` them in your message (e.g., `@explore find all auth functions`)
- **Programmatically** — via the Task tool from another agent's configuration

OpenCode ships with three built-in subagents: **General**, **Explore**, and **Scout**.

### Hidden Agents

Hidden agents are internal system agents not visible in the UI or `@` autocomplete. They handle behind-the-scenes operations and run automatically when triggered by system events. You cannot select them directly, but they perform critical maintenance functions.

OpenCode ships with three hidden agents: **Compaction**, **Title**, and **Summary**.

---

## 2. Built-in Agents (Complete Reference)

### Build — Primary Agent

| Property | Value |
|----------|-------|
| **Mode** | `primary` |
| **Tools** | All enabled |
| **Default temperature** | Model default (typically 0) |
| **Use case** | General development, file creation, editing, debugging, building features |

Build is the **default** primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations, system commands, and all available tools. It is the agent you will use for most coding tasks.

**What it can do:**
- Read, write, and edit any file in the project
- Run any shell command
- Search codebases with glob and grep
- Fetch external URLs and web pages
- Invoke subagents via the Task tool
- Load and use skills
- Ask the user questions

**Configuration (built-in defaults):**
```json
{
  "agent": {
    "build": {
      "description": "Default build agent with all tools",
      "mode": "primary"
    }
  }
}
```

### Plan — Primary Agent

| Property | Value |
|----------|-------|
| **Mode** | `primary` |
| **Tools** | All read tools enabled; edit and bash set to `ask` |
| **Default temperature** | Model default (typically 0) |
| **Use case** | Code analysis, planning, architecture review, reconnaissance |

A restricted agent designed for planning and analysis. By default, all file edits and bash commands are set to `ask` mode, meaning they require user confirmation before execution. This agent excels at reading code, analyzing architecture, and producing plans without making unintended changes.

**What it can do:**
- Read any file in the project
- Search with glob and grep
- Suggest changes (but requires approval to apply them)
- Run bash commands (requires approval)
- Fetch external documentation

**What it cannot do without approval:**
- Edit or write files
- Execute bash commands

**Configuration (built-in defaults):**
```json
{
  "agent": {
    "plan": {
      "description": "Restricted agent for planning and analysis",
      "mode": "primary",
      "permission": {
        "edit": "ask",
        "bash": "ask"
      }
    }
  }
}
```

### General — Subagent

| Property | Value |
|----------|-------|
| **Mode** | `subagent` |
| **Tools** | All enabled except todo |
| **Default temperature** | Model default |
| **Use case** | Complex delegated tasks, multi-file refactors, bulk operations |

A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access (except todo), so it can make file changes when needed. Use this to run multiple units of work in parallel.

**What it can do:**
- Read, write, and edit files
- Run shell commands
- Search codebases
- Fetch external URLs
- Load skills
- Ask the user questions

**What it cannot do:**
- Write to the todo list

**Invocation:**
```
@general help me refactor the authentication module
```

### Explore — Subagent

| Property | Value |
|----------|-------|
| **Mode** | `subagent` |
| **Tools** | read, grep, glob, webfetch (no edit, write, or bash) |
| **Default temperature** | Model default |
| **Use case** | Fast codebase exploration, finding definitions, understanding architecture |

A fast, read-only agent for exploring codebases. Cannot modify files. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase without any risk of changes.

**What it can do:**
- Read files (with line ranges)
- Search with glob patterns (`**/*.ts`, etc.)
- Search content with grep (regex)
- Fetch external URLs for documentation

**What it cannot do:**
- Write or edit any files
- Run shell commands
- Load skills

**Invocation:**
```
@explore find all TypeScript files that handle user authentication
```

### Scout — Subagent

| Property | Value |
|----------|-------|
| **Mode** | `subagent` |
| **Tools** | webfetch, read, grep, glob (no edit, write, or bash) |
| **Default temperature** | Model default |
| **Use case** | External documentation, dependency research, cross-referencing upstream code |

A read-only agent for external docs and dependency research. Use this when you need to clone a dependency repository into OpenCode's managed cache, inspect library source code, or cross-reference local code against upstream implementations without modifying your workspace.

**What it can do:**
- Fetch and read external URLs (documentation, GitHub repos, API references)
- Read files in OpenCode's managed cache
- Search cached content with grep and glob

**What it cannot do:**
- Write or edit files in the project
- Run shell commands
- Load skills

**Invocation:**
```
@scout look up the latest Stripe API docs for payment intents
```

### Compaction — Hidden Primary Agent

| Property | Value |
|----------|-------|
| **Mode** | `primary` (hidden) |
| **Tools** | System-managed |
| **Use case** | Automatic context window compaction |

Handles context window compaction when conversations grow too long. Automatically summarizes older messages to preserve context while staying within token limits. Runs automatically when the context window approaches its limit. Not selectable in the UI.

**Trigger:** Automatic when context window is near capacity.

**Behavior:** Compacts the conversation history by summarizing older messages into a condensed form, preserving the most important context for continued work.

### Title — Hidden Primary Agent

| Property | Value |
|----------|-------|
| **Mode** | `primary` (hidden) |
| **Tools** | System-managed |
| **Use case** | Automatic session title generation |

Generates short session titles based on conversation content. Runs automatically to create descriptive names for chat sessions, making it easier to identify and navigate between sessions. Not selectable in the UI.

**Trigger:** Automatic when a new session starts or after initial messages.

**Behavior:** Analyzes the conversation and produces a concise title (typically 3-7 words) that captures the session's purpose.

### Summary — Hidden Primary Agent

| Property | Value |
|----------|-------|
| **Mode** | `primary` (hidden) |
| **Tools** | System-managed |
| **Use case** | Session persistence and resumption |

Creates session summaries for persistence and retrieval. Used when saving or loading session state. Not selectable in the UI.

**Trigger:** Automatic during session save/persistence operations.

**Behavior:** Generates a structured summary of the session's key points, decisions, and outcomes for later retrieval.

---

## 3. Configuration Methods

Agents can be configured through two methods: JSON configuration in `opencode.json` or Markdown files in agent directories.

### JSON Configuration

Define agents in the `agent` field of `opencode.json`. This method is best for simple agent definitions and quick overrides of built-in agents.

**Project-level config** (`.opencode/config.json`):
```json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "description": "Custom build agent",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.7,
      "steps": 100
    },
    "plan": {
      "description": "Custom plan agent",
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "ask",
        "bash": "ask"
      }
    }
  }
}
```

**Global config** (`~/.config/opencode/config.json`):
```json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "model": "openai/gpt-5"
    }
  }
}
```

### Markdown Files

Create agent definitions as Markdown files in one of these directories:

- **Global:** `~/.config/opencode/agents/` — available in all projects
- **Per-project:** `.opencode/agents/` — available only in the current project

Each Markdown file defines a single agent. The **filename (without extension)** becomes the agent name. For example, `review.md` creates a `review` agent.

**Markdown file structure:**
```markdown
---
description: What this agent does and when to use it
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
steps: 50
permission:
  read: "allow"
  edit: "ask"
  bash: "ask"
  glob: "allow"
  grep: "allow"
  webfetch: "allow"
  task: "allow"
color: "#ef4444"
hidden: false
---

You are a specialized agent. Your system prompt goes here.

Instructions and behavioral guidelines for the agent.
```

**Example: `.opencode/agents/security.md`**
```markdown
---
description: Security-focused agent that audits code for vulnerabilities
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
steps: 50
permission:
  edit: "deny"
  bash: "ask"
  read: "allow"
  webfetch: "allow"
  glob: "allow"
  grep: "allow"
color: "#ef4444"
---

You are a security auditor. Your role is to:

1. Scan code for common vulnerabilities (SQL injection, XSS, CSRF, etc.)
2. Check for hardcoded secrets and credentials
3. Review authentication and authorization patterns
4. Assess dependency security
5. Report findings with severity ratings

Never modify files. Read-only analysis only.
```

### CLI Creation

Use the `opencode agent create` command to create a new agent interactively:

```bash
opencode agent create
```

This launches an interactive prompt that:
1. Asks where to save the agent (global or project-specific)
2. Asks for a description of what the agent should do
3. Generates an appropriate system prompt and identifier
4. Lets you select which permissions the agent should be allowed (anything not selected is denied)
5. Creates a Markdown file with the agent configuration

The file is saved to either `~/.config/opencode/agents/` (global) or `.opencode/agents/` (project).

---

## 4. All Agent Options (Complete Reference)

### description (required)

A plain-text description of what the agent does and when to use it. This appears in the agent selector UI and is used by the system to understand the agent's purpose (including for automatic subagent selection).

```json
{
  "description": "Reviews code for best practices and potential issues"
}
```

```json
{
  "description": "Database administration agent for migrations and queries"
}
```

**In Markdown files:**
```yaml
---
description: Writes and maintains project documentation
---
```

### mode

Controls how the agent is accessed. Values:

| Value | Behavior |
|-------|----------|
| `"primary"` | Appears in Tab cycle, directly selectable by user |
| `"subagent"` | Invoked via `@mention` or Task tool |
| `"all"` | Available both as primary and subagent (default) |

```json
{
  "mode": "subagent"
}
```

```json
{
  "mode": "primary"
}
```

If no `mode` is specified, it defaults to `"all"`.

### model

Override the model used by this agent. Format: `provider/model-id`.

If you don't specify a model:
- **Primary agents** use the globally configured model
- **Subagents** inherit the model of the primary agent that invoked them

```json
{
  "model": "anthropic/claude-sonnet-4-20250514"
}
```

```json
{
  "model": "openai/gpt-5"
}
```

```json
{
  "model": "opencode/gpt-5.1-codex"
}
```

Use `opencode models` to see available models.

### temperature

Controls randomness and creativity of the LLM's responses. Range: `0.0` to `1.0`.

| Range | Behavior | Best for |
|-------|----------|----------|
| `0.0` - `0.2` | Very focused, deterministic | Code analysis, planning, debugging |
| `0.3` - `0.5` | Balanced with some creativity | General development tasks |
| `0.6` - `1.0` | Creative and varied | Brainstorming, exploration, creative writing |

```json
{
  "temperature": 0.3
}
```

If no temperature is specified, OpenCode uses model-specific defaults (typically `0` for most models, `0.55` for Qwen models).

```json
{
  "agent": {
    "analyze": { "temperature": 0.1 },
    "build": { "temperature": 0.3 },
    "brainstorm": { "temperature": 0.7 }
  }
}
```

### steps

Maximum number of agentic iterations (tool calls) before the agent is forced to produce a text-only response. Prevents infinite loops and controls task scope and cost.

```json
{
  "steps": 100
}
```

When the limit is reached, the agent receives a special system prompt instructing it to respond with a summarization of its work and recommended remaining tasks.

If not set, the agent continues to iterate until the model chooses to stop or the user interrupts.

> **Note:** The legacy `maxSteps` field is deprecated. Use `steps` instead.

### disable

Set to `true` to completely disable an agent. The agent will not appear anywhere in the UI.

```json
{
  "disable": true
}
```

### prompt

Path to a custom system prompt file. Supports the `{file:...}` syntax to reference files relative to the config file location (works for both global and project config).

```json
{
  "prompt": "{file:./prompts/code-review.txt}"
}
```

```json
{
  "prompt": "{file:.opencode/prompts/db-migrator.md}"
}
```

In **Markdown agent files**, the body content after the frontmatter becomes the system prompt directly — no separate file needed.

### tools (deprecated)

> **Deprecated:** Use `permission` instead. The `tools` config is still supported for backwards compatibility but may be removed in a future version.

Enable or disable specific tools. `true` is equivalent to `{"*": "allow"}` permission; `false` is equivalent to `{"*": "deny"}`.

```json
{
  "tools": {
    "write": true,
    "bash": true,
    "webfetch": false
  }
}
```

Agent-specific `tools` override the global config. Supports wildcards:

```json
{
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}
```

### permission

Granular permissio

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Timmy6942025](https://github.com/Timmy6942025)
- **Source:** [Timmy6942025/opencode-builder-skill](https://github.com/Timmy6942025/opencode-builder-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-timmy6942025-opencode-builder-skill-opencode-agents
- Seller: https://agentstack.voostack.com/s/timmy6942025
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.