# Agents > Define your own specialist subagents as markdown files. Empryo also reads the agent folders you already have for Claude Code, opencode and Gemini CLI. A custom agent is a markdown file that describes a specialist: what it's for, which model runs it, which tools it may use, and the instructions it follows. When Empryo splits work across parallel helpers, it can hand a task to your specialist instead of a general-purpose one. Use one when you keep giving the same kind of instructions: "review this for security issues", "find the slow paths, don't edit anything", "write release notes in our style". Empryo uses the same file layout as Claude Code, opencode and Gemini CLI, and reads their folders. An existing `.claude/agents/reviewer.md` works with no changes. ## Write one Create a markdown file with `name` and `description` in the frontmatter. The body is the agent's instructions. ```markdown --- name: perf-hunter description: Finds hot paths and allocation churn. Use before optimizing anything. mode: explore tools: read, grep, genome_analyze effort: low --- You hunt for performance problems. Report the top 3 hot paths with `file:line` and the measured or inferred cost of each. Never edit files. ``` Save it as `.empryo/agents/perf-hunter.md` in your project. Empryo picks up new and edited files within a few seconds. You don't need to restart. Run `/agents` to see every definition Empryo found, grouped by project and global scope. In the terminal UI, press Enter on a row to read the full instructions, or `r` to re-scan. The desktop app shows the same list in a drawer. ## Where Empryo looks Empryo scans these folders, including subfolders, so you can organize files like `agents/review/security.md`. An agent's identity is its `name` field, or the filename if `name` is missing. The folder path doesn't matter. When two files use the same name, the one higher in this list wins. Project folders always beat global ones, and within each scope Empryo's own folder comes first. ``` .empryo/agents/ project .agents/agents/ project .opencode/agents/, .opencode/agent/ project (opencode) .gemini/agents/ project (Gemini CLI) .claude/agents/ project (Claude Code) ~/.empryo/agents/ global ~/.agents/agents/ global ~/.config/opencode/agents/, …/agent/ global (opencode) ~/.gemini/agents/ global (Gemini CLI) ~/.claude/agents/ global (Claude Code) ``` ## Frontmatter Only `name` and `description` are required. Every other field limits or tunes the agent. | Field | What it does | | :---------------- | :-------------------------------------------------------------------------------------------------- | | `name` | Unique id, lowercase with hyphens. Defaults to the filename | | `description` | When to use this agent. Empryo reads this to decide when to delegate | | `mode` | `explore` (read-only) or `code` (may edit files). Leave it out to let the task decide | | `model` | A full `provider/model` id, or a short alias (see below) | | `tools` | Only these tools are allowed. Leave it out to allow the normal set | | `additionalTools` | Extra Empryo-only tools to allow on top of `tools`, so the file still works in other agents | | `disallowedTools` | Tools to remove, applied after `tools` | | `effort` | Reasoning effort for this agent | | `maxTurns` | Maximum number of steps the agent may take | | `skills` | [Skills](/docs/tools/skills) to load into the agent's context at start | | `temperature` | Sampling temperature for this agent | | `color` | Color used for the agent in panels and transcripts | Empryo ignores keys it doesn't know. A `permission:` block written for another tool won't break the file. ### Read-only or editing `mode` decides whether the agent can change files. If the file sets a mode, that mode always applies. An `explore` agent stays read-only even when it's given an editing task. opencode's `subagent` and `primary` values are understood too. The `tools` list is enforced. If the agent tries a tool that isn't on the list, the call is refused with a message naming the agent that blocked it. A custom agent can never get more power than the session allows. If your session is read-only, so is every agent it starts. ### Models A full `provider/model` id is used exactly as written. Short aliases such as `haiku`, `sonnet` or `fast` map onto the fast model you've configured in Empryo, because the author's provider may not be yours. `inherit`, or no `model` field, uses whatever model Empryo would have picked. ## Run one Empryo chooses one of your agents on its own when a task matches its `description`. So write the description as a rule for when to use it ("Use after writing or modifying code"), not as a title. You can also ask for one by name in your prompt ("have perf-hunter look at the boot path"). The agent can run it as a parallel helper within the current turn, or in the background while you keep working. In a headless run, you can run the whole session as one of your agents: ```bash empryo --headless --agent perf-hunter "why is the boot path slow?" ``` If the name doesn't exist, Empryo stops with an error that lists the available agents. It won't quietly fall back to the default. Helpers running as a custom agent show its name: in the desktop Subagents panel and in the terminal UI's dispatch tree. ## Let Empryo write one Describe a role you want to reuse ("a release-notes writer that follows our CHANGELOG style") and ask Empryo to save it as an agent. It writes the file to `.empryo/agents/`, or to `~/.empryo/agents/` if you ask for a global one, and can use it in the same turn. If another folder already has an agent with the same name, Empryo tells you which file wins, so a new definition never loses silently to an old `.claude/agents/` copy.