Module 1: Custom Subagents

1. Module Introduction — Beyond Basic Task()

Description

This module transforms your relationship with Claude Code. So far you've used subagents as black boxes — "do this and give me back the result." That works for one-off tasks, but it doesn't scale. When you need an agent that only reviews code without being able to modify it, another that implements features following specific conventions, and a third that runs tests and reports results in a concrete format — you need subagents with an identity of their own.

The difference between delegating a generic task and designing a specialized subagent is the same as between hiring "someone who codes" and hiring a senior backend engineer with experience in FastAPI and PostgreSQL. Specificity defines the quality of the result. In this module you'll learn to create that specificity: clear roles, tool restrictions, system prompts that define behavior, and structured communication between agents.

By the end, you'll have 3 specialized subagents (reviewer, implementer, tester) working in a real development flow. Not as a demo — as a tool you can use tomorrow in your project.

Where Are We in the Guide?

Context in the Path

This is Guide #9 of the Claude Code Agentic Development Path. In the previous guides you learned to operate Claude Code: from basic installation to advanced prompt engineering, CLAUDE.md, hooks, MCP servers, and basic subagent usage. You know how everything works. Now you're going to learn to orchestrate systems where multiple agents work in a coordinated way.

Guides #1-4: Foundations and Prompt Engineering    ← completed
Guides #5-8: Intermediate Claude Code              ← completed
▶ Guide #9: Advanced Claude Code Workflows         ← YOU ARE HERE
Guide #10: Claude Code in CI/CD Pipelines          ← next
Guide #11: Security for AI-Generated Code          ← after

There's an enormous difference between knowing how to use a tool and knowing how to orchestrate a team of tools. The previous guides taught you Claude Code as an individual tool. This guide teaches you to direct a team of Claude Code agents.

Context in the Guide

This guide has 8 modules organized into 3 phases:

Phase 1: Advanced Subagents (Modules 1-3)
├── Module 1: Custom Subagents                    ← YOU ARE HERE
├── Module 2: Agent Memory and Scopes
└── Module 3: Parallel Sub-Agent Delegation

Phase 2: Agent Teams and Plugins (Modules 4-6)
├── Module 4: Agent Teams
├── Module 5: Plugins: Creating and Distributing
└── Module 6: Advanced Hooks and Headless SDK

Phase 3: Orchestration (Modules 7-8)
├── Module 7: Remote Control and CLAUDE.md for Teams
└── Module 8: Project: Complete Multi-Agent System

Total estimated duration: 8-10 hours (self-paced).

Where are we headed?

This module opens Phase 1 because everything that follows depends on well-defined subagents:

First you learn to create agents with an identity of their own (this module) — without this, Agent Teams are just groups of generic agents
Then you configure persistent memory (module 2) — your subagents remember context across sessions
Next you delegate in parallel (module 3) — multiple subagents working simultaneously
You formalize coordination with Agent Teams (module 4) — team lead, task board, dependencies
You package functionality into plugins (module 5) — distributing reusable configurations
You automate with hooks and the SDK (module 6) — full programmatic control
You operate remotely and standardize (module 7) — remote control and CLAUDE.md for teams
You integrate everything into a multi-agent system (module 8) — the culminating project

The Problem: Generic Subagents Don't Scale

A scenario you've lived

You have a project with 20 files. You need three things: review the recent code, implement a new feature, and run the tests. With basic Claude Code, you do this in a single conversation — sequential, manual, and with the context piling up.

With basic subagents, you delegate each task separately:

"Review the code"        → Generic subagent → result OK, but it reviewed everything including tests
"Implement login"        → Generic subagent → implemented, but changed existing conventions
"Run the tests"          → Generic subagent → ran tests, but didn't report coverage

Each subagent did something, but none did exactly what you needed. Why? Because they were all generic. No defined role, no restrictions, no specific instructions about what to look for, what to ignore, and how to report.

What changes with custom subagents

With specialized subagents, the same task looks like this:

reviewer    → Only reads code, looks for 8 specific criteria, reports by priority
implementer → Only edits files in src/, follows CLAUDE.md conventions, doesn't touch tests
tester      → Runs tests, reports coverage, lists the failing ones with root cause

Each agent knows exactly what to do, what it can touch, and what format to use for reporting. The difference isn't subtle — it's the difference between "someone who codes" and a team with defined roles.

The cost of not specializing

Without specialization, each delegation requires repetitive instructions in the prompt. You write the same context over and over. And when you forget a detail, the subagent makes decisions for you — it edits files it shouldn't have, uses an inconsistent style, or ignores existing tests.

A custom subagent you configure once. Then you use it a hundred times with the same quality.

Module Objective

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

✅ Create a custom subagent as a Markdown file with YAML frontmatter that defines name, description, model, and tools
✅ Write effective system prompts that define the subagent's role, work criteria, and output format
✅ Restrict tools per subagent — a reviewer that can only read, an implementer that can edit, a tester that only executes
✅ Configure subagents at the project level (.claude/agents/) and the user level (~/.claude/agents/)
✅ Orchestrate a flow of 3 sequential subagents: reviewer → implementer → tester

Professional objective

Tomorrow, when you open a real project, you won't delegate generic tasks to Claude Code. You'll create a .claude/agents/reviewer.md file that defines exactly how you want code to be reviewed. An implementer.md that follows your team's conventions. A tester.md that reports in the format your CI expects. These agents are shared with your team via git and produce consistent results regardless of who invokes them.

Module Roadmap

Capsule map

#	Capsule	What you'll learn	Type
01	Introduction (this one)	Context, objectives, why custom subagents matter	Intro
02	Roles with System Prompts	Creating subagents as Markdown files, defining roles with effective system prompts, subagent scopes	Technical
03	Tool Restriction	Controlling what each subagent can do: tools allowlist, disallowedTools, permission modes, validation hooks	Technical
04	Output Parsing and Communication	Chaining subagents, parsing outputs, communication patterns between agents	Technical
05	Project: 3 Specialized Subagents	Building a functional reviewer → implementer → tester flow in a real project	Project

Learning flow

First you'll understand how to define a subagent with an identity of its own — the Markdown file, the YAML frontmatter, and the system prompt that defines its behavior (capsule 02). With that foundation, you'll learn to restrict what it can do — because a reviewer that edits files isn't a reviewer (capsule 03). Then you'll see how subagents communicate — the output of one is the input of the next, and parsing that communication is a skill (capsule 04). Finally, you'll build a functional system of 3 agents working in sequence on a real project (capsule 05).

The progression is: define identity → restrict capabilities → connect agents → build system.

Each capsule builds directly on the previous one. Don't jump to 04 without mastering 02 and 03 — communication between agents requires that each one has a clear role and restrictions first.

Estimated module duration: 1-1.25 hours.

Connection to the Project

This module's mini-project: 3 Specialized Subagents

In capsule 05 you'll build a development flow with three subagents:

Reviewer — Analyzes recent code, looks for quality and security problems, reports by priority (critical/warning/suggestion). It can only read — it doesn't modify anything.
Implementer — Receives the reviewer's report and makes the corrections. It can only edit files in src/. It follows the conventions defined in CLAUDE.md. It doesn't touch tests.
Tester — Runs the test suite after the implementer's changes. It reports passing, failing, and coverage. It can only run commands — it doesn't edit code.

Your prompt:
"Review the recent changes, fix the problems, and verify that the tests pass"

↓

reviewer (read-only)        → Report: 2 critical, 3 warnings
    ↓
implementer (edit src/)     → Fixes the 2 critical and 2 warnings
    ↓
tester (bash only)          → 18/18 tests pass, 87% coverage

Connection to the final project (Module 8)

The subagents you create here are the building blocks of everything that follows. In module 3, they'll be delegated in parallel. In module 4, they'll become teammates of an Agent Team. In module 8 (capstone project), they'll be the 4 specialized agents of the complete multi-agent system. Without well-defined subagents, the entire system fails.

Prerequisites

Required knowledge

✅ Claude Code installed and operational — Previous guides in the path completed
✅ CLAUDE.md configured — At least one project with a functional CLAUDE.md
✅ Experience with basic subagents — You've used Task() or delegated tasks to explore/general-purpose subagents
✅ Git and advanced terminal — You navigate repositories, do branching, resolve conflicts
✅ Intermediate programming — Python or TypeScript at a real-project level

Quick check

If you can answer "yes" to these questions, you're ready:

Have you delegated at least one task to a subagent in Claude Code?
Do you know what a system prompt is and why it matters for an agent?
Do you have a project with at least 5 files where you can practice?
Do you know what git diff HEAD~3 does and why a reviewer would need it?

You don't need

❌ Experience with Agent Teams — covered in module 4
❌ Knowledge of advanced hooks — covered in module 6
❌ Experience with plugins or the SDK — covered in modules 5 and 6
❌ A large or complex project — it works with any codebase of 5+ files

Module Setup

What you need to have ready

1. A project with Claude Code configured:

You need a real project with multiple files. If you don't have one handy, you can use any cloned open source project. What matters is that it has:

At least 5-10 source code files
A basic CLAUDE.md
Existing tests (ideally)
Git history with at least 3 commits

2. Claude Code up to date:

claude --version

Make sure you have version 2.1.63 or later — the most recent versions use the Agent tool (a rename of the Task tool) and support all the subagent features we'll cover.

3. Agents directory:

Verify that the agents directory exists:

# For project-level subagents
mkdir -p .claude/agents

# For user-level subagents (available across all projects)
ls ~/.claude/agents/ 2>/dev/null || mkdir -p ~/.claude/agents

4. Get familiar with the /agents command:

Open Claude Code and run:

/agents

You'll see the available subagents (built-in and custom). This command will be your main tool for managing subagents.

Key Concepts We'll Use

Before diving into the technical capsules, make sure these concepts are clear:

Subagent: A separate instance of Claude that executes a specific task with its own context, system prompt, and tools. It doesn't share context with the main conversation.
System prompt: The Markdown text that defines the subagent's behavior — what it does, how it does it, what it looks for, and what format it uses to report.
YAML frontmatter: The configuration section at the start of the subagent's file that defines name, description, tools, model, and permissions.
Tool restriction: Limiting which tools a subagent can use. A reviewer with only Read/Grep/Glob can't modify your code.
Scope: Where the subagent lives — project (.claude/agents/) or user (~/.claude/agents/). It defines its availability reach.

Limits: What Is NOT Covered in This Module

❌ Agent Teams — Covered in Module 4. Here you work with individual, sequential subagents
❌ Memory and persistence across sessions — Covered in Module 2. Here subagents start from scratch each time
❌ Parallel delegation — Covered in Module 3. Here subagents work in sequence
❌ Advanced hooks — Covered in Module 6. Here we use basic validation hooks when necessary
❌ Plugins — Covered in Module 5. Here subagents are local files, not distributable packages
❌ Headless SDK — Covered in Module 6. Here everything is interactive in Claude Code

Evidence of Success

By the end of this module, you'll know you succeeded if:

✅ You can create a subagent as a Markdown file with complete YAML frontmatter in under 5 minutes
✅ Your reviewer subagent reviews code without being able to modify any file
✅ Your implementer subagent modifies only the files you specified and follows CLAUDE.md conventions
✅ Your tester subagent runs tests and reports results in a structured format
✅ The 3 subagents work in sequence producing a functional end-to-end flow
✅ You can explain to a colleague why a custom subagent beats a generic delegation

Quick self-assessment test

If you can answer these questions by the end of the module, you're on the right track:

What's the difference between a generic subagent and a custom one?
Where are subagent files stored and what defines their scope?
Which fields are required in a subagent's YAML frontmatter?
Why shouldn't a reviewer have access to Write and Edit?
How is one subagent's result communicated to another in a sequential flow?

Note on Experimental Features

The subagent features we cover in this module are stable and GA (Generally Available). Subagents as Markdown files, the YAML frontmatter, tool restriction, and sequential delegation are core Claude Code functionality.

Experimental features like Agent Teams (module 4) are explicitly marked when we cover them. This module doesn't use any experimental feature.

Last functionality check: March 2026

Summary

This module establishes the foundation for the entire guide — custom subagents are the building block of Agent Teams, plugins, and multi-agent orchestration
The key difference: a generic subagent does "something"; a custom subagent does exactly what you need with clear restrictions
You'll learn to create subagents as Markdown files with YAML frontmatter that define role, tools, model, and permissions
System prompts are the most important skill — the quality of the subagent depends directly on the quality of the instructions you give it
The mini-project builds a flow of 3 agents (reviewer → implementer → tester) that you can use in real projects
Everything learned here is used in modules 2-8 — without well-defined subagents, nothing that follows works

Additional Resources

Create Custom Subagents (Anthropic Docs) — Complete official documentation of subagents in Claude Code
CLI Reference — Claude Code — Reference for flags like --agents to define subagents via CLI
Claude Code Best Practices — General best practices that apply to subagents
Hooks Reference — Reference for hooks used for validation in subagents
Claude Code Overview — General context of Claude Code as a coding agent
Skills Documentation — Skills that can be preloaded into subagents

Next capsule: In capsule 02 you'll create your first custom subagent — a Markdown file with YAML frontmatter and a system prompt that defines exactly what it does, how it does it, and what tools it can use. You'll see the difference between a generic subagent and one designed with purpose.

Next →2. Defining Roles with Subagent Files and System Prompts