OpenCode Skill

OpenCode is an open source AI coding agent available as a terminal interface (TUI), desktop app, or IDE extension. It enables developers to work on code projects through conversational interactions with intelligent assistance for code explanation, implementation planning, code modification, and more.

Key Value Proposition: A flexible, multi-provider AI assistant with customizable agents, granular permissions, and extensive tool integrations that can be tailored for specific workflows like code review, documentation, security auditing, or development.

When to Use This Skill

Setting up OpenCode for a new development environment
Creating custom agents for specialized coding workflows
Configuring permissions for team-based development
Building automated scripts with OpenCode CLI
Integrating MCP servers for extended capabilities
Troubleshooting OpenCode configuration or tool issues
Comparing OpenCode features with other AI coding assistants

When NOT to Use This Skill

For Claude Code/Claude CLI specific features (different product)
For GitHub Copilot configuration (use copilot-specific docs)
For Cursor IDE settings (different AI editor)
For generic LLM API usage (use provider-specific skills)

Core Concepts

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         OpenCode                                 │
│            Terminal UI / Desktop App / IDE Extension             │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│    Agents     │    │    Tools      │    │  Permissions  │
├───────────────┤    ├───────────────┤    ├───────────────┤
│ • Build       │    │ • read/write  │    │ • allow       │
│ • Plan        │    │ • edit/patch  │    │ • ask         │
│ • Custom...   │    │ • bash        │    │ • deny        │
│ • Subagents   │    │ • grep/glob   │    │ • Wildcards   │
└───────────────┘    │ • webfetch    │    └───────────────┘
                     │ • lsp         │
                     │ • MCP servers │
                     └───────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  LLM Providers │   │   Sessions    │    │   Commands    │
├───────────────┤    ├───────────────┤    ├───────────────┤
│ • OpenAI      │    │ • SQLite      │    │ • /init       │
│ • Claude      │    │ • Persistence │    │ • /undo       │
│ • Gemini      │    │ • Export/     │    │ • /share      │
│ • Groq        │    │   Import      │    │ • Custom...   │
│ • Bedrock     │    └───────────────┘    └───────────────┘
└───────────────┘

Agent Types

| Type | Description | Use Case | |------|-------------|----------| | Primary Agent | Main assistant for direct interaction | Day-to-day development | | Subagent | Specialized assistant for specific tasks | Research, exploration | | Build (built-in) | Full tool access for development | Writing and modifying code | | Plan (built-in) | Read-only for analysis | Planning without changes | | General (subagent) | Multi-step task execution | Research and investigation | | Explore (subagent) | Codebase navigation | Quick file/code searching |

Installation

Quick Install (Recommended)

# Install script
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# Homebrew (macOS/Linux)
brew install opencode-ai/tap/opencode

# npm
npm install -g opencode

# Go
go install github.com/opencode-ai/opencode@latest

Verify Installation

opencode --version

Configuration

Configuration Files

OpenCode uses opencode.json in your project root or global config at ~/.config/opencode/:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "agent": {
    "build": {
      "model": "claude-sonnet-4-20250514"
    },
    "plan": {
      "model": "claude-sonnet-4-20250514",
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Environment Variables

# API Keys (choose your provider)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."
export GROQ_API_KEY="..."

# OpenCode Settings
export OPENCODE_CONFIG="~/.config/opencode/opencode.json"
export OPENCODE_PERMISSION="ask"  # Default permission level
export OPENCODE_AUTO_SHARE="true"  # Auto-share sessions
export OPENCODE_EXPERIMENTAL_LSP_TOOL="true"  # Enable LSP

Tools Reference

Built-in Tools

| Tool | Description | Permission | |------|-------------|------------| | read | Read file contents from codebase | allow | | write | Create or overwrite files | edit | | edit | Modify files using exact string replacements | edit | | patch | Apply patch files to code | edit | | grep | Search file contents using regex | allow | | glob | Find files by pattern (e.g., **/*.js) | allow | | list | List files and directories | allow | | bash | Execute shell commands | ask | | webfetch | Fetch and read web pages | ask | | lsp | Language Server Protocol (experimental) | allow | | skill | Load SKILL.md file content | allow | | question | Ask user questions during execution | allow | | todoread/todowrite | Task tracking during sessions | allow |

Tool Configuration

{
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "list": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    }
  }
}

Creating Custom Agents

Interactive Creation

opencode agent create

This guides you through:

Selecting storage location (global or project)
Defining agent purpose
Auto-generating system prompts
Choosing accessible tools
Creating markdown configuration

Agent Configuration (JSON)

{
  "agent": {
    "reviewer": {
      "description": "Code review specialist",
      "mode": "subagent",
      "model": "claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": ".opencode/agent/reviewer.md",
      "tools": {
        "read": true,
        "grep": true,
        "glob": true,
        "edit": false,
        "bash": false
      },
      "permission": {
        "webfetch": "deny"
      },
      "maxSteps": 20
    }
  }
}

Agent Configuration (Markdown)

Create .opencode/agent/reviewer.md:

---
description: Code review specialist for quality and security
mode: subagent
model: claude-sonnet-4-20250514
temperature: 0.3
tools:
  read: true
  grep: true
  glob: true
  edit: false
  bash: false
---

You are a code review specialist focused on:

1. Code quality and best practices
2. Security vulnerabilities
3. Performance issues
4. Maintainability concerns

When reviewing code:
- Identify issues by severity (critical, major, minor)
- Provide specific line references
- Suggest concrete improvements
- Consider the project's existing patterns

Agent Parameters

| Parameter | Type | Description | |-----------|------|-------------| | description | string | Brief explanation (required) | | mode | string | primary, subagent, or all | | model | string | Override default model | | temperature | float | Response randomness (0.0-1.0) | | prompt | string | Path to system prompt file | | tools | object | Enable/disable specific tools | | permission | object | Override permissions | | maxSteps | number | Limit iterations before text-only |

Custom Commands

Command Structure

Create .opencode/command/review.md:

---
description: Review code changes
agent: reviewer
---

Review the following code changes:

$ARGUMENTS

Focus on:
1. Security vulnerabilities
2. Performance issues
3. Code style violations
4. Missing tests

Using Arguments

---
description: Create a component
---

Create a new React component named $1 in the $2 directory.

Requirements:
- TypeScript
- Styled with Tailwind
- Include tests

Usage: /component Button components/ui

Including Shell Output

---
description: Review recent changes
---

Review the following git diff:

`!git diff HEAD~1`

Summarize changes and identify any issues.

File References

---
description: Explain architecture
---

Based on the architecture documentation:

@ARCHITECTURE.md

Explain how the authentication system works.

CLI Reference

TUI Mode (Default)

# Start in current directory
opencode

# Start in specific project
opencode /path/to/project

# Continue last session
opencode --continue

# Use specific session
opencode --session <session-id>

# Override model
opencode --model claude-sonnet-4-20250514

Non-Interactive Mode

# Run single prompt
opencode run "explain this codebase"

# Run with file context
opencode run --file src/main.ts "add error handling"

# Run custom command
opencode run --command review

# Output format
opencode run --format json "list all functions"

Server Mode

# Start headless server
opencode serve --port 8080

# Start with web interface
opencode web --port 8080

# Connect to remote server
opencode attach http://localhost:8080

Agent Management

# Create new agent
opencode agent create

# List all agents
opencode agent list

MCP Integration

# Add MCP server
opencode mcp add <server-name>

# List MCP servers
opencode mcp list

# Debug MCP connection
opencode mcp debug <server-name>

Session Management

# List sessions
opencode session list --max-count 10

# Export session
opencode export <session-id>

# Import session
opencode import session.json

# View usage stats
opencode stats --days 7

Project Initialization

Generate AGENTS.md

opencode
/init

This analyzes your project and generates AGENTS.md containing:

Project structure overview
Key patterns and conventions
Technology stack
Important files and directories

Best Practice: Commit AGENTS.md to version control so OpenCode understands your codebase.

Permissions System

Permission Levels

| Level | Behavior | |-------|----------| | allow | Executes without approval | | ask | Prompts for user approval | | deny | Blocks execution |

Approval Responses

When prompted:

once - Approve single request
always - Approve matching requests for session
reject - Deny the request

Default Permissions

Most tools default to allow, except:

doom_loop - ask (safety feature)
external_directory - ask (safety feature)
.env* files - deny (security)

Agent-Level Overrides

Agent permissions take precedence over global:

{
  "permission": {
    "bash": "ask"
  },
  "agent": {
    "build": {
      "permission": {
        "bash": "allow"
      }
    }
  }
}

Common Use Cases

Code Review Agent

---
description: Systematic code review
mode: subagent
tools:
  read: true
  grep: true
  edit: false
  bash: false
---

You are a code reviewer. For each review:

1. Check for security vulnerabilities
2. Identify performance bottlenecks
3. Ensure code follows project patterns
4. Verify test coverage
5. Suggest improvements

Format findings as:
- CRITICAL: [issue]
- MAJOR: [issue]
- MINOR: [issue]

Documentation Agent

---
description: Documentation writer
mode: subagent
tools:
  read: true
  glob: true
  write: true
  bash: false
---

You write clear, comprehensive documentation.

When documenting:
1. Follow project's existing doc style
2. Include code examples
3. Document edge cases
4. Keep language accessible

Security Audit Agent

---
description: Security vulnerability scanner
mode: subagent
tools:
  read: true
  grep: true
  bash: false
  webfetch: true
---

You are a security auditor. Scan for:

1. Injection vulnerabilities (SQL, XSS, command)
2. Authentication/authorization issues
3. Sensitive data exposure
4. Insecure dependencies
5. Misconfigurations

Reference OWASP Top 10 for classification.

Troubleshooting

Agent Not Invoking

Issue: Custom agent doesn't respond to @mention

Solutions:

Verify agent file is in correct location (.opencode/agent/ or ~/.config/opencode/agent/)
Check mode is set correctly (subagent for @mentions)
Ensure YAML frontmatter is valid
Try opencode agent list to verify registration

Permission Denied

Issue: Tool execution blocked unexpectedly

Solutions:

Check global permissions in opencode.json
Verify agent-specific overrides
Use opencode run --permission allow for testing
Check for conflicting wildcard patterns

Tool Not Working

Issue: grep/glob returns no results

Solutions:

Check if files are in .gitignore (excluded by default)
Create .ignore file to include ignored directories
Verify pattern syntax is correct

LLM Connection Issues

Issue: Provider not responding

Solutions:

Verify API key is set correctly
Check network connectivity
Run opencode models to list available models
Try opencode models --refresh to refresh cache

Resources

Official Documentation

Source Code

GitHub Repository

Related Projects

Charm - Terminal UI framework
MCP Protocol - Model Context Protocol

Version History

1.0.0 (2026-01-12): Initial skill release
- Complete OpenCode agent system documentation
- Built-in and custom agent configuration
- Tools reference with permission system
- CLI commands and usage patterns
- Custom commands and SKILL.md integration
- MCP server integration
- Common agent templates (review, docs, security)
- Troubleshooting guide