Mastering Claude Code Sub-Agents: A Guide in 10 Minutes |

Imagine starting your day, opening the terminal, firing up Claude Code, and kicking off a single prompt that accomplishes in minutes what used to take hours. This level of efficiency is achievable with Claude Code sub-agents—specialized workflows that perform one task extraordinarily well.

Code is becoming a commodity, but your fine-tuned prompts and sub-agent architecture can provide immense value. However, to unlock this potential, you must avoid several key mistakes many engineers make. This article breaks down how to build effective Claude Code sub-agents, use a powerful meta-agent to build new agents, and navigate the trade-offs and pitfalls to save you valuable time and tokens.

What Are Claude Code Sub-Agents?

First, it's crucial to understand that sub-agents likely don't work the way you think. The flow of information is critical and often misunderstood.

Here’s how the end-to-end process works: 1. You provide a prompt to your primary agent. 2. The primary agent then prompts one or more sub-agents based on your initial request. 3. The sub-agents execute their tasks autonomously. 4. Crucially, they report their results back to the primary agent, not to you. 5. Finally, the primary agent reports the consolidated results back to you.

This flow changes how you must write your sub-agent prompts. You are not directly commanding the sub-agent; you are instructing the primary agent on how to delegate tasks.

The Biggest Mistakes Engineers Make

Understanding the agent communication flow helps avoid the most common pitfalls when using sub-agents.

Mistake 1: Confusing System Prompts with User Prompts

Let's look at a simple hello-world agent prompt located in the new agents directory within a codebase.

When you trigger an agent, for example by typing Hi CC, Claude Code finds the agent with a matching description and executes it. The agent configuration looks something like this:

Agent Name: A unique ID.
Description: A vital piece of text that tells the primary agent when to call this sub-agent.
Tools: A list of specific tools the agent can use.
Color: For UI formatting.

Inside the agent's prompt file, you'll find a markdown structure, often with purpose and report sections. The first major mistake is not realizing that you are writing the system prompt for the sub-agent, not the user prompt.

This isn't a minor detail. It fundamentally changes how you should write the prompt and what information is available to the agent. A user prompt (like /prime) goes directly into the primary agent's context window. A sub-agent's prompt is a system prompt that defines its core behavior and top-level functionality.

Mistake 2: Misunderstanding Who the Sub-Agent Responds To

The second, even bigger mistake, is forgetting who the sub-agent is reporting to. Your sub-agents respond to the primary agent, not to you.

This means your sub-agent's prompt must be structured to communicate effectively with another AI. For instance, you should explicitly instruct the sub-agent on how to format its report for the primary agent.

Consider this example from a sub-agent's system prompt:

Claude, respond to the user with this message: "Hi there. How can I help you? Did you know [random tech news]..."

The sub-agent researches the information and then passes the fully formed message to the primary agent, which then delivers it to you. This explicit instruction is key.

The Core of Agentic Systems: Context, Model, and Prompt

The "big three"—Context, Model, and Prompt—are more important than ever in multi-agent systems. The flow of these elements between different agents is what determines success. If you misunderstand this, your agentic workflows will eventually fail, especially as you scale to more complex chains of sub-agents.

You can chain calls and responses, creating sophisticated workflows. You prompt the primary agent, which runs a task, which might involve firing off a sub-agent. The result comes back to the primary agent, which can then fire off another set of sub-agents. We're still prompt chaining, just with larger, more powerful compositional units.

A Practical Guide: Building a Meta-Agent

To truly scale your efficiency, you can build agents that build other agents. This is the concept of a "meta-agent."

A common issue in the generative AI space is creating solutions for problems that don't exist. A professional engineer works the other way around: 1. Problem: Identify a real-world problem. 2. Solution: Design a solution. 3. Technology: Choose the right tech to implement the solution.

Let's apply this with a concrete example:

Problem: When running multiple agents at scale, it's easy to lose track of what each one has completed.
Solution: Add text-to-speech notifications to agents so they announce when they're done and what they've accomplished.
Technology: Use a meta-agent to build a new, reusable text-to-speech (TTS) sub-agent.

First, we need to understand the available tools. We can use a simple reusable prompt to list them:

List all available tools in your system prompt. I want bullet points. I want TypeScript function signature format.

This allows us to discover the necessary tools, such as textToSpeech and playAudio.

textToSpeech(voiceId: string, text: string, outputDirectory: string): { success: boolean, filePath: string, error: string }
playAudio(filePath: string): { success: boolean, error: string }

After validating the workflow manually in the primary agent's context window, we can encapsulate this logic into a new agent using our powerful meta-agent. The meta-agent has a system prompt that details how to create a new agent configuration file based on a user's description.

Here's a prompt for our meta-agent:

Build a new sub-agent. When a user asks you to create a new sub-agent, use the following description to generate a new, complete sub-agent configuration file. The new agent should provide a text-to-speech summary of work completed. It should get the current working directory, use the text-to-speech tool to generate an audio file, and then use the play tool to play the audio.

The meta-agent will then generate the new agent file.

Refining the New Agent

After the meta-agent creates the agent, it's crucial to review and refine it. A few key tweaks can make it far more effective.

Add Trigger Keywords to the Description: The description determines when the primary agent calls the sub-agent. Adding explicit triggers makes it more reliable.

Description: If the user says "TTS" or "TTS summary," use this agent to provide a text-to-speech summary of the work completed.
Instruct the Primary Agent: You can use the description to tell the primary agent how to prompt the sub-agent.

When you prompt this agent, describe exactly what you want it to communicate to the user. Remember, this agent has no context of any previous conversations between you and the user.
Set Best Practices: To ensure reliability, you can add constraints within the agent's system prompt.

IMPORTANT: Run only bash pwd and the 11labs tools. Do not use any other tools. Base your response exactly on the information provided.

With these refinements, you now have a robust, reusable agent that can provide audio summaries for any task, solving the original problem for good.

The Benefits of Sub-Agents

Anthropic lists several key benefits of using sub-agents:

Context Preservation: Each sub-agent operates in its own isolated context, preventing pollution of the main conversation. This is powerful for scaling agents across large codebases.
Specialized Expertise: You can fine-tune instructions and tools for highly specific tasks.
Reusability: By storing agents in your repository, you can build a library of tools tailored to your codebase.
Flexible Permissions: You can lock down which tools each agent is allowed to call.

Beyond these, there are a couple of hidden benefits:

Focused Agents: Because a sub-agent is fresh and only knows what the primary agent tells it, it's less likely to make mistakes. It's focused on one thing and performs better.
Simple Multi-Agent Orchestration: Combining sub-agents with custom slash commands and hooks allows you to build powerful yet simple multi-agent systems. For example, you could create a /prime-tts command that runs a primary task and then chains your TTS summary agent at the end.

The Downsides and How to Mitigate Them

However, there are also several issues to be aware of:

Lack of Context History: The flip side of context preservation is that a sub-agent has no history. It only knows what the primary agent prompts it with. You must be very clear and provide all necessary information in the prompt.
Difficult to Debug: Sub-agent workflows can be opaque. You don't see the full internal prompts or parameters for every tool call, making it hard to understand what's going on when something breaks.
Decision Overload: As you add more agents, the primary agent might get confused about which one to call.
- Solution: Be extremely clear in your agent descriptions about when each one should be called.
Dependency Coupling: As you build chains of agents, they can become dependent on each other's specific output formats. A change in one agent can break the entire chain.
- Solution: Try to keep workflows isolated and avoid overloading your sub-agent chains.
No Recursive Calls: You cannot call a sub-agent from within another sub-agent, at least not yet. This limits the complexity of the hierarchies you can build.

Sub-agents are a powerful feature for any engineer looking to leverage AI for complex tasks. By understanding how they work, avoiding common pitfalls, and building robust, reusable components, you can significantly enhance your productivity and build sophisticated multi-agent systems.