Module 6: Subagents: delegating work to specialized agents

Module 6: Subagents — delegating work to specialized agents

Overview

You already know how to work with Claude Code: you've mastered the Explore → Plan → Code workflow, you have CLAUDE.md configured, and you've built skills and hooks that automate your workflow. So far you've interacted with a single agent — the main Claude Code agent that runs your instructions directly. Now comes the jump: what happens when one agent isn't enough?

This module teaches Claude Code's subagent system — the ability to delegate work to specialized agents that run in parallel or in sequence, each one optimized for a specific kind of task. You'll learn to use the built-in subagents (Explore, Plan, General-purpose, statusline-setup, claude-code-guide), to create custom subagents for your project's tasks, to take advantage of the official plugin marketplace (over 100 plugins installable with a single /plugin command), and to understand the emerging Agent Teams model for multi-agent orchestration.

Subagents are Claude Code's most differentiating feature. No other coding agent allows this level of delegation and specialization. Mastering subagents is what separates a competent user from an advanced one.

Where you are in the guide

Module 01: What Claude Code is ✅
Module 02: Installation and setup ✅
Module 03: CLAUDE.md and memory ✅
Module 04: Agentic workflow ✅
Module 05: Skills and Hooks ✅
Module 06: Subagents ← YOU ARE HERE
Module 07: Integrations (Git, SDK, Remote Control)
Module 08: Capstone project

In the previous modules you configured Claude Code (02-03), learned to work with it (04), and customized it (05). Now you go from customizing to scaling. This module teaches you to multiply Claude Code's capacity by delegating work to specialized agents.

The mental model: a team, not an individual

Until now you've worked with Claude Code as a single developer: you give it an instruction, it runs it, it hands back the result. That's effective, but it has limits. One agent has one context window, processes one task at a time, and mixes analysis with implementation.

Subagents change the mental model:

┌──────────────────────────────────────────────────────────────┐
│                    WITHOUT SUBAGENTS                         │
│                                                              │
│  You ──▶ Claude Code ──▶ analyze ──▶ plan ──▶ implement      │
│                    (all sequential, a single context)        │
│                                                              │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                    WITH SUBAGENTS                            │
│                                                              │
│                 ┌──▶ Explore subagent (analyzes files)       │
│                 │                                            │
│  You ──▶ Claude │──▶ Plan subagent (designs solution)        │
│          (lead) │                                            │
│                 └──▶ General subagent (implements task)      │
│                                                              │
│            (parallel, separate contexts, specialization)     │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Think of a tech lead coordinating a team. The tech lead doesn't write all the code — they delegate: "you analyze the tests, you implement the endpoint, you review the documentation." Each person focuses on their task, and the tech lead integrates the results. That's exactly what Claude Code does with subagents.

The precise analogy

Team concept	Claude Code concept	Function
Tech lead	Main agent (parent)	Orchestrates, delegates, integrates results
Analyst	Explore subagent	Reads and analyzes, doesn't modify
Architect	Plan subagent	Designs solutions without executing
Developer	General-purpose subagent	Executes complete tasks
Assistant	statusline-setup	Configures interface settings
Documenter	claude-code-guide	Answers questions about Claude Code features

Why the multi-agent model is better

The single-agent model has three fundamental problems that subagents solve:

1. Context pollution

When an agent reads 50 files to understand the architecture and then implements a small change, the analysis information takes up context it doesn't need for the implementation. With subagents, the Explore subagent spends its own context on the analysis, returns a compact summary, and the main agent works off that summary — without loading all 50 files.

2. Unnecessary serialization

Without subagents, everything runs in sequence: analyze, plan, implement. With subagents, you can parallelize: while one subagent analyzes the tests, another analyzes the documentation, and a third looks for dependencies. Three tasks that would take 3 minutes in sequence take 1 minute in parallel.

3. Lack of specialization

A general agent that does everything is like a fullstack developer who also handles DevOps, QA, and documentation. It works, but it isn't optimal. Subagents are optimized for their task: the Explore subagent has read-only access and is fast at searching; the Plan subagent designs without executing; the claude-code-guide subagent specializes in answering questions about the tool itself.

Why subagents matter now

The evolution of AI development

2023: One prompt, one response (chatbot)
2024: Multiple turns, one agent (agentic coding)
2025: Multiple agents, orchestration (multi-agent)
2026: Agent Teams, autonomous delegation (where we are)

Subagents are the natural next step in the evolution of AI-assisted development. We went from talking to a chatbot, to working with an agent, and now to directing a team of agents.

The practical impact

Without subagents, a task like "refactor the authentication module" requires Claude Code to:

Read every related file (consumes context)
Understand the current architecture (more context)
Design the new architecture (more context)
Implement the changes (context is already polluted)
Run tests (more context)

With subagents:

Explore subagent → analyzes and returns a summary
Plan subagent → designs using the summary
Main agent → implements with a clear plan and clean context
General-purpose subagent → runs tests in parallel

Less context consumed, better quality, more speed.

Module objectives

By the end of this module, you'll be able to:

✅ Use the built-in subagents: Explore, Plan, General-purpose, statusline-setup, claude-code-guide
✅ Manage subagents with the /agents command (interactive interface) and the claude agents CLI
✅ Create custom subagents with YAML frontmatter (tools, model, hooks, memory, initialPrompt, etc.)
✅ Enable persistent memory in subagents (~/.claude/agent-memory/)
✅ Define subagents inline via the --agents flag with JSON (useful for CI/CD)
✅ Understand the 5 scopes (Managed / CLI flag / Project / User / Plugin)
✅ Tell subagent, skill, and hook apart (when to use each)
✅ Install and manage plugins from the official plugin marketplace with /plugin
✅ Decide when to install a community plugin vs build your own
✅ Understand the Agent Teams model and when to scale up to multi-agent
✅ Design delegation strategies for complex tasks

Prerequisites

Required knowledge:

✅ Module 05 completed (Skills and Hooks configured)
✅ Module 04 completed (Explore → Plan → Code workflow mastered)
✅ CLAUDE.md configured in your project (Module 03)
✅ Claude Code installed and working (Module 02)

For the practice:

✅ A real project with at least 15-20 files (so the subagents have material to work with)
✅ Familiarity with the Explore → Plan → Code cycle
✅ At least one skill created in .claude/skills/

Quick check:

Before you continue, make sure you can answer these questions:

What are Claude Code's three modes and when do you use each?
What's the difference between a skill and an instruction in CLAUDE.md?
What are hooks and what are the 5 lifecycle events?

Answers

Explore (read-only analysis), Plan (design without execution), Agent/Code (full execution). The typical cycle is Explore → Plan → Code, and you can go straight to Code for simple tasks.
CLAUDE.md loads every time, at the start of each session (general project context). A skill loads on demand with /name or automatically by Claude when it detects that its description matches your request. The current format is SKILL.md + YAML frontmatter inside a directory.
Hooks are scripts/commands that run automatically on 22+ lifecycle events, including: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart/SessionEnd, PreCompact/PostCompact, SubagentStart/SubagentStop, Notification, Stop, and more. They support 4 handler types: command, http, prompt, agent. They're configured in .claude/settings.json.

If you aren't ready:

Go back to:

Module 04: The agentic workflow
Module 05: Skills and Hooks

Module roadmap

This module has 5 progressive capsules:

Capsule 01 — Module introduction (this capsule)

Context, mental model, and roadmap. You understand what subagents are, why they matter, and how they fit into the Claude Code ecosystem.

Capsule 02 — Built-in subagents

The subagents Claude Code ships with: Explore, Plan, General-purpose, statusline-setup, claude-code-guide. How they work, when they fire, what permissions each one has. When Claude creates them automatically vs when to ask for them explicitly.

Capsule 03 — Custom subagents

How to create your own specialized agents in .claude/agents/. File structure, tool configuration, and restrictions. The difference between skills and subagents. Patterns for team subagents.

Capsule 04 — Plugin marketplace

Anthropic's official marketplace (over 100 plugins) built into Claude Code. The /plugin command, installing and managing, criteria for deciding between installing and building, alternative marketplaces, security considerations.

Capsule 05 — Introduction to Agent Teams

The emerging Agent Teams model (experimental/research preview). Team lead, teammates, task board, dependency resolution. When to scale from subagents to Agent Teams.

Progression map

Capsule 01 (this one) → Mental model and context
Capsule 02            → Built-in subagents: the ones you already have
Capsule 03            → Custom subagents: the ones you build
Capsule 04            → Plugin marketplace: the ones the community built
Capsule 05            → Agent Teams: the multi-agent future

Difficulty: ⭐ ──────────────────────────────────▶ ⭐⭐⭐⭐

Capsules 01-02 are foundational — you understand and use built-in subagents. Capsule 03 is intermediate — you build your own subagents. Capsule 04 is practical — you install prebuilt capabilities from the marketplace. Capsule 05 is advanced/exploratory — it introduces the Agent Teams model, which is still in preview.

What you'll build in this module

Across the 5 capsules, you'll learn to:

Use the Explore subagent to analyze your codebase before implementing
Use the Plan subagent to design architectural solutions
Delegate parallel tasks to multiple subagents
Create a custom subagent for a repetitive task in your project
Install plugins from the official marketplace to add capabilities without building them
Understand Agent Teams and when it makes sense to scale up to multi-agent

By the end of the module, you'll know when and how to delegate work, building a workflow where Claude Code multiplies its capacity without multiplying complexity.

A look at the full module

To help you picture how the concepts fit together, here's a real scenario:

The session without subagents

You: Refactor the users module. Separate business logic
     from data access.

Claude Code (alone):
  → Reads 15 files in the users module (takes up ~30% of context)
  → Analyzes the current structure (more context)
  → Thinks through the new architecture (more context)
  → Starts implementing... but has already burned 60% of context
  → Result: incomplete implementation, has to compact
  → Loses detail in the compaction, introduces inconsistencies

Total: 8 minutes, inconsistent quality, 2 corrective iterations

The session with subagents

You: Refactor the users module. Separate business logic
     from data access.

Claude Code (as lead):
  → Launches Explore subagent: "Analyze the structure of the
    users module, identify what is business logic and what is
    data access"
  → Explore returns: a 20-line summary with the classification

  → Launches Plan subagent: "With this analysis, design the
    separation into layers: services and repositories"
  → Plan returns: a 5-step plan with files to create/move

  → Claude Code implements with clean context and a clear plan
  → Launches General-purpose subagent: "Run npm test -- --related users"
  → Tests pass

Total: 4 minutes, consistent quality, 0 corrective iterations

That's the difference. It isn't just speed — it's output quality, because each agent operates with clean, specialized context.

How this connects to what you already know

Subagents and the Explore → Plan → Code workflow (Module 04)

The Explore and Plan modes you learned in Module 04 are, internally, subagents. When you switch to Explore mode, Claude Code is using a subagent specialized in reading. When you use /plan, it uses a planning subagent. You've already used them — this module teaches you to do it deliberately and to build your own.

Subagents and CLAUDE.md (Module 03)

Subagents inherit the project context. When an Explore subagent analyzes your codebase, it has access to the conventions defined in CLAUDE.md. When you create a custom subagent, you can reference it in CLAUDE.md so the main agent knows it exists.

Subagents and Skills/Hooks (Module 05)

Skills and subagents are complementary but distinct mechanisms:

Mechanism	What it is	When to use it
Skill	Markdown instructions that Claude reads	Simple, repetitive tasks (create a component, write a test)
Subagent	A separate agent with its own context	Complex tasks that need specialization or parallelization
Hook	Automatic script on lifecycle events	Validations and automations (lint, format, test)

The rule: if the task is solved with text instructions → skill. If it needs a dedicated agent with its own reasoning → subagent. If it must run automatically → hook.

Key concepts you'll see

Parent-child model

The main agent (parent) creates subagents (children). The parent delegates, the children execute, and the children hand results back to the parent. The parent integrates and decides what happens next.

Parent (main agent)
├── Decides what to delegate and to whom
├── Receives summarized results
└── Integrates everything into a coherent response

Children (subagents)
├── Receive a specific instruction
├── Work in their own context
└── Return a compact result to the parent

Context isolation

Every subagent has its own context. They don't share the parent's context window. That's a feature, not a bug — it prevents the context pollution that degrades quality.

Concrete example: if an Explore subagent reads 30 files to analyze your codebase, those 30 files are NOT loaded into the parent's context. The parent only receives the 20-line summary the subagent produces. Result: the parent keeps its context clean for the implementation.

Tool restrictions

Not all subagents have the same tools. The Explore subagent can only read and search. The Plan subagent designs without executing. That's intentional — restrictions make subagents safer and more predictable.

Subagent	Read	Write/Edit	Execute	Search
Explore	✅	❌	❌	✅
Plan	✅	❌	❌	✅
General-purpose	✅	✅	✅	✅
statusline-setup	✅	✅	❌	❌
claude-code-guide	✅	❌	❌	✅

Automatic vs explicit

Claude Code creates subagents automatically when it detects that a task would benefit from delegation. But you can also ask for them explicitly. Knowing when to step in and when to let Claude decide is a skill you'll develop in this module.

Signs that Claude Code will use a subagent automatically:

You ask it to analyze many files (→ Explore subagent)
You use /plan (→ Plan subagent)
The task has independent, parallelizable components
You ask it to run commands while it works on something else

Connection to the capstone project

In Module 08, you'll build a complete CLI tool with Claude Code. Subagents will be an integral part of your workflow:

Explore subagent to analyze the starting template and understand the structure
Plan subagent to design the command architecture
Custom subagent (optional) for repetitive project tasks (e.g. adding a new command with all the boilerplate)
Deliberate delegation to keep context clean during long sessions

Mastering subagents doesn't just speed up your work on the capstone project — it prepares you for professional workflows where delegating to agents is the norm.

Versions and compatibility

This module covers:

Claude Code 2.0+
Opus 5 (1M token context window)
Sonnet 5 (1M token context window)

Features covered:

✅ Built-in subagents: Explore, Plan, General-purpose, statusline-setup, claude-code-guide
✅ Custom subagents in .claude/agents/
✅ Official plugin marketplace (/plugin) with over 100 curated plugins
✅ Parent-child orchestration
✅ Automatic subagent creation
⚠️ Agent Teams (research preview, experimental)

A note on change:

Built-in subagents are a fundamental part of Claude Code's architecture — the concepts are stable. Custom subagents are a more recent feature and the API may still shift. Agent Teams is in research preview and could change significantly. Always check the official documentation to confirm the current syntax.

Summary

This module is where Claude Code stops being a single agent and becomes a team of agents that you direct.

What you learned in this capsule:

Subagents let you delegate work to specialized agents
The mental model is "tech lead + team", not "a single developer"
Subagents solve three problems: context pollution, serialization, lack of specialization
There are built-in subagents (Explore, Plan, General-purpose, statusline-setup, claude-code-guide) and custom subagents that you build
The official plugin marketplace (/plugin) gives you access to over 100 prebuilt capabilities installable with one command
Skills, subagents, and hooks are complementary mechanisms with distinct purposes
Agent Teams is the next evolutionary step (experimental)

Next capsule: 02 - Built-in subagents — how Explore, Plan, General-purpose, statusline-setup, and claude-code-guide work, when they fire, and how to use them effectively.

Additional resources

Official documentation

Sub-agents — Subagent architecture and types in Claude Code
Best Practices — Recommended workflows, including delegation
Claude Code Overview — Capabilities and general architecture

Subagents and orchestration

Plugins Reference — Skills, agents, hooks, MCP bundled
Interactive Mode — Permissions and task management

Complementary

Memory — How CLAUDE.md interacts with subagents
CLI Reference — Every command and slash command

← PreviousPermission System: access control in Claude Code Next →Built-in Subagents: Claude Code's specialized agents