Authoring subagents

A subagent definition is one Markdown file. omp scans a handful of directories on every task call, indexes them by name, and resolves the agent parameter to whichever file wins. The eight bundled agents from Subagents sit at the bottom of that stack — anything you drop in front of them with the same name takes over.

Where definitions live

Files are read from these roots, in this order. The first match by name wins.

.omp/agents/<name>.md          # project, omp-managed
~/.omp/agent/agents/<name>.md  # user, omp-managed
<plugin>/agents/<name>.md      # plugin-provided
<bundled>                      # explore, plan, designer, reviewer, librarian, oracle, task, quick_task

Resolution is exact-name, case-sensitive (Reviewer and reviewer are distinct). Only the .omp roots are scanned — .claude/agents/ and friends are skipped because their frontmatter schema differs. Within one directory, files are read in lexicographic order before dedup. Plugin agents are appended after the filesystem sources; bundled agents come last. Override a bundled agent by giving your file the same name.

A bad frontmatter parse or a missing required field skips that one file with a warning. Discovery of the rest continues.

Definition file shape

---
name: api-reviewer
description: Reviewing changes to packages/api/* for breaking changes, missing tests, and OpenAPI drift.
tools: read, search, find, bash
model: sonnet
---
 
You review pull requests touching the public API surface.
 
Focus on:
 
- breaking changes to exported types or HTTP routes
- missing or thin test coverage on changed branches
- OpenAPI spec drift vs the runtime handlers
 
Return a short bulleted verdict. Do not edit files.

name and description are required. The description is what the parent agent reads when deciding whether to dispatch — write it the same way you’d write a skill description: verbs, nouns, scope. The Markdown body becomes the child’s system prompt verbatim.

| Field | Effect | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------- | ------- | --------------------------------------------- | | name | Identifier matched against the agent field of a task call. | | description | Shown to the parent in the task tool’s inventory. | | tools | CSV or YAML list. Restricts the child to this subset. yield is always added. Omit to inherit the parent’s tool set. | | model | Model pattern — or a CSV list of fallbacks — for the child session. Omit to inherit. | | spawns | *, CSV, or list — which agent names this child may itself spawn. Defaults to none, except when tools includes task, where it defaults to *. | | thinkingLevel | minimal \\ | low \\ | medium \\ | high \\ | xhigh(kebab-casethinking-level works too). | | output | Opaque JSON schema for structured returns. Conflicts with prose output instructions; pick one. | | blocking | Marks the spawn as blocking on the parent’s side. | | autoloadSkills | Skill names preloaded into the child session. | | read-summarize | Set false to make the child’s read return verbatim content instead of structural summaries. |

Anything not set is inherited from the parent session’s defaults at execution time.

Dispatching a custom agent

Once the file is on disk, pass its name to the task tool:

{
  "agent": "api-reviewer",
  "tasks": [{ "id": "review-pr-417", "description": "Review PR 417", "assignment": "..." }]
}

If the name doesn’t resolve, the call returns Unknown agent "<name>". Available: … without spawning anything. If a parent’s spawns policy disallows the name, you get Cannot spawn '<name>'. Allowed: …. Recursion depth caps further spawns from inside a child once task.maxRecursionDepth is hit.

Iterating on a definition

Open /agents from the prompt to see every agent the current session resolved, where each one was loaded from, and which won a name collision. N starts the new-agent flow, R regenerates a draft, and Ctrl+R reloads from disk — useful when you’ve just edited a file in another window. For a faster loop, dispatch the agent directly with a one-line assignment and inspect the returned agent://<id> transcript.

Related

• Subagents & IRC — using the task tool and the bundled agents.

• Skills — on-demand playbooks the agent loads at runtime.

• Custom tools — extend the tool surface a subagent can use.\n