OpenCode Custom Agents and Subagents: Markdown Files, Modes and @ Mentions
How do I create a custom agent or subagent in OpenCode?
Put a markdown file in .opencode/agents/ for a project or ~/.config/opencode/agents/ for every project, or add an entry under the agent key in opencode.json. The file name becomes the agent name. Set mode to subagent and call it with an @ mention or let the primary agent call it.
Built-in agents
- build: the default primary agent with all tools enabled.
- plan: a restricted primary agent for analysis. Edits and bash ask by default.
- general: a subagent for multi-step work that can change files.
- explore: a read-only subagent for finding files and searching code.
Create an agent as a markdown file
Save the file in .opencode/agents/ or ~/.config/opencode/agents/. A file named review.md creates an agent called review. The body is the system prompt.
.opencode/agents/docs-writer.md
--- description: Writes project documentation mode: subagent permission: bash: deny --- You are a technical writer. Produce clear, well-structured docs with code examples.
Create an agent in opencode.json
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"reviewer": {
"description": "Reviews changes for bugs and style issues",
"mode": "subagent",
"temperature": 0.1,
"permission": { "edit": "deny", "bash": "ask" }
}
}
}Options you can set
- description: required. Says what the agent does and when to use it.
- mode: primary, subagent or all. The default is all.
- model: in provider/model-id format.
- temperature, top_p, steps, color, hidden, disable.
- prompt: path to a custom system prompt file.
- permission: allow, ask or deny per tool. The older tools key is deprecated.
Generate one and use it
Run the interactive wizard to create an agent. It asks where to save it, what it should do and which permissions to grant.
Terminal
opencode agent create
Primary agents call subagents automatically based on their description. You can also mention one directly, for example: @explore find where the session config is loaded.
Sources
More OpenCode guides
Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.
Built an MCP server? Get it listed everywhere →
Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →