Custom Subagents

What a subagent is

A subagent is a separate Claude instance your main session can delegate a task to. It runs in its own context window with its own system prompt and its own tool permissions, does the work, and returns only a summary to the parent. The hundred file reads it performed along the way stay in its window and vanish when it finishes — your main conversation receives the findings, not the mess.

That context isolation is the core value, because the context window is the scarcest resource in a long session. Delegation lets exploration be thorough without being expensive to your main thread.

Defining one

Subagents are markdown files with YAML frontmatter, in .claude/agents/ (project) or ~/.claude/agents/ (personal). A realistic example:

---
name: security-reviewer
description: Reviews code for security issues. Use proactively
  after changes to auth, input handling, or data access.
tools: Read, Grep, Glob, Bash
model: opus
---

You are a security reviewer. Examine the code you are pointed at
for injection risks, authentication flaws, secrets in code, and
unsafe input handling. Report concrete findings with file and line
references. Report gaps, not style preferences.

The frontmatter fields that matter:

• description — drives delegation. Claude matches tasks against it to decide when to hand off, so write it to say when: "Use proactively after code changes." Vague descriptions mean the subagent never fires or fires constantly.
• tools / disallowedTools — an allowlist or blocklist. The security reviewer above gets read-and-search tools plus bash, and cannot edit files — its role is enforced by capability, not by politeness.
• model — haiku, sonnet, opus, or inherit. Route cheap work to cheap models: an exploration subagent on Haiku costs a fraction of one on Opus, and exploration rarely needs the big model.
• permissionMode, maxTurns — risk and budget controls.
• skills — skills to preload into the subagent's context.
• memory — what memory scope it sees.
• isolation: worktree — gives the subagent its own git worktree (a separate checkout of the repo), so its edits can't collide with your working directory. Essential for parallel editing.

The built-ins

Three subagents come free, no definition needed:

• Explore — fast read-only codebase search, with quick / medium / very-thorough levels. "Use the Explore subagent to find where rate limiting is implemented."
• Plan — the read-only researcher plan mode uses for exploration.
• general-purpose — can explore and modify; the default delegate for self-contained tasks.

Custom subagents earn their keep when you want a specific system prompt, a restricted toolset, or a chosen model — the security reviewer being the classic case.

When delegation beats the main thread

Context isolation. "Investigate how sessions are handled across the codebase" might touch forty files. In the main thread, those forty reads permanently occupy your window. Delegated, you get back a tight summary and your window stays clean for implementation.

Fresh-context review. A model reviewing code it just wrote is biased toward it — same blind spots, same assumptions. A review subagent starts cold: it sees the diff and the criteria, not the reasoning that produced the change. This is the single best-known use: "Use a subagent to review this code for edge cases" catches things the writing session cannot.

Parallelism. Several subagents can work simultaneously — with isolation: worktree keeping their edits physically separate.

Capability scoping. Some jobs should run with fewer permissions. A researcher with disallowedTools: Write, Edit cannot damage anything no matter how its prompt is phrased.

When NOT to delegate

Delegation has real costs: the subagent starts with zero knowledge of your conversation, and you pay its full exploration spend in tokens. So keep in the main thread anything that depends on accumulated session context, tight interactive back-and-forth, and small tasks where a handoff brief would be longer than just doing the work. The multi-agent economics lesson applies at small scale too: delegation pays when the work is separable — self-contained enough that a brief and a summary capture everything that crosses the boundary.

A good default rhythm for a feature: Explore subagent for the initial investigation, main thread for design and implementation (full context lives here), then a fresh security-reviewer or edge-case subagent over the diff before you call it done.