/subagents

name: subagents
description: Use when delegating work to a separate agent with its own context. Covers when delegation pays off, designing a subagent's scope and prompt, parallel fan-out, and the cost of a cold start.
metadata:
  category: agent-tooling
  version: 1.0.0
  tags: [subagents, delegation, context, parallelism]

Subagents

Purpose

Delegate work to a subagent when its own context is worth the cost of starting one. A subagent begins cold — it re-derives everything the main agent already knows — so the delegation must buy more than it costs.

When to Use

• A search or exploration that would flood the main context with results you do not need to keep.
• Independent work that can run in parallel.
• A task requiring a different, specialized instruction set.
• Verification by an agent that has not seen the reasoning that produced the work.

Capabilities

• Scoping a subagent's task and boundaries.
• Prompt design for a cold-start agent.
• Parallel fan-out for independent work.
• Result aggregation.
• Read-only agents for review and verification.

Inputs

• The task, and whether it is genuinely independent.
• What the subagent needs to know, since it knows nothing.
• What it must return.

Outputs

• A subagent that completes its task without further interaction.
• A result compact enough to be worth the round trip.

Workflow

1. **Justify the delegation** — The valid reasons are: context isolation (the search produces 50 files of noise and one answer), parallelism (five independent tasks), and specialization (a different instruction set). "The task is big" is not a reason — a big task in the same context is usually cheaper. 2. **Write the prompt as if to a stranger** — Because it is one. The subagent has none of your context: no conversation history, no prior findings, no shared understanding of the goal. Everything it needs must be in the prompt. 3. **State exactly what to return** — A subagent that returns a wall of text has moved the context problem rather than solved it. Specify the format and the length. 4. **Fan out only genuinely independent work** — Two subagents editing the same file will conflict. Parallelism requires disjoint scopes. 5. **Use a read-only agent for verification** — An agent that did not write the code is a better reviewer of it than the one that did.

Best Practices

• A subagent starts cold and re-derives context you already have. That is the cost. It is worth paying for isolation and parallelism, and it is not worth paying to avoid a long turn.
• The subagent's prompt is the entire interface. Include the file paths, the constraints, the definition of done, and the return format. Ambiguity produces a confidently wrong answer you then have to check.
• Search and exploration are the archetypal delegation: the subagent reads forty files and returns one paragraph. That paragraph is what you wanted; the forty files are what you were trying to avoid.
• Do not delegate a task you cannot verify. A subagent's report is a claim, not evidence.
• Parallel subagents that write to the same files will race. Give each a disjoint scope, or serialize them.
• Verification by a fresh agent is genuinely more effective than self-review — it has no attachment to the approach and no memory of why a shortcut seemed reasonable.

Examples

**Delegation that pays for itself — exploration with a compact return:**

Task for the subagent:

Find every place in this repository where an outbound HTTP call is made without
a timeout.

Search for: fetch(), axios, httpx, requests, http.Client, and any wrapper around
them in src/. For each call site, determine whether a timeout is configured —
either at the call, on the client, or by a default in a shared client factory.

Do not fix anything. Do not read files that are not relevant.

Return ONLY a markdown table with these columns, and nothing else:
| File:line | Call | Timeout configured? | Where the timeout is set (or "none") |

If there are more than 20, return the 20 with the widest blast radius (those in
request paths rather than in scripts or tests) and state the total count.

The subagent reads sixty files. It returns a twenty-row table. The main context receives the table.

**A delegation that is not worth it:**

"Implement the refund feature."

The subagent does not know: the domain conventions, the Result type, the fact
that Money is an integer, the existing RefundService, or why the previous
approach was rejected. It will re-derive some of this, get some of it wrong,
and return code that must be reviewed line by line against context it never had.

Doing this in the main context — where all of that is already established — is
faster and produces better code.

**Parallel fan-out with disjoint scopes:**

Three subagents, in parallel, each with a scope that cannot collide:

  1. "Audit skills/frontend/ for broken internal links. Report only."
  2. "Audit skills/backend/ for broken internal links. Report only."
  3. "Audit skills/devops/ for broken internal links. Report only."

Read-only, disjoint, independently useful. This is the shape delegation is for.

Notes

• The single best use of a subagent is a search whose intermediate results you do not want. The isolation *is* the product.
• A subagent that needs to ask a follow-up question has been given an insufficient prompt. Since it usually cannot ask, it will guess. Write the prompt accordingly.
• Verification subagents are most valuable on high-stakes work: a fresh reader catches the thing the author's context made invisible.