Course: Introduction to Subagents

Mirrors: Anthropic Academy — Introduction to Subagents · https://anthropic.skilljar.com/introduction-to-subagents Audience: Claude Code users and developers. · Time: ~60 min + project Prereqs: claude-code-101, introduction-to-agent-skills helpful. · Backing notes: subagents, agentic-patterns, agent-sdk Project: p14-subagent-research

A subagent is a delegate Claude can hand a scoped task to — it runs in its own context window, with its own tools and system prompt, and returns just a summary. By the end you can explain why context isolation matters, define a subagent in .claude/agents/, delegate to it, run several in parallel, and know when not to.

Learning objectives

After this course you can:

Define what a subagent is and how it differs from the main agent.
Explain why context isolation improves quality, cost, and focus.
Author a subagent in .claude/agents/*.md with description, tools, and model.
Have the main agent delegate a task and consume the returned summary.
Run parallel subagents in an orchestrator-workers pattern.
Decide when to use a subagent vs. doing the work inline, and brief one well.

Module 1 — What a subagent is

🎞 Frame 1 · A delegate with its own context · ⏱ ~3 min

🎬 Scene — The main Claude session spawns a smaller agent, which goes off, does noisy work, and hands back a single tidy summary.

🧠 Concept — A subagent is an isolated agent the main session delegates to. It has its own context window, a focused tool set, and its own system prompt. When done it returns one message to the parent — the parent never sees its full trace. (Deeper: subagents.)

🖼 On screen

Main agent ──delegate──▶ Subagent (own context, own tools, own prompt)
Main agent ◀──summary─── Subagent   ← only the final string comes back

✅ Checkpoint — What is the only thing the parent agent receives from a subagent? (Its final summary message.)

🎞 Frame 2 · Why context isolation matters · ⏱ ~3 min

🎬 Scene — A research subagent reads 40 web pages; the parent's context stays clean, holding only the conclusion.

🧠 Concept — Long, noisy work (file scans, web research, log spelunking) would bloat and distract the parent's context. Isolating it keeps the parent focused and its context lean, while the subagent absorbs the mess. This directly improves answer quality. (Deeper: context-management.)

🖼 On screen

Without subagent: parent context = goal + 40 noisy pages + answer   → distracted
With subagent:    parent context = goal + clean answer               → focused

✅ Checkpoint — Name one task whose intermediate output you'd rather keep out of the main context.

🎞 Frame 3 · Specialization, parallelism, cost · ⏱ ~2 min

🎬 Scene — Three subagents with different badges: a Haiku searcher, a Sonnet analyzer, a Sonnet writer.

🧠 Concept — Beyond isolation, subagents give you specialization (different prompts/tools per type), parallelism (run several at once), and cost control (cheap Haiku workers, reserve Opus/Sonnet for the orchestrator). (Deeper: subagents, agentic-patterns.)

✅ Checkpoint — Why would you assign Haiku to a search subagent but Sonnet to the orchestrator?

Module 2 — Defining a subagent

🎞 Frame 4 · The .claude/agents/*.md file · ⏱ ~3 min

🎬 Scene — A markdown file under .claude/agents/ with YAML frontmatter on top and a system prompt below.

🧠 Concept — You define a subagent as a markdown file in .claude/agents/<name>.md: frontmatter declares its config, the body is its system prompt. Project-level files are committed so the team shares them. (Deeper: subagents.)

🖼 On screen

---
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.

✅ Checkpoint — Where do subagent definitions live, and what does the file body become? (.claude/agents/<name>.md; the body is the subagent's system prompt.)

🎞 Frame 5 · The frontmatter fields · ⏱ ~3 min

🎬 Scene — Each frontmatter line is annotated: description, tools, model, isolation.

🧠 Concept — Key fields: description (when the model should invoke it — it reads this), tools (an allow-list whitelist), model (override for cost/speed), and optionally isolation: worktree for filesystem write-isolation.

🖼 On screen

Field	Purpose
`description`	When to delegate to this subagent (model reads it)
`tools`	Whitelist of allowed tools
`model`	Model override (e.g. Haiku for cheap workers)
`isolation`	`worktree` for isolated filesystem writes

✅ Checkpoint — Which field is a whitelist, and why limit it? (tools; least privilege — give a subagent only what its job needs.)

🎞 Frame 6 · A focused system prompt · ⏱ ~2 min

🎬 Scene — The body of the file: a tight, role-specific prompt with an explicit output contract.

🧠 Concept — The body should give the subagent a narrow role and a clear output contract (e.g., "return file:line citations, not prose"). A subagent with a sharp prompt and few tools outperforms a vague general one.

✅ Checkpoint — Why specify an explicit output format in a subagent's system prompt? (Its summary is all the parent gets — it must be predictable and usable.)

Module 3 — Delegation and parallelism

🎞 Frame 7 · How the main agent delegates · ⏱ ~3 min

🎬 Scene — The orchestrator calls the Agent tool with a subagent type, a short description, and a fully self-contained prompt.

🧠 Concept — The main agent delegates by calling the Agent tool: it names the subagent_type and passes a prompt. The subagent runs in its own context and returns a summary string. (Deeper: subagents, agent-sdk.)

🖼 On screen

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

✅ Checkpoint — When the parent delegates, what does the subagent know about the parent's conversation? (Nothing — only what's in the prompt.)

🎞 Frame 8 · Brief it like it knows nothing · ⏱ ~3 min

🎬 Scene — A prompt that says "based on the above" fails; a self-contained prompt with paths and constraints succeeds.

🧠 Concept — A subagent starts with zero context from your conversation. The prompt must include everything it needs — file paths, requirements, constraints, the exact deliverable. "Based on the above" doesn't work. (Deeper: subagents.)

⚠️ Gotcha — Vague briefing is the #1 subagent failure. Over-specify rather than under-specify.

✅ Checkpoint — Why can't a subagent prompt rely on "as we discussed earlier"?

🎞 Frame 9 · Parallel subagents: orchestrator-workers · ⏱ ~3 min

🎬 Scene — One orchestrator fans out to research, analyze, and write subagents running concurrently, then merges their summaries.

🧠 Concept — The orchestrator-workers pattern: a larger orchestrator delegates scoped sub-problems to several workers (often in parallel), each with its own context and tool whitelist, then aggregates their summaries. Results flow up through the orchestrator, not via shared mutable state. (Deeper: agentic-patterns.)

🖼 On screen

flowchart TB
    O[Orchestrator<br/>Sonnet/Opus] -- delegate --> R[research<br/>Haiku]
    O -- delegate --> A[analyze<br/>Sonnet]
    O -- delegate --> W[write<br/>Sonnet]
    R -- summary --> O
    A -- summary --> O
    W -- summary --> O
    O --> Out([Deliverable])

✅ Checkpoint — In orchestrator-workers, how do results combine — shared state or returned summaries? (Returned summaries, aggregated by the orchestrator.)

Module 4 — When to use them (and when not)

🎞 Frame 10 · Subagent vs inline · ⏱ ~3 min

🎬 Scene — A balance: a sprawling, noisy sub-problem on one side; a one-step task on the other.

🧠 Concept — Use a subagent when work is genuinely scoped, noisy/large, parallelizable, or needs different tools/model. Do it inline when it's a quick one-step task — spawning a subagent then adds pure overhead. (Deeper: subagents.)

🖼 On screen

Use a subagent	Do it inline
40-page research sweep	A single grep
Parallel independent sub-tasks	One sequential edit
Needs a narrower tool set / cheaper model	Trivial lookup

✅ Checkpoint — Why is spawning a subagent for a 1-step task usually a mistake? (Overhead outweighs the benefit.)

🎞 Frame 11 · Trust but verify the summary · ⏱ ~3 min

🎬 Scene — A subagent reports "all files updated"; the parent re-checks the diffs before trusting it.

🧠 Concept — A subagent's summary describes intent, not guaranteed reality. Verify writes/changes after the fact. And beware parallel races — two subagents writing the same files conflict; use isolation: worktree for write-isolation.

⚠️ Gotcha — Don't let two parallel subagents edit the same files. Isolate or serialize writes.

✅ Checkpoint — Two parallel subagents both modify app.py. What goes wrong, and how do you prevent it? (Conflicting writes; use worktree isolation or serialize.)

🎞 Frame 12 · Design tips & recap · ⏱ ~2 min

🎬 Scene — A recap slide: isolate context, scope tightly, whitelist tools, brief fully, verify, parallelize when independent.

🧠 Concept — Good subagent design: keep each one focused, least-privilege on tools, self-contained in its brief, and verified after the fact. Orchestrator typically a larger model; workers smaller; provenance flows up.

✅ Checkpoint — Without looking, list the four frontmatter fields of a subagent definition. (description, tools, model, isolation.)

🛠 Project

Complete p14-subagent-research — A Multi-Subagent Research System. You'll define research and synthesis subagents in .claude/agents/, have an orchestrator fan out parallel research, aggregate the returned summaries into a cited brief, and verify the result — practicing isolation, briefing, and provenance.

🧪 Self-check quiz

What three things does a subagent have that make it "isolated"?
What is the only thing the parent receives back from a subagent?
Where are subagents defined, and what is the file body?
Name the four common frontmatter fields.
Why must a subagent's prompt be fully self-contained?
In orchestrator-workers, how do results combine?
Give one case for a subagent and one case for doing the work inline.
How do you prevent two parallel subagents from clobbering each other's writes?

<details><summary>Answers</summary>

Its own context window, its own tool set, its own system prompt. 2. The final summary string. 3. .claude/agents/<name>.md; the body is the subagent's system prompt. 4. description, tools, model, isolation. 5. The subagent has zero context from the conversation — "based on the above" fails. 6. Returned summaries aggregated by the orchestrator (not shared state). 7. Subagent: a 40-page research sweep; inline: a single grep / one-step edit. 8. Use isolation: worktree (or serialize the writes).

</details>

🎓 Certificate criteria

You've "passed" Introduction to Subagents when you can:

Explain context isolation and why it improves quality and cost.
Define a subagent in .claude/agents/ with description, tools, and model.
Delegate a task with a self-contained prompt and consume the summary.
Run parallel subagents and aggregate their results safely.
Complete p14-subagent-research with verified, cited output.

Tick this course off in progress and record the date you earned Anthropic's official certificate.

🔗 Sources & deeper notes

Official course: https://anthropic.skilljar.com/introduction-to-subagents
Docs: https://docs.claude.com/en/docs/claude-code/subagents
Vault notes: subagents, agentic-patterns, agent-sdk, context-management
Prev course: introduction-to-agent-skills · Related: mcp-advanced-topics