Subagents — Delegation Class: Assigning Tasks to AI Assistants
A main agent should not take on all tasks — just like a company cannot have one person acting as CEO, accountant, legal advisor, marketer, developer, and QA all at once. When a single agent is tasked with reading logs, running tests, writing code, and researching documentation, its context quickly becomes cluttered with noise, and the quality declines.
Subagents are the solution: they delegate tasks to child agents, each with its own context, tools, permissions, and responsibilities. The main agent acts as a coordinator; the subagents handle the specialized work. This is the organizational mindset for team structures in the AI era.
What is a Subagent
A subagent is a separate instance of Claude, running in its OWN context window, with its own system prompt, tool access, and permissions. When a task matches the description of a subagent, the main agent delegates; the subagent works independently and then only returns a summary of the results to the main stream (Anthropic — Subagents in Claude Code).
The key point lies in the bolded sentence: the subagent works within its own context window. Search results, logs, and files read for exploration — all never touch the main conversation (Claude Docs — Subagents). This is why subagents protect context very effectively.
Four Main Benefits
- Context Preservation — isolating operations that generate multiple outputs (reading logs, scanning codebase) into subagents so that the main stream does not become "flooded."
- Enforced Constraints — limiting the tools of the subagent (e.g., read-only, no write access) so it cannot perform actions outside its scope.
- Reusability & Specialization — define once, reuse across multiple projects; each subagent has its own "personality" and expertise.
- Cost Control — routing subagents to a cheaper model (e.g., Haiku) for simpler tasks.
Claude Code comes with several pre-built subagents, such as Explore (read-only — find/understand codebase) and Plan (research in planning mode). They intentionally skip certain steps to run quickly and cheaply.
Defining a Subagent: Markdown File + Frontmatter
A subagent is a .md file placed in .claude/agents/ (project scope) or ~/.claude/agents/ (personal scope) (Claude Docs — Subagents):
---
name: code-reviewer
description: Review code quality and security. Use proactively after
completing a major change.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When called, analyze the changes and provide specific
feedback on quality, security, and best practices. Read only, do not modify.- Required:
name(lowercase + hyphen) anddescription(describing when to delegate). - Optional:
tools,disallowedTools,model(sonnet/opus/haiku/inherit),permissionMode,maxTurns,skills,mcpServers,hooks,memory... - The body = system prompt of the subagent.
An important and often misunderstood point: a subagent only receives this system prompt along with basic environmental information. It does not receive the full system prompt of Claude Code, and does not see the main conversation history. It starts fresh and only receives a "task message" prepared by Claude itself (Claude Docs — Subagents).
When names overlap, the order of priority is based on position: managed (highest) → CLI → project → user → plugin (lowest).
How to Call a Subagent
- Automatically: based on
description; add phrases like "use proactively" to encourage delegation. - Call by natural name in the prompt, or @-mention to ensure the correct subagent runs.
- Entire session under one subagent:
claude --agent <name>.
Writing a good description is key: it is the basis for the main agent to decide on delegation. Vague descriptions → either never called, or called incorrectly at times.
Fan-out: Running Multiple Subagents in Parallel
The greatest power for scaling is fan-out: the main agent spawns multiple independent subagents running in parallel, then aggregates the results. For example: reviewing a large codebase by assigning each module to a subagent; or researching a topic by having multiple subagents query different sources simultaneously and then compile the results (Claude Docs — Workflows).
Common usage patterns:
- Code review: a read-only subagent checks quality/security.
- Run tests: a subagent runs tests and only reports failures.
- Parallel research: multiple subagents query simultaneously.
- Sequential chain: reviewer → optimizer (this agent follows the previous agent).
Best Practices
- Accurate description + narrow tool scope. Start with read-only permissions, only expand when necessary.
- Focused prompt. The body should clearly state the role and limits, as the subagent lacks the main context.
- Isolate large outputs. Read logs, scan files — push into the subagent to keep the main flow tidy.
- Commit project scope. Place subagents in
.claude/agents/and commit for the whole team to share.
Limitations & Pitfalls
- Fresh context can sometimes take time to gather context — subagents are not suitable for tasks that require back-and-forth with the user.
- Limited nesting depth. In the Claude Agent SDK, subagents can nest up to 5 levels; in Claude Code, according to the Vietnamese community documentation (AZDIGI), a subagent cannot call another subagent — so verify according to the product context you are using.
- With agents provided by PLUGIN: some configurations like
hooks,mcpServers,permissionModeare not supported (for security reasons). - UI-interactive tools cannot be used within a subagent.
An Important Misunderstanding
Many people think subagents "see everything" from the main session. The reality is the opposite: it starts fresh and only receives the task message. This is both a strength (protecting context, delegating permissions) and a point to note (the task must be described clearly, as the subagent does not "know" the main context by itself).
Quickly distinguish from other layers: **Skill changes behavior, Subagent protects context and delegates permissions, MCP adds capabilities, Hook ensures deterministic actions.** The four layers complement each other, not replace each other.
Summary & Next Steps
Subagents are a delegation layer: each subagent is a separate Claude with its own context, tools, and permissions, defined by a Markdown file in .claude/agents/, delegated via description, and is most powerful when fan-out occurs in parallel. They keep the main flow tidy and allow you to build an entire "team" of AI.
At this point, you have four layers: memory (CLAUDE.md), expertise (Skills), control (Hooks), and delegation (Subagents). But how do you share this entire configuration with the team, rather than having each person recreate it? That is the role of Plugins — Article 5.
References
- Anthropic — How and when to use subagents in Claude Code: https://claude.com/blog/subagents-in-claude-code
- Claude Docs — Create custom subagents: https://docs.claude.com/en/docs/claude-code/sub-agents
- Claude Docs — Subagents in the SDK: https://docs.claude.com/en/docs/claude-code/sdk/subagents
- Claude Docs — Orchestrate subagents with dynamic workflows: https://code.claude.com/docs/en/workflows
- AZDIGI — Guide to using Subagents (Vietnamese): https://azdigi.com/blog/tri-tue-nhan-tao/huong-dan-dung-subagents-trong-claude-de-tao-doi-tro-ly-ai-thong-minh
Article 4/7 in the "Agent Development Toolkit with Claude" series. Content rephrased from the original documentation by Anthropic. Previous ← Article 3: Hooks · Next → Article 5: Plugins & Marketplace.