---
name: opencode-interaction
description: This skill provides comprehensive guidance for configuring, managing, and interacting with OpenCode. Use it when configuring agents, managing MCP servers, creating skills, setting up permissions, or troubleshooting opencode.json.
---

# OpenCode Interaction

This skill covers everything about OpenCode configuration — the agent runtime that powers this project. Use it whenever you need to modify `opencode.json`, set up MCP servers, create or enable skills, configure agents, or understand the OpenCode ecosystem.

## Core Concepts

OpenCode is a terminal-first AI coding agent. It uses a configuration file (`opencode.json`) that defines:

- **Agents** — Named agent instances with prompts, models, permissions
- **Skills** — Modular knowledge packages loaded on demand
- **MCPs** — Model Context Protocol servers connecting to external services
- **Tools** — Built-in capabilities (read, write, bash, glob, grep, webfetch)
- **Plugins** — Extensions like rate-limit-fallback
- **Permissions** — Granular allow/deny rules per agent

## Configuration File: opencode.json

### Root-Level Fields

| Field | Type | Description |
|-------|------|-------------|
| `$schema` | string | Schema URL: `https://opencode.ai/config.json` |
| `agent` | object | Named agent definitions |
| `skills` | object | Skill sources and enabled skills |
| `mcp` | object | MCP server definitions |
| `tools` | object | Built-in tool enable/disable |
| `permission` | object | Default permission rules |
| `plugin` | string\|array | Plugin configuration |
| `model` | string | Default model override |
| `autoupdate` | boolean | Auto-update OpenCode |
| `keybinds` | object | Keyboard shortcuts |

### Agent Definition

```json
{
  "agent": {
    "agent-name": {
      "mode": "primary",
      "model": "opencode/minimax-m2.5-free",
      "temperature": 0.0,
      "steps": 1000000,
      "permission": {
        "read": "allow",
        "edit": "allow",
        "write": "allow",
        "bash": "allow",
        "glob": "allow",
        "grep": "allow",
        "skill": { "*": "allow" },
        "tool": { "*": "allow" },
        "task": { "*": "allow" }
      },
      "prompt": "{file:./AGENT.md}",
      "description": "What this agent does",
      "color": "#8E44AD"
    }
  }
}
```

### Permission Model

Permissions cascade: root → agent. Agent permissions override root.

| Permission | Values | Description |
|------------|--------|-------------|
| `read` | `"allow"` / `"deny"` | Read files |
| `edit` | `"allow"` / `"deny"` | Edit/write files |
| `write` | `"allow"` / `"deny"` | Write new files |
| `bash` | `"allow"` / `"deny"` | Execute shell commands |
| `glob` | `"allow"` / `"deny"` | File pattern matching |
| `grep` | `"allow"` / `"deny"` | Content search |
| `webfetch` | `"allow"` / `"deny"` | Fetch web URLs |
| `skill` | `{ "name": "allow"/"deny", "*": "deny" }` | Per-skill permissions |
| `tool` | `{ "name": "allow"/"deny", "*": "deny" }` | Per-tool permissions |
| `task` | `{ "name": "allow"/"deny", "*": "deny" }` | Per-task permissions |

**Pattern:** Use `"*": "deny"` as default, then explicitly allow what's needed.

### Skills Configuration

```json
{
  "skills": {
    "sources": ["./skills", "./other-skills"],
    "enable": ["skill-name-1", "skill-name-2"]
  }
}
```

Skills are loaded from `sources` paths. Only skills listed in `enable` are activated.

### MCP Server Configuration

Two types of MCP servers:

**Remote MCP (HTTP/HTTPS):**
```json
{
  "mcp": {
    "server-name": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "API_KEY_HEADER": "{env:ENV_VAR_NAME}"
      },
      "enabled": true
    }
  }
}
```

**Local MCP (child process):**
```json
{
  "mcp": {
    "server-name": {
      "type": "local",
      "command": ["npx", "-y", "@package/mcp-server", "--flag", "value"],
      "enabled": true
    }
  }
}
```

**Tool filter pattern (optional):**
```json
{
  "mcp": {
    "server-name": {
      "type": "remote",
      "url": "https://...",
      "enabled": true,
      "tools": {
        "tool_name": "allow",
        "tool_*": "deny"
      }
    }
  }
}
```

### Plugin Configuration

```json
{
  "plugin": [
    "@azumag/opencode-rate-limit-fallback"
  ]
}
```

Or with sources:
```json
{
  "plugins": {
    "sources": [],
    "enable": [
      "superpowers@git+https://github.com/obra/superpowers.git"
    ]
  }
}
```

## Available Models

Reference `references/models.md` or use these model categories:

| Category | Models | Use Case |
|----------|--------|----------|
| Free & Fast | `opencode/minimax-m2.5-free`, `opencode/gpt-5-nano` | Light tasks, quick responses |
| Balanced | `opencode/deepseek-v4-flash-free`, `llmgateway/gemini-2.5-flash` | General purpose |
| Powerful | `opencode/big-pickle`, `llmgateway/claude-opus-4.6` | Complex reasoning |
| Reasoning | `llmgateway/o3`, `huggingface/deepseek-ai/DeepSeek-R1-0528` | Analysis & logic |

## Common MCP Servers

| Server | Type | Description |
|--------|------|-------------|
| **context7** | remote | Up-to-date library documentation (`npx ctx7 setup --opencode`) |
| **github** | remote | GitHub API (`npx -y @modelcontextprotocol/server-github`) |
| **filesystem** | local | Filesystem operations |
| **gitlab** | remote | GitLab API |
| **pencil** | local | VS Code extension MCP |
| **sentry** | remote | Sentry error tracking (OAuth) |
| **grep** | remote | Vercel Grep — search GitHub code snippets |

## Skill Management

### Where Skills Live

- **Local (per-agent):** `<agent-dir>/.opencode/skills/<skill-name>/SKILL.md`
- **Global:** `~/.config/opencode/skills/<skill-name>/SKILL.md`

### Skill Anatomy

```
skill-name/
├── SKILL.md              ← Required: YAML frontmatter + markdown instructions
├── scripts/              ← Optional: executable code (Python/Bash)
├── references/           ← Optional: reference docs loaded as needed
└── assets/               ← Optional: output files (templates, images)
```

### Creating a Skill

1. Create directory: `mkdir -p .opencode/skills/<skill-name>/`
2. Write `SKILL.md` with YAML frontmatter (`name`, `description`)
3. Add optional `scripts/`, `references/`, `assets/`
4. Enable in `opencode.json`: `"skills": { "sources": [".opencode/skills"], "enable": ["skill-name"] }`

### Installing Skills

- **From skills.sh:** `npx skills add <owner/repo@skill> -y`
- **From global index:** Copy skill folder into `.opencode/skills/` and enable it
- **Local init:** `npx skills init <skill-name>`

## Project Structure Conventions

Standard `.opencode/` directory layout:
```
.opencode/
├── opencode.json         ← Main configuration
├── PROMPT.md             ← Project-level instructions (loaded via {file:})
├── skills/               ← Custom skills
│   └── skill-name/
│       └── SKILL.md
└── agents/               ← Agent prompts
    └── agent-name.md
```

## Tips

1. **Use `{env:VAR_NAME}`** in configs to reference environment variables (e.g., for API keys)
2. **OAuth MCP servers** can be authenticated via `opencode mcp auth <server-name>`
3. **Use `"permission": "allow"`** at root to allow everything, then restrict per-agent
4. **Skills auto-trigger** based on their `name` and `description` in YAML frontmatter matching user intent
5. **Tool filtering** lets you enable/disable specific tools from an MCP server using glob patterns