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 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).

Minimal example:

repo-explorer.md

---
name: repo-explorer
description: Maps how a codebase implements a feature. Use before planning changes.
---

Example with optional fields:

security-reviewer.md

---
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

Valid examples:

name: repo-explorer

name: test-runner

name: code-reviewer

Invalid examples:

name: Repo-Explorer  # uppercase not allowed

name: -explorer  # cannot start with hyphen

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.

Good example:

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:

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.

Example:

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.

Examples:

# Whitelist: only these tools
tools: [Read, Grep, Glob]

# All tools the harness offers
tools: true

# 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

Example:

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:

## 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
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.