Introduction to subagents

A walkthrough of the Claude Academy course Introduction to subagents (Learn the products track, 4 lessons, about 45 minutes). Each lesson is summarised with my own tables and examples; take the course for the full lessons. All the courses are listed in the Claude Academy course index.

Note: My own summary of the course, not the course itself; verify details against the lessons and current docs.

Lessons: What are subagents? · Creating a subagent · Designing effective subagents · Using subagents effectively

Prerequisites / Audience

• Developers who already use Claude Code and run longer sessions where context fills up.
• Comfortable with editing Markdown/YAML files in a repo.
• Goal: split work across isolated subagents and orchestrate them predictably.

Learning objectives

• Explain how subagents work: a separate context window, how inputs flow in, how summaries come back.
• Create custom subagents (by asking Claude to write them) for workflows like code review and docs.
• Design reliable subagents: structured output, obstacle reporting, limited tool access.
• Decide when subagents help and recognize common anti-patterns.

---

Lesson 1 — What are subagents?

• A subagent is a specialized assistant Claude Code can delegate to. It runs in its own context window, does the work, and returns only a summary to the main thread.
• The problem it solves: every tool call, file read, and search result in the main chat consumes the (finite) context window. Once it fills up, Claude starts losing track of earlier parts of the conversation.
• A subagent’s starting context contains:
  1. A custom system prompt from its config file (role and behavior).
  2. A task description written by the parent agent from your request.
• The intermediate steps stay isolated. Claude Code saves the full subagent conversation to a separate transcript file.
• Tradeoff: the main thread doesn’t see how the subagent reached its conclusion.
• Example: “Which service handles refunds?” The Explore subagent reads about 15 files, but the main context only records the question and the answer.

Built-in subagents

Subagent	Purpose
General purpose	Multi-step tasks that need both exploration and action
Explore	Fast searching and navigation of codebases
Plan	Used in plan mode to research and analyze the codebase before presenting a plan

• Custom subagents have their own system prompt and tool access, e.g. a code reviewer, test writer, or docs generator.
• The three benefits: focused pieces of work, a clean main context, and concise results.

---

Lesson 2 — Creating a subagent

• Subagents are Markdown files with YAML frontmatter. The frontmatter says when to use the subagent; the body says how it should behave.
• Recommended way to create one: ask Claude to write the file. Describe the subagent and where to save it, and include your choices for scope, tools, model, and color.
  • Note: the /agents wizard shown in the lesson video was removed in Claude Code v2.1.198. The file format and fields are unchanged.

Scope

Location	Scope
.claude/agents/<name>.md	Project-level: available only in the current project (commit it to share)
~/.claude/agents/<name>.md	User-level: available in all your projects on this machine

Tools, model, color

• Tool categories: read-only, edit, execution, MCP, other. Grant only what the job needs. For example, a reviewer needs no Edit, but Bash helps it run git diff.
• Model options: haiku (fast/light), sonnet (balanced), opus (complex analysis), inherit (use the main conversation’s model). You can also use a full model ID.
• Color: a UI marker that shows which subagent is active.

Example config

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---
You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.

Field	Meaning
name	Unique ID. Invoke it by asking Claude or typing @agent-code-quality-reviewer
description	Controls when Claude delegates. Must be a single line (use \n for breaks). Can include example conversations
tools	Allowed tools. Editable at any time
model	Alias (sonnet/opus/haiku), full model ID, or inherit
color	UI color
body	The system prompt: focus areas, method, and report format

• Automatic delegation: include the word “proactively” in the description, e.g. description: Proactively suggest running this agent after major code changes...
• Testing: make some changes and ask Claude to review them. If .claude/agents/ didn’t exist when the session started, restart Claude Code. If the subagent isn’t triggered, sharpen the description with concrete trigger examples.

---

Lesson 3 — Designing effective subagents

A badly configured subagent wanders, runs too long, or returns output the main agent can’t use. The four fixes are below.

How config data is used

• The name and description of every subagent are injected into the main agent’s system prompt. That’s how the main agent picks which one to launch.
• The description also guides the input prompt the main agent writes for the subagent.
  • Adding “You must tell the agent precisely which files you want it to review” makes the main agent list the specific files to review instead of just saying “use git diff”.
  • Adding “return sources that can be cited” to a web-search subagent makes the main agent pass that instruction along.

1. Define an output format (the single biggest improvement)

• It creates natural stopping points: the subagent is done when every section is filled.
• It prevents over-long runs, since otherwise subagents struggle to decide when they’ve done enough research.

Provide your review in a structured format:
- Summary: what you reviewed and overall assessment
- Critical Issues: security vulns, data-integrity risks, logic errors
- Major Issues: quality, architecture misalignment, performance
- Minor Issues: style, docs gaps, small optimizations
- Recommendations: refactors, best practices
- Approval Status: ready to merge/deploy, or requires changes
- Obstacles Encountered: setup issues, workarounds, env quirks, commands that
  needed special flags/config, dependencies/imports that caused problems

2. Report obstacles

• Workarounds the subagent discovers (dependency fixes, special flags, env quirks) must show up in its summary. Otherwise the main thread has to rediscover them, which wastes time and tokens.
• You get this reliably by adding an explicit “Obstacles Encountered” section to the output format.

3. Limit tool access

Subagent type	Tools
Research / read-only	Glob, Grep, Read (can’t modify files)
Code reviewer	add Bash (for git diff), still no Edit/Write
Styling / code modification	Edit, Write (changing code is its job)

• Limiting tools prevents side effects and clarifies each subagent’s role.

4. Specific descriptions

• Write them to steer both when the subagent launches and what instructions it receives.

---

Lesson 4 — Using subagents effectively

The decision rule: does the intermediate work matter to the main thread? If no, delegate. If yes, keep it in the main thread.

When subagents shine

• You need the result, not a play-by-play of how it was found.
• Exploration would clutter the main context.
• A fresh perspective or custom system prompt helps.

Use case	Why it works
Research	Reads dozens of files, then returns e.g. “JWT validation happens in middleware/auth.js line 42, called from the router in route/api.js”
Code review	Claude reviews better when the code seems to be someone else’s. A separate context has no authoring history, and project review standards can live in the system prompt
Custom system prompts	A copywriting agent (tone, audience, voice instead of terse technical prose); a styling agent that reads design-system files before writing any CSS

Anti-patterns (when subagents hurt)

Anti-pattern	Problem
“Expert” personas (“you are a Python expert”)	Adds nothing, because Claude already has that knowledge
Sequential pipelines (reproduce → debug → fix)	Each step depends on the previous step’s discoveries, so information gets lost at each handoff
Test runners	Return “tests failed” and hide the full output you need for debugging. Performed worst in testing

---

Quick-Review Flashcards

1. Q: What two things make up a subagent’s starting context? → A: Its custom system prompt (from the config file) and a task description written by the parent agent.
2. Q: What comes back to the main thread? → A: Only a summary. The full run is saved to a separate transcript file.
3. Q: Name the three built-in subagents. → A: General purpose, Explore, Plan.
4. Q: Where do project vs. user subagents live? → A: .claude/agents/ (project) and ~/.claude/agents/ (user).
5. Q: Which field controls when Claude delegates? → A: description, which must be a single line. Add “proactively” for automatic use.
6. Q: What is the body of the subagent file? → A: The subagent’s system prompt.
7. Q: What’s the single most important design improvement? → A: A structured output format, which gives the subagent stopping points and keeps runs short.
8. Q: Why add an “Obstacles Encountered” section? → A: So workarounds and quirks reach the main thread instead of being rediscovered.
9. Q: Which tools should a code reviewer get? → A: Read/Grep/Glob plus Bash (for git diff), but no Edit/Write.
10. Q: What’s the key question for deciding whether to delegate? → A: “Does the intermediate work matter?” If no, use a subagent.
11. Q: Why do test-runner subagents fail? → A: They hide the full failure output you need for debugging.
12. Q: How do you invoke a subagent explicitly? → A: Ask Claude by name, or type @agent-<name>.

Practice Ideas

• Ask Claude to create a project-level code-quality-reviewer with read-only tools plus Bash. Make changes, then ask for a review.
• Rewrite that reviewer’s description to require explicit file lists, and compare the input prompts the main agent writes before and after.
• Add the structured output format (including Obstacles Encountered) and compare run length and quality against a version without it.
• Build a read-only research subagent (Glob, Grep, Read, model: haiku) and use it to answer “where is X handled?” in an unfamiliar repo.
• Build a copywriting or styling subagent with a custom system prompt that reads your design-system files first.
• Try a reproduce → debug → fix pipeline once, then solve the same bug in the main thread, and note what got lost in the handoffs.