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

Overview

\n

Claude Code sub-agents run as isolated workers called by a primary agent. Understanding the actual communication flow prevents the two most common mistakes.

\n

How Sub-Agents Actually Work

\n
You --> prompt --> Primary Agent --> prompts --> Sub-Agent(s)\n                   Primary Agent <-- responds -- Sub-Agent(s)\n                   Primary Agent --> responds --> You\n
\n

Sub-agents respond to the primary agent, not to you. This changes everything about how you write their prompts and report sections.

\n

The Two Big Mistakes

\n

Mistake 1: Treating the Agent File as a User Prompt

\n

The .claude/agents/ file is a system prompt. Your primary agent generates the user prompt when it calls the sub-agent.

\n

Mistake 2: Forgetting Who the Sub-Agent Talks To

\n

The sub-agent's output goes to the primary agent. Structure the Report section to communicate back through the chain, not to the human.

\n

Agent File Structure

\n
---\nname: agent-slug           # Unique ID — used in sub-agent calls\ndescription: |             # MOST IMPORTANT FIELD after name\n  When to call: \"If user says X or Y, use this agent\"\n  How to prompt: \"Exactly what you want communicated\"\n  Context note: \"This agent has NO context from your conversation\"\ntools: [\"bash\", \"read\"]    # Lock down available tools\n---\n\n# Agent Title\n\n## Purpose\nOne paragraph max.\n\n## Instructions\nSystem prompt content — what the agent knows and does.\n\n## Report\nHow to format the response back to the primary agent.\n
\n

Description Field: The Most Critical Part

\n

The description field controls:

\n\n

Since sub-agents have no context from the parent conversation, the description must tell the caller exactly what context to inject.

\n
description: |\n  Use when the user asks for a work summary or TTS output.\n  When calling, include: the completed task name, files modified, and outcome.\n  The agent will format this into a spoken summary.\n
\n

Tool Locking

\n

Always restrict tools to what the agent genuinely needs. An agent that only reads files shouldn't have bash access.

\n
tools: [\"read\", \"grep\"]           # Read-only agent\ntools: [\"bash\", \"write\", \"edit\"]  # Build agent\ntools: [\"bash\"]                   # Script runner only\n
\n

Meta-Agent Pattern

\n

A meta-agent generates sub-agent YAML files dynamically. Use when building a system that needs to spawn specialized workers at runtime.

\n
---\nname: agent-factory\ndescription: |\n  Use when asked to create a new specialized agent.\n  Provide: agent purpose, required tools, trigger phrases.\ntools: [\"write\", \"bash\"]\n---\n\n# Agent Factory\n\n## Purpose\nCreates .claude/agents/*.md files from specifications.\n\n## Instructions\nGiven an agent specification, write a valid agent YAML file to `.claude/agents/<name>.md`.\nFollow the required frontmatter schema.\n\n## Report\nConfirm the agent file path created and the trigger phrases registered.\n
\n

Parallel Sub-Agent Dispatch

\n

The primary agent can call multiple sub-agents in the same turn. They run concurrently.

\n
Primary Agent:\n  - calls: file-reader (reads 3 files)\n  - calls: web-searcher (fetches 2 URLs)\n  Both run simultaneously → primary synthesizes results\n
\n

Location and Loading

\n

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.

\n

Common Agent Roles

\n

| Agent | Tools | When to Use |\n|-------|-------|-------------|\n| file-analyst | read, grep | Code review, audit |\n| build-runner | bash | Compile, test, deploy |\n| doc-writer | write | Generate markdown |\n| data-fetcher | bash (curl/httpx) | API calls, scraping |\n| summarizer | read | Condense large files |

\n

Anti-Patterns

\n\n"}