How to Write Your Own Sub-Agent

The four sub-agent examples that follow this section all look similar because they follow the same five principles. Once these principles are familiar, writing a new sub-agent for a recurring task takes ten minutes.

Single-purpose

One sub-agent does one thing. A “code reviewer” sub-agent that also runs tests, also writes documentation, and also checks security is four sub-agents pretending to be one. Each capability bleeds into the others; the system prompt becomes vague; auto-delegation gets unreliable.

The Secret Scanner only scans for secrets. The Migration Validator only validates migrations. When a task feels too big for one sub-agent, that’s a signal to chain two narrow sub-agents, not to broaden one.

A precise description field

The description is how Claude Code decides when to auto-delegate. Vague descriptions produce two failure modes: the sub-agent never gets called when it should, or it gets called for tasks it’s not designed for.

The fix is to write the description as a trigger condition, not a capability summary:

Vague	Precise
Reviews code for quality	Use after staging changes and before committing. Reviews diffs for silent breakage.
Helps with database stuff	Use before merging a database migration. Dry-runs the migration and flags destructive operations.
Finds bugs	Use when an error or failing test appears. Finds root cause and proposes the smallest fix.

The pattern: Use [when] to [do what]. If the description doesn’t start with a clear when, rewrite it.

Minimum tool access

A sub-agent should have the smallest tool set that lets it finish the job. The default impulse — give it everything just in case — produces sub-agents that take destructive actions you didn’t expect.

Common patterns:

• Read-only review (Code Reviewer, Edge Case Sweep) → Read, Grep, Glob
• Read + run commands (Secret Scanner, Migration Validator) → Read, Grep, Bash
• Read + research the web (Source Verifier, Lead Researcher) → Read, WebFetch, WebSearch
• Read + write a single output file (Decision Log, Meeting Notes) → Read, Write
• Full read + write + execute — only when genuinely needed → Read, Write, Edit, Bash, Grep, Glob

Most useful sub-agents don’t need Write or Edit. They produce a structured output the main session reads and acts on.

Structured output

A sub-agent that returns prose forces the main session to parse it. A sub-agent that returns a table, a JSON object, or a fixed-format report can be consumed directly.

Define the output shape in the system prompt. Examples from the four sub-agents that follow:

• Secret Scanner — PASS or a list of (file, line, masked value, BLOCK) rows.
• Migration Validator — operation classification table, blockers list, verdict (APPROVED / BLOCKED).
• Resurrector — three-line summary (last intent, last block, smallest re-entry) plus three ranked next steps.
• Edge Case Sweep — ranked table of 15 edge cases with probability × severity scores.

The shape doesn’t have to be machine-parseable. It just has to be predictable.

Choose the right model

Three models, three use cases:

• Haiku — pattern matching, narrow scans, fast classification. The Secret Scanner runs on Haiku. So would a “is this commit message well-formed” check.
• Sonnet — everyday reasoning, structured output, most sub-agents. The Resurrector and Edge Case Sweep both use Sonnet.
• Opus — non-trivial reasoning, cross-cutting analysis, anything where being wrong is expensive. The Migration Validator uses Opus because a missed lock in production is much worse than a false positive in review.

Default to Sonnet. Drop to Haiku only when the task is genuinely narrow. Reach for Opus only when the cost of error is high enough to justify it.

A template

Combining the five principles:

---
name: <kebab-case-name>
description: Use [when] to [do what]. [One more sentence of trigger detail if needed.]
tools: <minimum tool set>
model: <haiku | sonnet | opus>
---

You [role description in one sentence].

Read [the specific input the agent expects].

Apply [named rules, in order]:

1. [Rule 1, with criteria]
2. [Rule 2, with criteria]
3. [Rule 3, with criteria]

Output:

- [Field 1]
- [Field 2]
- [Verdict / next step / structured result]

[Reject criteria — what counts as a non-answer that should be regenerated.]

A short test

Before committing a new sub-agent, check it against four questions:

1. Could this be one prompt to the main session? If yes, don’t make it a sub-agent.
2. Is the description a when, not a what?
3. Are the tools actually needed, or just listed by reflex?
4. Is the output shape predictable enough that the main session knows what to do with it?

If any answer is no, the sub-agent isn’t ready.