Subagents

Load this when: a task is large enough to split, a search would flood your context, you need work verified by something other than the agent that wrote it, or you are defining a new specialist in .claude/agents/.

A subagent is a separate Claude instance with its own context window, its own system prompt, and optionally a restricted tool set. The main agent delegates a task to it, the subagent works in isolation, and it returns a single final report.

1. Why delegate at all

Three reasons, in order of how often they apply:

1. Context preservation. A search that reads forty files costs forty files of your context. Delegated to a subagent, it costs one paragraph of findings. This is the most common reason and the most undervalued.
2. Independent verification. An agent that wrote code is a bad judge of whether that code works — it is predisposed to see its own intent rather than what it typed. A fresh subagent has no such stake. See verification.md.
3. Parallelism. Independent read-only investigations run concurrently instead of serially.

Delegation is not free. Each subagent starts cold — it does not inherit your conversation, the file you just read, or the decision the user made three turns ago. Everything it needs must be in the prompt you give it. For a task you could finish in two tool calls, spawning a subagent is slower and worse.

Do the work inline when: it is a couple of files, you already have the context loaded, or the task is a single edit. "Thorough", "multiple angles", and "several parts" are not by themselves reasons to delegate.

2. Defining a subagent

Subagents are markdown files with YAML frontmatter. Project-level definitions live in .claude/agents/; user-level ones in ~/.claude/agents/. Project definitions take precedence when names collide.

---
name: swift-reviewer
description: Independent verifier for Swift changes. Use after code is written to check it against the repo rules and prove it builds. Runs builds and tests and returns real output.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are an independent reviewer. …system prompt…

The description is the interface

The main agent picks a subagent by reading descriptions, not by reading system prompts. A vague description means the subagent never gets invoked, or gets invoked for the wrong things.

# WEAK — nothing here says when to use it.
description: Reviews code.

# STRONG — names the trigger, the input, and the output.
description: Independent verifier for Swift/iOS changes. Use after another agent
  has written code, to check it against repository rules and prove it builds and
  tests pass. Runs builds and tests and returns their real output.

Write descriptions in the form *". Use when . Returns

$ ./scripts/eval-agents.sh
AGENT                   TOOLS                                BOUNDARY
ios-explore             Read, Grep, Glob                     read-only (enforced + declared)
swift-reviewer          Read, Grep, Glob, Bash               read-only (enforced + declared)
swift-refactorer        Read, Grep, Glob, Edit, Write, Bash  read-write
…
OK — 10 agents, every declared boundary is consistent with its instructions.

# WEAK
"Look at the networking code."

# STRONG
"Find every place that constructs a URLRequest in Sources/, and report which
ones set an Authorization header and which do not.

Context: we are adding a shared auth interceptor and need to know what would
be duplicated. The APIClient at Sources/Data/APIClient.swift:44 is already
known — I need the ones outside it.

Out of scope: test targets, and anything under Vendor/.

Return: a table of file:line, the endpoint, and whether it sets auth."

# 1. Delegating what you could do in two tool calls.
"Spawn a subagent to read Package.swift."
-> Just read it. Cold start costs more than the read.

# 2. Spawning a fresh agent for a task an existing one has context for.
-> Continue the existing subagent instead of starting cold again.

# 3. Assuming the subagent can see your conversation.
"Fix the bug we discussed."
-> It has no idea what you discussed. Restate it.

# 4. Parallel writers on the same files.
-> Sequence them, or isolate each in a worktree.

# 5. A reviewer that also edits.
-> Then it is grading its own work. Restrict its tools.

# 6. Trusting a report with no evidence.
"The subagent said tests pass."
-> Did it paste the output? If not, it asserted, it did not verify.

# 7. Predicting a background subagent's result.
-> A pending agent has no result. Say it is still running.

# 8. One mega-subagent with every tool and a vague description.
-> It never gets routed correctly and cannot be reasoned about.