opencode

What this skill does

# OpenCode — Agent Framework Reference

OpenCode is the AI agent framework running this environment. It manages agents, skills, tools, commands, sessions, providers, and plugins. Everything is configured via files in the config directory (`/opt/opencode/` in the Kortix sandbox, or `.opencode/` in a project).

## Architecture Overview

```
┌─────────────────────────────────────────────────────┐
│  OpenCode                                            │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │  Agents   │  │  Skills   │  │  Tools    │          │
│  │ (.md)     │  │ (SKILL.md)│  │ (.ts)     │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       │              │              │                 │
│  ┌────▼──────────────▼──────────────▼─────┐          │
│  │              Session Engine              │          │
│  │  (prompt → model → tool calls → text)   │          │
│  └────────────────┬───────────────────────┘          │
│                   │                                   │
│  ┌────────────────▼───────────────────────┐          │
│  │            Provider Layer               │          │
│  │  (Anthropic, OpenAI, Kortix router)     │          │
│  └────────────────────────────────────────┘          │
│                                                      │
│  Config: opencode.jsonc  │  Plugins  │  MCP Servers  │
└─────────────────────────────────────────────────────┘
```

---

## Agents

### What is an Agent?

An agent is a **persona** — a system prompt combined with permission rules, model preferences, and behavioral constraints. Defined as `.md` files with YAML frontmatter.

### Agent Definition File

Location: `agents/*.md` or `agents/**/*.md` in the config directory.

```markdown
---
description: "Short description shown in UI and Task tool"
model: provider/model-id
mode: primary
permission:
  bash: allow
  edit: allow
  read: allow
  task: allow
  skill: allow
  # ... tool permissions
---

# Agent Name

System prompt content goes here. This entire markdown body
becomes the agent's system prompt.
```

### Frontmatter Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `description` | string | Yes | Shown in UI and Task tool agent list |
| `mode` | `primary` / `subagent` / `all` | Yes | Controls where the agent appears |
| `model` | string | No | Default model as `provider/model-id` (e.g., `anthropic/claude-opus-4-6`) |
| `permission` | object | No | Tool permission rules (`allow` / `deny` per tool name) |
| `temperature` | number | No | Model temperature |
| `topP` | number | No | Top-P sampling |
| `steps` | number | No | Max tool-use steps per turn |
| `hidden` | boolean | No | Hide from UI |

### Agent Modes

| Mode | User-selectable | Task tool | Use case |
|---|---|---|---|
| `primary` | Yes | Hidden from list, but **can be spawned by name** | Main agent the user interacts with |
| `subagent` | No | Listed and spawnable | Specialist agents for Task tool delegation |
| `all` | Yes | Yes | Available everywhere |

**Key insight:** The Task tool's description filters out `primary` mode agents (`a.mode !== "primary"`), but `Agent.get()` (the execution path) has **no mode guard**. A primary agent CAN self-spawn by name via `subagent_type: "agent-name"`.

### Agent Name Derivation

The agent name is the **filename without `.md`**. For nested paths, only the filename matters:
- `agents/kortix.md` → name: `kortix`
- `agents/specialised/my-agent.md` → name: `my-agent`

### Agent Loading Order

1. Built-in agents (compaction, title, summary — hidden infrastructure)
2. Config directory agents (`agents/*.md`)
3. Config overrides from `opencode.jsonc` `"agent"` section (can disable built-in agents)

### Disabling Built-in Agents

In `opencode.jsonc`:
```json
{
  "agent": {
    "build": { "disable": true },
    "plan": { "disable": true },
    "explore": { "disable": true },
    "general": { "disable": true }
  }
}
```

### Agent Permission System

Permissions control which tools an agent can use. Rules are evaluated per-tool-call:

```yaml
permission:
  bash: allow       # Allow all bash commands
  edit: allow       # Allow file editing
  task: allow       # Allow spawning subagents
  skill: allow      # Allow loading skills
  web-search: allow # Allow web search tool
```

Subagent sessions inherit parent permissions but can have additional restrictions. The Task tool hardcodes `todowrite: deny` and `todoread: deny` for all subagent sessions (lines 77-82 of task.ts).

---

## Skills

### What is a Skill?

A skill is a **knowledge package** — domain-specific instructions, workflows, and resources that inject into the agent's context when loaded via the `skill()` tool. Skills transform a general-purpose agent into a specialist on demand.

### Skill Structure

```
skill-name/
├── SKILL.md          # Required: frontmatter + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: supplementary docs
└── assets/           # Optional: templates, images
```

### SKILL.md Format

```markdown
---
name: my-skill
description: "Detailed description of when to load this skill. Include trigger phrases."
---

# Skill Title

Instructions loaded into context when the skill is triggered.
These become part of the agent's working knowledge.
```

**Frontmatter fields:**
| Field | Required | Description |
|---|---|---|
| `name` | Yes | Skill identifier (used in `skill({ name: "..." })`) |
| `description` | Yes | Trigger description — the agent reads this to decide when to load the skill |

### Skill Discovery

Skills are discovered from multiple locations (loaded in order, later overwrites earlier):

1. **Global external dirs:** `~/.claude/skills/**/SKILL.md`, `~/.agents/skills/**/SKILL.md`
2. **Project external dirs:** Walk up from project dir looking for `.claude/skills/`, `.agents/skills/`
3. **OpenCode config dirs:** `{config}/skills/**/SKILL.md` or `{config}/skill/**/SKILL.md`
4. **Additional paths:** From `opencode.jsonc` `skills.paths` array
5. **URL downloads:** From `opencode.jsonc` `skills.urls` array

### Skill Loading Flow

1. On startup, all `SKILL.md` files are scanned and their **name + description** are extracted (~100 tokens each)
2. These descriptions are included in the `skill` tool's description (available_skills list)
3. The agent reads descriptions and decides when to load a skill
4. When loaded via `skill({ name: "..." })`, the full SKILL.md body is injected into context
5. Bundled files (scripts/, references/) are listed but not loaded — the agent reads them as needed

### How the skill tool works

The `skill` tool (defined in `src/tool/skill.ts`):
1. Lists all accessible skills in its description (filtered by agent permissions)
2. When called with a skill name, reads the full SKILL.md content
3. Returns `<skill_content name="...">` block with the content + skill base directory
4. Also lists up to 10 files in the skill directory for the agent to reference

---

## Tools

### What is a Tool?

A tool is a **capability** the agent can invoke — bash commands, file operations, web search, etc. Tools are defined in TypeScript and registered with the framework.

### Built-in Tools

These are part of OpenCode core:

| Tool | Description |
|---|---|
| `bash` | Execute shell commands |
| `read` | Read files |
| `edit` | Edit files (string replacement) |
| `write` | Write/create files |
| `glob` | File pattern matching |
| `grep` | Content search |
| `task` | Spawn subagent sessions |
| `skill` | Load skills |
| `todowrite` | Manage task list |
| `todoread` | Read task list |
| `question` | Ask user questions |

### Custom Tools

Custom tools are TypeScript files in `tools/*.ts` in the config directory. They use the `Tool.define()` API:

```typescript
import { Tool } from "opencode/tool"
import z from "zod"

export default Tool.define("my-tool", async (ctx) => {
  return {
    description: "What this tool does",