Loaded automatically when the description matches the active task. Read only the section needed.
Use this skill when
Installing or updating the opencode CLI (curl ... | bash, brew install, npm i -g opencode-ai)
Authoring opencode.json / opencode.jsonc (project) or ~/.config/opencode/opencode.json (user)
Writing or editing AGENTS.md for project memory (same file used by OpenAI Codex)
Configuring providers in opencode.json: provider.* for BYOK (Claude, OpenAI, Gemini, Mistral, Groq, Ollama, etc.)
Defining agents in opencode.json: agent.* (build/plan/custom) or .opencode/agents/<name>.md
Setting up MCP servers in opencode.json: mcp.* (stdio + http)
Running headless: opencode run "...", JSON output, CI integration
Using ACP (Agent Client Protocol) to drive OpenCode from Zed editor / IDE
Switching themes via tui.json: theme (tokyonight, dracula, etc.)
Migrating between OpenCode, Claude Code, and OpenAI Codex configs
Picking the right CLI: when multi-provider/BYOK is the requirement
Do not use this skill when
Task is Claude Code CLI specifics (settings.json hooks, .claude/skills, /loop) — use claude-code
Task is OpenAI Codex CLI (Rust, config.toml, codex exec) — use codex
Task is hosting the OpenCode server on Cloudflare / SST — focus here is the CLI client
Task is general LLM agent design (planning, evaluation, benchmarking) — use agent-evaluation
Task is authoring a Claude Code SKILL.md file — use skill-evaluation
User wants the deprecated 2021-era OpenAI Codex completion model — that's been discontinued; modern Codex is codex skill
Purpose
OpenCode (currently maintained by Anomaly at github.com/anomalyco/opencode, originally github.com/sst/opencode) is the leading open-source, multi-provider terminal coding agent. Unlike Claude Code (Anthropic-only) and OpenAI Codex (OpenAI-only), OpenCode is BYOK across 75+ providers including Anthropic, OpenAI, Google, Mistral, Groq, Together, and local models via Ollama. Built with Bun + TypeScript (with a Go TUI), 100K+ stars, Apache-2.0.
This skill covers the CLI operating surface: install, auth across providers, opencode.json config schema, agents (built-in build/plan + custom markdown agents), MCP servers, ACP protocol (for editor integration), headless opencode run, and the migration path to/from Claude Code and OpenAI Codex.
What this skill does NOT cover: hosting an OpenCode server on Cloudflare/SST (infra, not CLI), general agent benchmarking (agent-evaluation), or building custom MCP servers (mcp-builder).
Capabilities
Installation & auth
Native install script: curl -fsSL https://opencode.ai/install | bash. Brew: brew install sst/tap/opencode. npm SDK: npm i -g opencode-ai. Verify: opencode --version. Auth: opencode auth login opens a provider picker and stores credentials in ~/.local/share/opencode/auth.json. Per-provider env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OLLAMA_BASE_URL) also work directly.
Configure once in provider, pick per-agent in agent.<name>.model. Provider format: <provider>/<model-id>. Examples: anthropic/claude-sonnet-4-6, openai/gpt-5.5, google/gemini-2.5-pro, groq/llama-3.3-70b-versatile, ollama/codellama:34b. Failover is provider-specific (e.g., OpenRouter allow_fallbacks/order, Vercel gateway order) — there is no generic top-level provider.fallback key. Use opencode models to list everything available with current auth.
Two built-in primary agents: build (full tools, default) and plan (read-only, drafts a plan). Switch live with Tab in TUI or --agent flag. Custom agents: define in opencode.json: agent.<name> OR as markdown at ~/.config/opencode/agents/<name>.md / .opencode/agents/<name>.md. Frontmatter: description, model, tools, prompt. Subagents (non-primary) are called by primary agents via task delegation.
Configure in opencode.json: mcp. Same protocol as Claude Code/Codex — server binaries are interchangeable. Transports: local (stdio) and remote (http/sse). Example:
OpenCode permission model is simpler than Claude Code's: per-agent tools allowlist (disable write, edit, bash, web per agent), plus a runtime approval prompt by default. --auto flag or permissions.auto config skips prompts. There are no native hooks — wrap opencode run in a shell script for post-edit formatting.
ACP (opencode serve --acp) exposes OpenCode as an Agent Client Protocol server for editors (Zed native, VS Code via SDK). Headless: opencode run "<prompt>" --json returns a JSONL event stream. AGENTS.md is shared with Codex; CLAUDE.md is Claude Code's analogue. See references/agents.md, references/interop.md, references/migration.md.
Behavioral Traits
Reads opencode.json and AGENTS.md first when entering a project
Picks the provider per task: Anthropic for hard reasoning, Groq/Ollama for bulk/fast, Gemini for long context
Uses build agent by default; switches to plan for unfamiliar code or large refactors
Defines a code-reviewer custom agent with write: false, edit: false for read-only review work
Uses OpenRouter / Vercel gateway order + allow_fallbacks for per-model failover (no generic top-level provider.fallback exists)
Wraps opencode run in a shell script when hooks-like behaviour is needed (OpenCode has no native hooks)
Uses ACP mode when working inside Zed/VS Code rather than a separate TUI
Stores secrets in {env:VAR} interpolation, never inline in opencode.json
Commits opencode.json and AGENTS.md; gitignores .opencode/local.json if present
Important Constraints
NEVER commit API keys inline in opencode.json — use {env:VAR} or {file:~/.secrets/...}
NEVER assume Claude Code hooks have an OpenCode equivalent — they don't; use shell wrappers
NEVER use --auto outside a sandboxed environment (devcontainer/VM/CI runner)
NEVER mix Anomaly fork and SST origin docs — they diverged in late 2025; check which repo your install came from
NEVER omit the provider prefix in model IDs — claude-sonnet-4-6 is ambiguous; use anthropic/claude-sonnet-4-6
ALWAYS run opencode models after opencode auth login to verify the provider is reachable
ALWAYS pin OpenCode version in CI: install script accepts VERSION=1.0.92 bash
ALWAYS write subagent system prompts in their markdown body (not in opencode.json) when they exceed ~5 lines
Related Skills
90%-filter applied. ✓ = active; rest are cascade markers.
Cousin CLI agents
✓ claude-code — Anthropic's official CLI (depth in skills/hooks/subagents)
✓ codex — OpenAI's official CLI (Rust, OpenAI-only)
