Subagents

Subagents are isolated workers. Each one has its own context window, can be pinned to a cheaper model, and is dispatched by Claude based on a routing rule in the agent’s description field. The main thread only sees the agent’s final summary.

This is the right primitive when work doesn’t belong on the main thread — repeatable specialist tasks like compression, structured review, or adversarial critique. The trade-off is delegation: the main thread loses visibility into how the agent reasoned, and each invocation starts fresh with no memory of earlier conversation.

For the broader question of when to reach for a subagent versus a CLAUDE.md rule or a skill, see Foundational elements. To orchestrate many subagents at scale, see Dynamic Workflows.

Where they live

Subagents are markdown files in the agents/ directory:

• User-level — ~/.claude/agents/*.md. Available across every project.
• Project-level — <repo>/.claude/agents/*.md. Committed with the repo, available only when working in that codebase.

User-level for agents that earn their keep across repos (compressors, reviewers). Project-level for agents that are genuinely repo-specific.

The three rules that catch most problems

Title-case tool names. Use Read, Grep, Bash, Glob, WebFetch, WebSearch in the tools field. Lowercase doesn’t always parse correctly across Claude Code versions.

Use “PROACTIVELY” or “MUST BE USED” in descriptions where you want aggressive routing. Without these phrases, Claude treats the agent as available rather than preferred. Be deliberate — overuse and routing accuracy drops.

Descriptions are routing rules, not labels. Write the trigger conditions, not the capability. "Use when long inputs appear — pasted documents, transcripts, file contents over ~1500 words" routes correctly. "Compresses documents" doesn’t tell Claude when to call it.

Frontmatter shape

The minimum useful agent definition:

---
name: agent-name
description: When to use this agent, in trigger-condition language.
model: sonnet
tools: Read, Grep
---

System prompt for the agent. What it does, what it returns, what its limits are.

Optional fields worth knowing:

• model — pin the agent to haiku, sonnet, or opus. Crucial for token efficiency. Pin compression and orientation work to Haiku; pin adversarial review to Opus.
• tools — restrict what the agent can do. An agent that should only read files shouldn’t have Bash. Smaller tool surface = more reliable behaviour.

Three agents that earn their keep

The suite below is a starting point. Each one is user-level (~/.claude/agents/) so it works across every project. Use them as templates — both for what to build and for the shape a useful agent definition takes.

Compressor — Haiku, user-level

The universal intake agent. Strips large inputs to a structured brief before any Opus reasoning happens.

---
name: context-compressor
description: Use PROACTIVELY when long inputs appear — pasted documents, research dumps, transcripts, thread history, or file contents over ~1500 words. Returns a tight structured summary only, never raw content. MUST BE USED before main-thread reasoning on large inputs.
model: haiku
tools: Read
---

Compression only. Accept input and return:

**Core claims** — 3–5 bullets, one sentence each.
**Key entities** — people, systems, companies, metrics, named only.
**Open questions or gaps** — what's missing or unresolved.
**Recommended focus** — one sentence on what the main thread should reason on.

Hard limits: max 500 words. No quotes. No raw content. No preamble.

Why it works: long input is the most reliable trigger. Haiku is the right model — compression doesn’t need reasoning depth. The strict output shape stops the agent drifting into analysis.

Code reviewer — Sonnet, user-level

Structured code review on staged or specified files. Sonnet is the right call: Haiku misses subtle type and framework issues; Opus is overkill.

---
name: code-reviewer
description: Use PROACTIVELY after code edits to staged or specified files. Reviews for type safety, framework conventions, security, and maintainability. Returns structured findings with severity ratings. MUST BE USED before merging non-trivial changes.
model: sonnet
tools: Read, Grep, Glob
---

Identify issues precisely. Do not rewrite code.

For each file:

**File:** `path/to/file`
**Issues:**
- [HIGH/MED/LOW] Issue → specific line or pattern → why it matters

**Patterns to note:** anything consistent across files worth flagging.

Severity:
- HIGH — runtime risk, broken framework conventions, type unsafety, security
- MED — maintainability, missing types, implicit any
- LOW — style, naming, minor inconsistency

Hard limits: no rewrites. Quote lines only when necessary. Max 500 words per file.

The “do not rewrite code” line is doing real work. Without it, code-review agents drift into rewriting, which conflates two different cognitive jobs. Reviewing identifies issues; rewriting fixes them. Keep them separate.

Adversarial reviewer — Opus, user-level

Triggered only when you explicitly ask for review of a completed draft. This is where Opus earns its keep.

---
name: adversarial-reviewer
description: Use this agent when the user explicitly requests review, challenge, or critique of a completed draft — strategy documents, product decisions, investment theses, memos, frameworks. Do NOT trigger during drafting. Read the source material in full before reviewing.
model: opus
tools: Read
---

Find what's wrong. Do not validate.

Before reviewing, read the source material in full.

**Assumption audit** — list every implicit assumption. Flag the unverified or optimistic.
**Gap analysis** — what evidence is missing? What questions are unanswered?
**Structural weaknesses** — where does logic not hold? Where do conclusions outrun evidence?
**Promotional bias check** — flag advocacy masquerading as analysis.
**Verdict** — one paragraph: what must be resolved before this is defensible?

Tone: direct. No diplomatic softening. Findings only — no rewrites.

The “Do NOT trigger during drafting” line in the description matters — without it, Claude will route to this agent during normal work and pollute the main thread with pre-emptive critique. The negative trigger is as important as the positive one.

Common anti-patterns

Reimplementing built-ins. Claude Code ships with Explore, Plan, and General-purpose agents. Don’t write a custom agent that duplicates them — you’ll add routing complexity for no gain. Reach for a custom agent only when the built-ins genuinely don’t fit.

Merging jobs. A “compressor-and-reviewer” agent does both worse than a dedicated compressor and a dedicated reviewer. One agent, one job. Routing accuracy depends on each agent having a clear, distinct trigger.

Vague descriptions. “Helps with code” is not a routing rule. Claude can’t decide when to use a “helpful” agent. Trigger conditions should be specific enough that you can predict whether the agent will be invoked.

Forgetting to restart. Filesystem agents load at session start. If you edit an agent definition mid-session, Claude is still using the old version. Restart after edits.

Subagent memory expectations. Each invocation starts fresh. The main thread’s context isn’t visible to the subagent unless you pass it in. If context-gathering work is expensive, either accept it’ll be repeated or hand the brief to the agent in your prompt.