▲ Claude Academy
Sign in

Vault / wiki/201/subagents.md

updated 2026-05-28

Subagents

Isolated agents the main Claude session can delegate tasks to. Each subagent runs in its own context window, with a focused tool set and its own system prompt. When done, it returns a single message to the parent.

Why subagents

  • Context isolation. Long noisy work (file scans, web research) stays out of the parent's context.
  • Specialization. Different system prompts and tool sets per subagent type.
  • Parallelism. Multiple subagents can run concurrently.
  • Cost optimization. Use Haiku for cheap subagents; reserve Opus for the orchestrator.

Defining subagents

In .claude/agents/<name>.md:

---
description: Read-only code-search agent. Locate symbols, files, and references quickly.
tools: Read, Grep, Glob, Bash(rg:*)
model: claude-haiku-4-5-20251001
---

You are a precise code-search agent. Given a query, locate the most relevant
files and lines. Return file:line citations, not prose summaries.

Frontmatter:

  • description — when to invoke (model reads this).
  • tools — allowed tool list (whitelist).
  • model — override for this subagent.
  • isolation — worktree for filesystem isolation.

Invocation

The main agent calls the Agent tool with:

{
  "subagent_type": "Explore",
  "description": "Locate auth-related code",
  "prompt": "Find every file under src/ that imports from src/auth and report file paths."
}

The subagent runs in its own context; the only thing the parent sees is the final summary string the subagent returns.

Multi-subagent orchestration

The orchestrator-workers pattern:

flowchart TB
    User([User goal]) --> O[Main agent / Orchestrator<br/>Sonnet or Opus]
    O -- "delegate search" --> R[research subagent<br/>Haiku + Read/Grep/Glob]
    O -- "delegate analyze" --> A[analyze subagent<br/>Sonnet + code tools]
    O -- "delegate write" --> W[write subagent<br/>Sonnet + filesystem]
    R -- summary --> O
    A -- summary --> O
    W -- summary --> O
    O --> Out([Final deliverable])

Each subagent has its own context window and tool whitelist. The parent only ever sees the final summary string the subagent returns — not its full trace.

Pitfalls

  • Over-delegation. Spawning a subagent for a 1-step task adds overhead. Use for genuinely scoped sub-problems.
  • Bad briefing. The subagent has zero context from your conversation. The prompt must include everything it needs — file paths, requirements, constraints. "Based on the above" doesn't work.
  • Trust trap. A subagent's summary describes intent, not necessarily reality. Verify writes/changes after the fact.
  • Parallel races. If two subagents write the same files, you get conflicts. Use worktrees for write-isolation.

CCA-F angle

The "Multi-Agent Research System" scenario is built around orchestrator-workers. Memorize:

  • Orchestrator typically larger model; workers smaller.
  • Each worker gets a focused, self-contained prompt.
  • Results aggregate via the orchestrator, not via shared mutable state.
  • Provenance flows up (each worker tags facts with source).

See also