> ## Documentation Index > Fetch the complete documentation index at: https://personal-f2f22caf.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Specification > The complete format specification for Harness Subagents. ## File format A subagent is defined by a single Markdown file. The file contains YAML frontmatter followed by Markdown content. The frontmatter holds metadata; the body holds the subagent's instructions. ``` repo-explorer.md ├── Frontmatter # Metadata: name, description, complexity, ... └── Body # Instructions the harness uses as the subagent's system prompt ``` The file name (without the `.md` extension) identifies the subagent. This format proposes a harness-neutral location that harnesses should discover first, modeled on the `.agents/skills/` convention: user level (`~/.agents/agents/`), then project level (`.agents/agents/`). It is a proposal of this format, not an established convention yet. Harness-specific directories (such as `.claude/agents/`) are scanned in addition — see [adding subagents support](https://personal-f2f22caf.mintlify.site/harness-implementation/adding-subagents-support.md) for the conventions existing harnesses use. A subagent file is self-contained. It does not bundle scripts, references or other supporting files. ## Frontmatter | Field | Required | Constraints | | - | - | - | | `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. | | `description` | Yes | Max 1024 characters. Non-empty. Describes what the subagent does and when a parent should delegate to it. | | `complexity` | No | One of `mundane`, `routine`, `interpreting`, `judgment`, `critical`. When omitted, the harness judges from the whole file. | | `tools` | No | Whitelist of tool names, or a boolean: `true` all, `false` none. An empty array means `false`. Absent inherits from the parent. (Experimental) | | `metadata` | No | Arbitrary key-value mapping for additional metadata (a map from string keys to string values). | > [card] > > **Minimal example:** > > ```markdown repo-explorer.md theme={null} > --- > name: repo-explorer > description: Maps how a codebase implements a feature. Use before planning changes. > --- > ``` > > **Example with optional fields:** > > ```markdown security-reviewer.md theme={null} > --- > name: security-reviewer > description: Reviews code changes for security vulnerabilities. Use when a change touches authentication, input handling or dependencies. > complexity: judgment > tools: [Read, Grep, Glob] > metadata: > author: example-org > version: "1.0" > --- > ``` #### `name` field The required `name` field: * Must be 1-64 characters * May only contain unicode lowercase alphanumeric characters (`a-z`, `0-9`) and hyphens (`-`) * Must not start or end with a hyphen (`-`) * Must not contain consecutive hyphens (`--`) * Must match the file name without the `.md` extension > [card] > > **Valid examples:** > > ```yaml theme={null} > name: repo-explorer > ``` > > ```yaml theme={null} > name: test-runner > ``` > > ```yaml theme={null} > name: code-reviewer > ``` > > **Invalid examples:** > > ```yaml theme={null} > name: Repo-Explorer # uppercase not allowed > ``` > > ```yaml theme={null} > name: -explorer # cannot start with hyphen > ``` > > ```yaml theme={null} > name: repo--explorer # consecutive hyphens not allowed > ``` #### `description` field The required `description` field: * Must be 1-1024 characters * Should describe what the subagent does and when a parent should delegate to it * Should include the boundaries of the task: subagents a parent should *not* delegate to this one help the parent choose correctly The description is the only part of the file a parent reads before deciding to delegate. It carries the entire burden of delegation. > [card] > > **Good example:** > > ```yaml theme={null} > description: Runs the project's test suite and reports pass/fail results grouped by root cause. Use when verifying code changes, before commits, or after refactors. Do not use for writing new tests or fixing test failures. > ``` > > **Poor example:** > > ```yaml theme={null} > description: Helps with tests. > ``` #### `complexity` field The optional `complexity` field: * Must be one of `mundane`, `routine`, `interpreting`, `judgment` or `critical` if provided * States the big picture: what kind of work the subagent does, not which model runs it * When omitted, the harness reads the whole file (description and body) and decides for itself The five tiers name the kind of work, from least to most demanding: | Tier | Suited for | Example | | - | - | - | | `mundane` | One fully specified step, where the spec decides every choice. | "Find every TODO comment and list them" | | `routine` | A prescribed procedure with light branching and local reads. | "Run the test suite and report pass/fail grouped by root cause" | | `interpreting` | Mixed evidence to weigh, prose quality that matters, or a plan that already decides the approach. | "Summarize this RFC thread and call out the contested trade-offs" | | `judgment` | Diagnosis, unfamiliar code, trade-offs, or open-ended work with no ready procedure. | "Find why checkout intermittently double-charges; no reproducer exists" | | `critical` | A live or irreversible state change, long-horizon orchestration, or design others will build on. | "Plan the billing-schema migration under live traffic" | The names describe the work, not a model size or an effort setting. A harness maps each tier to the models and reasoning effort it has; the same tier may land on different models in different harnesses. **Complexity and description work in tandem.** `complexity` sets the tier. The `description` adjusts within it: the scope, risk and ambiguity it describes tell the harness how far up or down the tier to lean. Two `interpreting` subagents can end up differently: a narrow, well-bounded one can run on a quick, light-effort setup, while an open-ended one can need a more capable model with more effort. Write the description with that reading in mind. When `complexity` is omitted, the harness reads the entire file and picks the model and effort by judgment, using the same signals. Complexity is a suggestion, not a requirement. Harnesses may override it per task based on their model lineup, availability or cost policy. If the model a harness selects is not available, the harness should ask the user whether to continue or to select another model. The default is to inherit the parent's model. How and whether the harness asks depends on the harness. > [card] > > **Example:** > > ```yaml theme={null} > complexity: routine > ``` #### `tools` field The optional `tools` field: * An array of tool names acting as a whitelist, or a boolean: `true` means all tools, `false` means none * When the field is absent, the subagent inherits the parent's tools * An empty array (`[]`) means the same as `false`: no tools * Tool names are harness-specific * Experimental. Support for this field may vary between harness implementations The harness enforces tool access. The body asking a subagent to "not edit files" is not a permission boundary — this field is. > [card] > > **Examples:** > > ```yaml theme={null} > # Whitelist: only these tools > tools: [Read, Grep, Glob] > ``` > > ```yaml theme={null} > # All tools the harness offers > tools: true > ``` > > ```yaml theme={null} > # No tools at all > tools: false > ``` #### `metadata` field The optional `metadata` field: * A map from string keys to string values * Harnesses can use this to store additional properties not defined by the Harness Subagents spec, such as provider-specific model routing * We recommend making your key names reasonably unique to avoid accidental conflicts > [card] > > **Example:** > > ```yaml theme={null} > metadata: > author: example-org > version: "1.0" > ``` ### Body content The Markdown body after the frontmatter contains the subagent's instructions. There are no format restrictions. Write whatever helps the subagent perform the delegated work effectively. The harness gives the body to the subagent as its system prompt when the parent delegates a task. The subagent does not see the parent's conversation, the user's history or any other context — only the body and the task the parent sends. Recommended sections: * Role and scope: what the subagent is, what it may and may not do * Tool expectations: how to approach the work with the tools it has * Constraints: boundaries that apply to every run, such as read-only scope * Deliverable expectations: what to report back and in what shape Everything in the body is paid on every run, inside the subagent's own context window. A long body leaves less room for the work. Keep it focused. The Agent Skills guidance of under 500 lines for `SKILL.md` is a sensible ceiling for the same reason. ## Discovery and sync Subagent files come from layered sources: the user level, the project level, and the subagents a harness provides itself. Harnesses persist what they load, attributed by source, keeping user and project subagents separate from their own. When subagents share a `name`, the more specific source wins: project overrides user, and both override harness-provided subagents. Keeping the catalog current is a sync, source by source. Each source is reconciled so the catalog mirrors it, and nothing else changes: a project providing A and B alongside a harness providing C yields a catalog of A, B, C; when the project changes and provides A and D, a sync makes the catalog A, C, D — B leaves with its source, C is untouched. Harness updates reconcile only the harness-provided layer and never rewrite user or project entries. Users and projects can disable or enable any subagent, including bundled ones. Harnesses should show which subagents are overridden, and by what. A harness may track changes in `.agents/agents/` and sync automatically. When it does not, it should tell the user when a sync is due: knowing an update is required is useful even when the update is applied manually. ## Lifecycle A subagent runs through four stages. 1. **Discovery**: The harness syncs its catalog and loads each subagent's `name` and `description` at startup. This is all the parent knows about the subagent when deciding whether to delegate. 2. **Delegation**: The parent sends a task to the subagent. Effective tasks include an objective, the expected deliverable, guidance on tools and sources to use, and clear task boundaries. 3. **Execution**: The harness spawns the subagent with the body as its system prompt, in an isolated context. The subagent works on the task using the tools the harness grants it. 4. **Return**: The subagent reports its deliverable directly back to the parent. The parent decides what to keep. ## Communication constraints These constraints follow from what a subagent is: a child of a parent agent, running without a human in the loop. * **No human intervention.** Subagents are not steered, paused or corrected mid-run. A subagent that needs a decision makes a reasonable assumption, records it in its report and continues. * **No blocking questions.** A subagent cannot ask the user anything. When genuinely stuck, it returns a blocked status with what is missing, and the parent decides what happens next. * **The parent is the only audience.** Everything a user eventually reads passes through the parent. A subagent writes for the parent, not for the user. * **No depth guarantee.** A parent may itself be a subagent. Harnesses may limit nesting. Subagent authors should not design around a specific depth. ## The deliverable Every subagent run ends with a report to the parent. The report is the product; the parent may read many of them in one session, so each one must be easy to act on. The recommended minimum deliverable: ```markdown theme={null} ## Status completed | blocked ## Summary One paragraph the parent can act on without reading anything else. ## Artifacts File paths or the deliverable itself. ## Notes Assumptions, deviations and follow-ups for the parent. ``` Rules of thumb: * **Status first.** A parent triaging several subagents reads statuses before anything else. * **The summary stands alone.** Assume the parent reads nothing below it. If the summary needs the artifacts to make sense, it is not done. * **Point, don't paste.** For large outputs, write them to files and return paths. The parent loads what it needs. * **Omit empty sections.** A completed run with no caveats needs no Notes section. This shape is a recommendation, not a requirement. Harnesses and parents may negotiate other formats; the task a parent sends can specify one. ## Subagents, skills, and tools The format is one of three ways to give an agent more capability. They compose, and choosing the right one matters: | Need | Use | | - | - | | Specialized knowledge or procedures an agent loads when a task calls for them | [Skill](https://agentskills.io) | | Delegated, isolated unit of agentic work with a report back | Subagent | | External model or service: OCR, transcription, image generation, batch classification | Tool (an MCP server or a bundled script) | A subagent is an agent: it runs an agent loop with tools, in its own context, and returns a report. Work that only needs a single inference call is faster as a tool. The fastest path for "answer these ten questions true or false" is one structured call to a decision model, not a subagent spawn. ## What the format does not define * **File locations.** The `.agents/agents/` cascade is the recommended default; beyond it, each harness discovers subagent files wherever it fits its architecture. * **Sync mechanics.** When a harness syncs, how it persists the catalog, and where enable/disable is configured are harness decisions. The format defines what a sync must respect — layered sources, per-source reconciliation, precedence — not how or when it runs. * **Model selection.** There is no model field. Harnesses derive model and effort from `complexity`, the description and their own policy, and decide what happens when the chosen model is unavailable. Harnesses that route across providers can store routing configuration in `metadata`. * **Nesting depth and parallelism.** Harnesses decide whether subagents can spawn subagents, and how many run at once. * **References and bundled files.** The body is self-contained. Large, conditional knowledge belongs in skills, which subagents can use where the harness supports them. * **Agent-to-agent protocols.** Communication between independent agents is the territory of protocols like A2A, not of this file format. MCP connects agents to tools and data. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.