opencode-expert

Original：🇺🇸 English

Translated

This skill provides comprehensive guidance for using OpenCode, the open-source AI coding agent. Use this skill when working with OpenCode CLI commands, keyboard shortcuts, agents (build/plan), slash commands, tools, skills, MCP servers, or configuration. Automatically triggered when OpenCode-specific questions or tasks are detected.

3installs

Sources-hiraoku/synapse-a2a

Added on2026-02-04

NPX Install

npx skill4agent add s-hiraoku/synapse-a2a opencode-expert

SKILL.md Content

View Translation Comparison →

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

bash

# 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

bash

# 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

bash

# 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

bash

# 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):

```
.opencode/skills/<name>/SKILL.md
```
(project)

~/.config/opencode/skills/<name>/SKILL.md

(global)

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

Skill Format

markdown

---
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

opencode-expert

NPX Install

Tags

SKILL.md Content

OpenCode Expert

Quick Reference

Agents

Build Agent (Default)

Plan Agent

Subagents

Keyboard Shortcuts

Slash Commands

CLI Commands

Interactive Mode

Non-Interactive Mode

Server Mode

Management Commands

Built-in Tools

Skills

File Locations

Skill Format

Name Rules

Configuration

Config Locations

Environment Variables

Custom Agents

Best Practices

Use Plan Mode First

File References

Undo Stack

Session Management

References