Overview
Claude Code sub-agents run as isolated workers called by a primary agent. Understanding the actual communication flow prevents the two most common mistakes.
How Sub-Agents Actually Work
You --> prompt --> Primary Agent --> prompts --> Sub-Agent(s)
Primary Agent <-- responds -- Sub-Agent(s)
Primary Agent --> responds --> You
Sub-agents respond to the primary agent, not to you. This changes everything about how you write their prompts and report sections.
The Two Big Mistakes
Mistake 1: Treating the Agent File as a User Prompt
The .claude/agents/ file is a system prompt. Your primary agent generates the user prompt when it calls the sub-agent.
Mistake 2: Forgetting Who the Sub-Agent Talks To
The sub-agent's output goes to the primary agent. Structure the Report section to communicate back through the chain, not to the human.
Agent File Structure
---
name: agent-slug # Unique ID — used in sub-agent calls
description: | # MOST IMPORTANT FIELD after name
When to call: "If user says X or Y, use this agent"
How to prompt: "Exactly what you want communicated"
Context note: "This agent has NO context from your conversation"
tools: ["bash", "read"] # Lock down available tools
---
# Agent Title
## Purpose
One paragraph max.
## Instructions
System prompt content — what the agent knows and does.
## Report
How to format the response back to the primary agent.
Description Field: The Most Critical Part
The description field controls:
- When the primary agent invokes this sub-agent
- How the primary agent prompts it
- Whether the primary agent provides enough context for the sub-agent to succeed
Since sub-agents have no context from the parent conversation, the description must tell the caller exactly what context to inject.
description: |
Use when the user asks for a work summary or TTS output.
When calling, include: the completed task name, files modified, and outcome.
The agent will format this into a spoken summary.
Tool Locking
Always restrict tools to what the agent genuinely needs. An agent that only reads files shouldn't have bash access.
tools: ["read", "grep"] # Read-only agent
tools: ["bash", "write", "edit"] # Build agent
tools: ["bash"] # Script runner only
Meta-Agent Pattern
A meta-agent generates sub-agent YAML files dynamically. Use when building a system that needs to spawn specialized workers at runtime.
---
name: agent-factory
description: |
Use when asked to create a new specialized agent.
Provide: agent purpose, required tools, trigger phrases.
tools: ["write", "bash"]
---
# Agent Factory
## Purpose
Creates .claude/agents/*.md files from specifications.
## Instructions
Given an agent specification, write a valid agent YAML file to `.claude/agents/<name>.md`.
Follow the required frontmatter schema.
## Report
Confirm the agent file path created and the trigger phrases registered.
Parallel Sub-Agent Dispatch
The primary agent can call multiple sub-agents in the same turn. They run concurrently.
Primary Agent:
- calls: file-reader (reads 3 files)
- calls: web-searcher (fetches 2 URLs)
Both run simultaneously → primary synthesizes results
Location and Loading
Sub-agent files live in .claude/agents/ (project-level) or ~/.claude/agents/ (global). Claude Code discovers them automatically at startup. Changes require restart or explicit reload.
Common Agent Roles
| Agent | Tools | When to Use | |-------|-------|-------------| | file-analyst | read, grep | Code review, audit | | build-runner | bash | Compile, test, deploy | | doc-writer | write | Generate markdown | | data-fetcher | bash (curl/httpx) | API calls, scraping | | summarizer | read | Condense large files |
Anti-Patterns
- Overly broad descriptions — triggers on wrong inputs, wastes tokens
- Missing context instructions — sub-agent fails because it lacks info the primary has
- No tool restriction — security risk and unpredictable behavior
- Report section missing — sub-agent output arrives in wrong format for the primary