opencode-expert

SKILL.md

OpenCode Expert

Comprehensive guide for OpenCode - the open-source AI coding agent.

Quick Reference

Task
Command/Action

Start TUI
opencode

Continue session
opencode -c or opencode --continue

Run non-interactive
opencode run "message"

Start headless server
opencode serve

Web interface
opencode web

Switch agent
Tab key

File search
@ then type filename

Undo changes
/undo

Redo changes
/redo

Share conversation
/share

Initialize project
/init

Configure API keys
/connect

Agents

OpenCode has two primary agents, switchable with Tab:

Build Agent (Default)

Full access to all tools

Can edit files, run commands, make changes

Use for active development work

Plan Agent

Read-only mode for analysis and exploration

File edits and bash commands require approval (ask mode)

Use for reviewing implementation strategy before changes

Subagents

Invoke subagents with @ mention:

@general - Complex research and multi-step tasks with full tool access

@explore - Fast read-only codebase searches and code questions

Keyboard Shortcuts

Key
Action

Tab
Switch between Build and Plan agents

@
Fuzzy file search

Ctrl+C
Cancel current operation

Slash Commands

Command
Description

/connect
Configure LLM provider API keys

/init
Initialize project and create AGENTS.md

/undo
Revert recent changes (stackable)

/redo
Restore undone changes

/share
Create shareable conversation link

CLI Commands

Interactive Mode

# Start TUI in current directory
opencode

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

# Continue previous session
opencode --continue
opencode -c

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

# Start with specific model
opencode --model <model>
opencode -m <model>

# Start with specific agent
opencode --agent build
opencode --agent plan

Non-Interactive Mode

# Run single prompt
opencode run "Fix the bug in auth.py"

# Run with file attachment
opencode run "Review this" --file README.md
opencode run "Review this" -f README.md

# Run and share result
opencode run "Explain this code" --share

# Run specific command
opencode run --command "npm test"

Server Mode

# Start headless API server
opencode serve

# With custom port
opencode serve --port 3000

# With mDNS discovery
opencode serve --mdns

# Web interface
opencode web

Management Commands

# Authentication
opencode auth login
opencode auth list
opencode auth logout

# Models
opencode models              # List available models
opencode models --refresh    # Refresh model cache

# Agents
opencode agent create        # Create custom agent
opencode agent list          # List agents

# MCP servers
opencode mcp add <server>
opencode mcp list
opencode mcp auth
opencode mcp debug

# Sessions
opencode session list
opencode session list -n 10  # Last 10 sessions

# Statistics
opencode stats
opencode stats --days 7
opencode stats --tools
opencode stats --models

# Export/Import
opencode export <sessionID>
opencode import <file>

# Upgrade
opencode upgrade
opencode upgrade <version>

Built-in Tools

OpenCode provides these tools to agents:

Tool
Description

read
Read file contents with optional line ranges

write
Create new files or overwrite existing

edit
Modify files using exact string replacements

patch
Apply patch files

grep
Search file contents with regex

glob
Find files by pattern (**/*.js)

list
List files and directories

bash
Execute shell commands

lsp
Language Server Protocol integration (experimental)

todowrite
Create/update task lists

todoread
Read current todo state

skill
Load skill files into conversation

webfetch
Fetch and read web pages

question
Ask user clarifying questions

Skills

File Locations

Skills are discovered from (in order):

.agents/skills/<name>/SKILL.md (project, shared with Codex)

.claude/skills/<name>/SKILL.md (Claude-compatible project)

~/.config/opencode/skills/<name>/SKILL.md (global)

~/.claude/skills/<name>/SKILL.md (Claude-compatible global)

Skill Format

---
name: my-skill
description: Description of what this skill does and when to use it.
---

# Skill Content

Instructions and documentation here...

Name Rules

Lowercase alphanumeric with single hyphens

Cannot start/end with hyphens

No consecutive hyphens (--)

Must match directory name

Configuration

Config Locations

Project: .opencode/ or opencode.json

Global: ~/.config/opencode/

Environment Variables

Variable
Description

OPENCODE_CONFIG
Custom config path

OPENCODE_PERMISSION
Permission mode

OPENCODE_SERVER_PASSWORD
Server auth password

OPENCODE_DISABLE_AUTOUPDATE
Disable auto-updates

OPENCODE_EXPERIMENTAL
Enable experimental features

OPENCODE_ENABLE_EXA
Enable Exa search

Custom Agents

Create agents via opencode agent create or define in:

opencode.json

~/.config/opencode/agents/

.opencode/agents/

Agent config options: description, temperature, model, tool permissions, system prompts.

Best Practices

Use Plan Mode First

Switch to Plan agent (Tab) to review implementation strategy before making changes.

File References

Use @filename to fuzzy search and reference files in prompts.

Undo Stack

Use /undo liberally - changes are stackable and reversible with /redo.

Session Management

Use --continue or -c to resume previous sessions and maintain context.

References

For detailed documentation, see:

references/cli.md - Complete CLI reference

references/tools.md - Tool details and permissions

references/agents.md - Agent configuration guide