A First OpenCode Setup: AGENTS.md, Skills and MCP

OpenCode is one of the few terminal coding agents that treats every major open standard — AGENTS.md, Agent Skills, subagents, MCP servers and plugins — as a first-class citizen rather than a bolt-on. That makes it a good agent to learn the standards on, because you can see all five working side by side in one config file. This is a from-scratch setup: install the binary, give it project memory, add a skill, define a subagent, wire up an MCP server, and drop in a plugin. Every command and config snippet below comes straight from OpenCode's own docs, so you can copy it as-is.

OpenCode Open source

Open-source terminal coding agent that works with any model provider

★ 211k · +1.4k this week

8.4 Visit ↗

Install OpenCode

The quickest path is the official install script:

curl -fsSL https://opencode.ai/install | bash

If you'd rather go through a package manager, OpenCode also publishes to npm:

npm install -g opencode-ai

Homebrew and other platform installers are documented too, but the two above cover most terminals. Once it's installed, cd into a project and run opencode to open the TUI.

Connect a model provider

Before OpenCode can do anything useful, it needs a model to talk to. Run:

/connect

and pick a provider from the list. If you don't already have API keys sitting around for OpenAI, Anthropic or another provider, the docs point new users toward OpenCode Zen, the project's own hosted provider, specifically because it removes that first-setup decision: "If you are new to using LLM providers, we recommend using OpenCode Zen." You can always add or switch providers later — /connect isn't a one-time choice, it's how you register any provider you want available to /model afterward.

Give it project memory with AGENTS.md

Before touching skills or MCP servers, generate the file that anchors everything else. Inside a project, run:

/init

OpenCode analyzes the repository and writes an AGENTS.md file to the project root, describing structure, conventions and coding patterns it detects. The docs recommend committing this file to git — it's the shared brief every agent, skill and subagent in the project reads from, and it's the same open format other apps like Claude Code, Codex and Cursor also read. If you want the deeper mechanics of why a single instructions file works across tools, AGENTS.md: One Instructions File for Every Agent covers that ground.

Add Agent Skills

Skills are Markdown packets with a bit of YAML frontmatter, and OpenCode looks for them in four places, in this order of increasing "just works":

That means a skill written for Claude Code's .claude/skills folder is picked up by OpenCode with zero changes — one of the clearer examples of the SKILL.md format behaving like an actual open standard rather than a vendor convention. The frontmatter itself needs just a name (lowercase, hyphenated, 1–64 characters) and a description (1–1024 characters); license and metadata are optional.

Agents call skills through a built-in skill tool — skill({ name: "git-release" }) — and you control who's allowed to do that in opencode.json:

{
  "permission": {
    "skill": {
      "*": "allow"
    }
  }
}

Set that to "ask" if you want a prompt before each skill runs, or false under an agent's tools to disable skills entirely for that agent. Two skills already built to run across OpenCode, Claude Code, Codex and Cursor are worth trying first:

Superpowers 🧩 SkillFree

A skills library that makes coding agents plan, test-first and debug systematically

★ 294k · +2.7k this week

9.0 GitHub ↗

Archify 🧩 SkillOpen source

Validated, interactive architecture, sequence and data-flow diagrams compiled from typed JSON

★ 76k · +4.5k this week

7.9 Visit ↗

Define a subagent

Subagents are specialists a primary agent can delegate to, or that you invoke directly by @ mentioning them. OpenCode ships three built in — General, Explore and Scout — and lets you add your own two ways. The one the docs call preferred is a Markdown file, where the filename becomes the agent's name:

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
permission:
  edit: deny
  bash: deny
---
Review the diff for correctness, security and style issues.
Point out the specific line and the specific risk — don't restate what the diff already shows.

Save that as review.md under .opencode/agents/ (per-project) or ~/.config/opencode/agents/ (global), and you can call it with @review from the TUI. The permission block above is doing real work: edit: deny and bash: deny mean this subagent can read and comment but can't touch your files or run commands, which is exactly the shape you want for a reviewer. If you'd rather not hand-write the frontmatter, opencode agent create walks you through it interactively.

Connect MCP servers

MCP servers extend what OpenCode's agents can reach — a database, a browser, an issue tracker — and the config is a few lines per server in opencode.json. A local server you run as a subprocess:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

A remote, hosted MCP server instead takes a URL and headers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

If you're new to the remote-MCP side of that split — why some servers are a URL instead of a local process, and what OAuth has to do with it — Remote MCP + OAuth: How Agents Connect Without API Keys walks through the handshake. For a first server to try, GitHub's is the one most repos will actually use day to day, and Playwright's is the fastest way to let an agent click around what it just built:

GitHub MCP Server 🔌 MCP serverFree

GitHub's official MCP server: issues, pull requests, code, Actions and security alerts

★ 33k · +132 this week

9.0 GitHub ↗

Playwright MCP 🔌 MCP serverFree

Microsoft's MCP server for browser automation with Playwright

★ 38k · +196 this week

9.1 GitHub ↗

Browse the full catalog at /mcp-servers if neither fits — there are servers for databases, design tools, cloud deploys and web search beyond what fits in one post.

Extend with plugins

Plugins are where you reach past config into actual code — JavaScript or TypeScript files that hook into OpenCode's lifecycle. OpenCode auto-loads anything it finds in .opencode/plugins/ (project) or ~/.config/opencode/plugins/ (global):

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // hook implementations go here
  }
}

For a plugin someone else already published to npm, you don't need the file at all — just list it in opencode.json and OpenCode installs it with Bun at startup:

{
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}

Load order runs global config, then project config, then the global plugins directory, then the project plugins directory — so a project-level plugin can override anything a global one set up.

A day-one config to copy

Here's roughly what a first opencode.json looks like once you've done all five steps above — trim it to what you actually installed:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": { "*": "allow" }
  },
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"]
    }
  },
  "plugin": ["opencode-wakatime"]
}

Pair that with an AGENTS.md from /init, a skill or two dropped into .opencode/skills/, and a review.md subagent, and you've exercised every standard OpenCode supports in a single afternoon — the same five pieces that show up, in slightly different clothing, in Claude Code, Cursor, Codex and most of the rest of the ecosystem. /glossary has short definitions for any of these terms if a name here was new.

Where all of this config actually lives

By this point you've touched several different config surfaces — AGENTS.md, skill folders, agent Markdown files, mcp entries, a plugin list — and it's worth knowing how OpenCode reconciles all of them if they exist at more than one level. opencode.json (or opencode.jsonc) can live in your project root, in ~/.config/opencode/, at a path you set via the OPENCODE_CONFIG environment variable, or in an OS-managed directory for locked-down enterprise installs. OpenCode loads all of the sources it finds and merges them, rather than letting one file replace another, in this order from lowest to highest priority: remote config, global config, the OPENCODE_CONFIG path, project config, the .opencode directories (agents, commands, plugins), inline config via OPENCODE_CONFIG_CONTENT, then any system-managed files, with macOS managed preferences overriding everything else if your machine is enrolled in one.

In practice this means you rarely have to choose between "set it globally" and "set it per-project" — a permission you allow globally stays allowed unless a project config explicitly narrows it, and an MCP server you only need on one client project can live in that project's opencode.json without touching your global setup at all. It's the same merge-not-replace model that makes AGENTS.md composable with a global one too, since project-level instructions layer on top of whatever baseline you've set for yourself across all repos.

If something doesn't load

Skills, subagents, MCP servers and plugins all get discovered at startup, so a broken one usually shows up as "the thing I added just isn't there" rather than a loud error. OpenCode's own troubleshooting docs point at a short, ordered list before anything more drastic:

1. Fully quit and relaunch — a surprising amount of "it's not picking up my change" is a stale running process.
2. Check the logs at ~/.local/share/opencode/log/ (or the Windows equivalent), or restart with --log-level DEBUG for more detail.
3. If a plugin is the suspect, remove the "plugin" key from opencode.jsonc temporarily to confirm it's the cause, then delete ~/.cache/opencode — plugins and their dependencies are cached there and a stale cache is a common culprit.
4. If a model won't respond, re-run /connect, and double-check you're referencing it as <providerId>/<modelId> (for example openai/gpt-4.1) — opencode models lists what's actually available to you.

None of this is specific to the standards this post covers, but it's the fastest path back to a working setup when one of them silently doesn't show up.

Takeaway

OpenCode's advantage isn't a unique feature — it's that AGENTS.md, Skills, subagents, MCP and plugins are all wired up the same way you'd expect from reading each standard's own spec, with no OpenCode-specific dialect to relearn. Start with /init and one MCP server, add a skill from an existing pack like Superpowers or Archify once you trust the loop, and only reach for a custom subagent or plugin once you've hit something the built-ins can't do.