Skip to main content
Beyond the ten built-in agents, you can define your own. Custom agents are Markdown files with a frontmatter block that describes the agent’s model, access level, and available tools, plus a body that acts as its system prompt.

​
Creating an agent

The fastest path is the built-in generator, which asks a few questions and writes the file for you:
Agents live under .opencode/agent/ in the project (or your global config directory for personal agents). Each agent is a single .md file whose filename becomes the agent’s name.

​
Anatomy of an agent file

Common frontmatter fields:

​
Using a custom agent

In the TUI, press Tab to cycle through agents; custom agents appear alongside the built-ins.

​
Subagents

Agents can delegate to subagents through the task tool. Bolt ships with @general and @explore, and any custom agent whose file lives under .opencode/agent/ can also be invoked as a subagent by name.
  • Agents — the built-in agent lineup.
  • Tools — what you can add to tools:.
  • Custom Tools — build the tool the agent will call.