The Right Way to Use Claude Code Sub-Agents: 3-5 Beat 100 Every Time

Why Are Your Sub-Agents Slow and Blowing Up?

Many Claude Code users work with Sub-Agents, but few truly understand the underlying mechanism. Even more absurd — some people have installed over 100 Agents, only to end up with a system that's both slow and token-explosive. The root cause is simple: more isn't better; every Agent needs a clear responsibility boundary.

Sub-Agents are essentially Claude Code's "clones" — you give each clone a specialized focus and a set of tool permissions, and it works in an isolated window without polluting your main conversation. This is context isolation, and it's the core value of Sub-Agents.

Today we'll start with the official built-in Agents, move to custom configurations, then cover the three major community solutions (ECC, Superpowers, GizTech) — giving you a complete understanding of Sub-Agents in one go.

The 5 Official Built-in Sub-Agents Explained

The official documentation is clear: 3 core + 2 auxiliary = 5 total.

The Core Three

1. Explore — The Cheapest, Fastest Search Expert

• Uses the Haiku model (cheapest)
• Read-only permissions
• Does NOT load the project's CLAUDE.MD (to maintain speed and low cost)
• Use case: Having Claude locate where a specific function lives

2. Plan — The Deep Analysis Planner

• Automatically activates when entering Plan Mode
• Uses a stronger model with deeper analysis than Explore
• Outputs an implementation plan after researching the codebase
• Also does NOT load CLAUDE.MD

3. General Purpose — The Only All-Rounder

• Can read, write, and run commands
• DOES load CLAUDE.MD (because it needs project context to modify code)
• Use case: "Investigate this bug and fix it for me"

The Two Auxiliary Agents

• Claude Code Guide: Answers questions about Claude Code configuration, MCP setup, etc.
• Status Line Setup: Configures terminal status bar

These two trigger automatically — no need to manage them.

4 Key Fields for Custom Sub-Agents

Are the official 5 enough? For most people, yes. But if you want to go further, Claude Code lets you create your own Sub-Agents by simply creating an MD file in the .claude/agents/ directory.

There are only 4 key configuration fields:

Field	Purpose	Recommendation
Name	Name the Agent	Keep it concise
Description	Most important — determines when it triggers	The more specific, the more accurate the trigger
Model	Choose the model	Haiku for search, Sonnet for coding, Opus for complex reasoning
Tools	Tool permissions	Read-only gets Read/Grab/Globe; code modification adds Edit/Write

How you write the Description determines trigger accuracy. For example, writing "must be used for database migrations" means Claude knows to dispatch this Agent whenever database migrations come up.

Dedicated MCP Servers Configuration

A highly practical field: you can declare dedicated MCP servers in the Agent's YML header. This MCP only loads when that Agent starts — the main conversation and other Agents can't see it.

For example, configure a database analysis Agent with a dedicated PostgreSQL MCP attached. It loads when needed and shuts down when done, wasting no resources.

Three Common Pitfalls

Pitfall 1: MCP Inheritance Issues

Custom Agents inherit the main conversation's MCP by default. But if your Tools field is incomplete (e.g., only specifying Tools: Read, Bash), MCP tools may get stripped. For stable MCP inheritance, either omit the Tools field entirely or use wildcards.

Pitfall 2: Token Trap

When each MCP loads, its tool descriptions get stuffed into the context. If you attach a bunch of MCPs to an Agent without limiting Tools, tokens explode — latency spikes and costs soar. Solution: subtract from your Agent; only give it the tools it needs.

Pitfall 3: CLAUDE.MD Inheritance Rules

Custom Agents inherit CLAUDE.MD, but the built-in Explore and Plan do not. The official statement: "Explore and Plan are the only sub-agents that skip CLAUDE.MD and Git status — no configuration can change this."

Comparing the Three Major Community Sub-Agent Solutions

ECC: The Specialized Division of Labor Approach

• 63 Agents, all MD files in the agents directory
• Deliberate model selection: 6 use Opus for deep reasoning, 55 use Sonnet for daily tasks, 1 uses Haiku
• Layered tool permissions: Reviewer types get read-only; Build/Resolver types get write access
• Highlight: All 63 Agents share 7 security guardrails against prompt injection and privilege escalation

Superpowers: The Process Discipline Approach

• Defines three Agent roles: Implementer, Spec Reviewer, Code Quality Reviewer
• Core mechanism: Sequential enforcement — spec review must pass before code quality review can be dispatched; no skipping
• Agents aren't manually triggered; Skills automatically dispatch them within workflows

GizTech: The Role-Switching Approach

• Uses SKL.MD files to define roles: CEO, Engineer, Designer, QA
• Claude switches identities based on Skill instructions
• Unique design: Ask User Question decision format — every time a user decision is needed, it provides explanation, analysis, recommended reasoning, and a completeness score

Summary of the Three Approaches

Solution	Philosophy	Best For
ECC	One Reviewer per language, specialized division	Large multi-language projects
Superpowers	Skills invoke Sub-Agents with process discipline	Teams requiring strict review
GizTech	Claude wears different hats, switching roles	Full-stack solo development

Sub-Agent Selection Advice: Less Is More

How to choose? Here's a tiered framework:

Tier 1: Master the official 5 first. They work out of the box — no installation needed.

Tier 2: Expand as needed. Use GizTech's review approach for team collaboration; use ECC's security pipeline for security-sensitive projects.

Core principle: 3-5 is the sweet spot. Beyond 10, Claude Code actually doesn't know who to dispatch, and trigger accuracy drops off a cliff.

Remember these two principles: Context isolation. Permission control.

Used well, Sub-Agents transform your Claude Code from a solo operator into a full team. But always remember — 3 to 5 that actually work are a hundred times better than 100 that never trigger.