Mastering Claude Code Sub-Agents: A Guide to Avoiding Common Pitfalls

Imagine starting your day. You of course open up the terminal. You fire up Claude Code. Then you kick off a single prompt that does the work it used to take you hours in mere minutes. You're able to accomplish this with Claude Code sub-agents. You've created workflows of specialized agents that do one thing and do it extraordinarily well.

For instance, you could have a meta-agent where your agents are building other agents. Code is a commodity; your fine-tuned prompts can be valuable. And now, your Claude Code sub-agents can yield extreme value for your engineering if you know how to avoid the two big mistakes engineers are making with them.

In this article, we're going to break down how to build effective Claude Code sub-agents. We'll use a powerful meta-agent to build new agents. But before we get there, sub-agents have serious trade-offs and pitfalls you should know about so you don't waste your engineering time and tokens. Let's understand how to take our agentic coding to the next level with Claude Code sub-agents.

What Exactly Are Sub-Agents?

First things first, what are Claude Code sub-agents? I can almost guarantee you sub-agents don't work like you think they do. Let me explain.

Here's what the flow of Claude Code agents looks like end-to-end:

1. It starts with your prompt.
2. Your primary agent then prompts your sub-agents.
3. Your sub-agents do their work autonomously.
4. This is important: They report back to your primary agent.
5. Your primary agent reports back to you.

The flow of information here is absolutely critical. You prompt your primary agent, and then your primary agent prompts individual sub-agents based on your original prompt. Your sub-agents respond not to you; they respond to your primary agent. Many engineers are going to miss this fact, and this changes the way you write your sub-agent prompts.

Let's break down exactly what Claude Code sub-agents look like. Inside this codebase, we have a simple "hello world" agent prompt, operating inside of the brand new agents directory.

We'll start simple to understand what sub-agent prompts look like. Let's open up a new shell and fire up Claude in yellow mode.

Hi CC

You'll notice in the description for the agent, it says: if they say hi claude or high CC or high claude code, use this agent. And now Claude Code immediately finds this agent, finds the description, and kicks it off.

An agent definition includes: - name: Its unique ID. - description: Very important. This communicates to your primary agent when it should call this agent. - tools: You can specify specific tools available. - sub_agent_complete: A message on completion. - color: The display color in the terminal.

The First Big Mistake

If we look at this format, there's something really important here, and we're coming up on the first big mistake engineers are making when using Claude Code sub-agents. If we open up the prompt file, you can see a classic markdown format with purpose and report.

The first mistake engineers make is not understanding that what you're writing here is the system prompt of your sub-agent. This is not the prompt for your agent. It's the system prompt. This might not seem like an important detail, but it changes the way you write the prompt and what information is available.

The Second, Even Bigger Mistake

An even bigger mistake is this: notice the report section. Remember who your sub-agents are responding to. It's not you; it's your primary agent. This response format is going to be really important.

You can see here I'm explicitly having the sub-agent communicate to the primary agent:

Claude, respond to the user with this message:

And guess what happened? The response was: Hi there. How can I help you? Did you know Nvidia... We had it research some random tech news.

The sub-agent prompt format includes variable declarations at the top, and then the system prompt. You can see this right in the official documentation. To be super clear, this is not the user prompt. When you write a command like /p prime, that runs right into our primary agent as a user prompt. The agents directory is different; it defines the top-level functionality via system prompts.

If you understand this, you're going to perform very well with your sub-agents and avoid the top two mistakes. You don't prompt your sub-agents directly. You write a prompt for your primary agent to prompt your sub-agents. You are communicating with your primary Claude Code agent. It is Claude Code that prompts your sub-agents; it is delegating.

The Importance of Delegation and "The Big Three"

You really want to be thinking about your Claude Code sub-agents as tools of delegation for your primary agent. This is why "The Big Three" are so important:

• Context
• Model
• Prompt

Specifically, the flow of the context, model, and prompt between different agents is critical as we scale up our agentic coding to multi-agent systems.

Chaining Sub-Agents for Complex Workflows

We're just getting started here. You can chain the calls and responses. It's funny that we started out prompt chaining years ago, and now we're still prompt chaining, just with bigger compositional units.

The true flow is: 1. You, the user, prompt the primary agent. 2. The primary agent runs tasks, potentially calling sub-agents. 3. The results come back to the primary agent. 4. The primary agent can "keep cooking," firing off another set of sub-agents to continue the work.

Your sub-agents are always responding to your primary agent. If you're doing powerful multi-agent orchestration, this is a foundational concept.

Building a Meta-Agent: A Practical Example

Let's actually use this. I've built over 50, probably more than 100+ agents already, thanks to a meta-agent. As soon as you get access to a new feature, figure out how you can scale it up. Oftentimes, with generative AI, you build a meta version of that—the thing that builds the thing.

Let's create new agents with our meta-agent. A big issue in the GenAI ecosystem is seeing engineers using technology to create solutions for problems that don't exist. If you want to be a valuable engineer, work the other way:

1. Problem First: Start with a real problem.
2. Solution Second: Define a clear solution.
3. Technology Third: Choose the tech to implement the solution.

Let's walk through a concrete example.

• Problem: When I'm agentic coding at scale, I lose track of what some agents have done.
• Solution: Add text-to-speech to my agents so they notify me when they're done and, more importantly, what they've done.
• Technology: We can use Claude Code sub-agents. I have a meta-agent that can build a new text-to-speech agent.

Order matters: problem, solution, technology.

First, I want to understand what my agent can do. I'll run a reusable prompt to list all available tools in a TypeScript function signature format.

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

From the list, I need two things: a tool for text-to-speech and a tool to play the audio. I find textToSpeech and playAudio.

textToSpeech(text: string, voiceId: string, outputDir: string): Promise<string>
playAudio(filePath: string): Promise<void>

Now, let's validate the workflow in our primary agent's context window.

11 labs I've completed. Next, we can...
Voice ID: [your_voice_id]
Output directory: ./output

I'll have Claude Code Opus fire off this tool. It saves the file. Now we run playAudio.

"I've completed XYZ. Next weekend ABC."

Great. We have text-to-speech working. We now have the full capability to have our agents communicate with us via a sub-agent.

Unleashing the Meta-Prompt

Now we can crank open our powerful meta-prompt. Knowing the workflow, we can build a new agent that encapsulates this work. Our meta-agent has a system prompt that details how to create a new agent.

Here's the prompt I'll use:

Build a new sub-agent.
Generate a new complete Claude Drive sub-agent configuration file from a user's description.
PROACTIVELY use this to create new agents when a user asks you to create a new sub-agent.
Our agents will have the following flow: get the current working directory, run text-to-speech, then play the audio.

I'm asking Claude Code to build the agent. The description of our meta-agent will get activated. This is very important: your description must properly set up when your agent should call a specific sub-agent.

A key piece of this prompt is that I'm not just having it build on zero information. I'm re-pooling the Claude Code documentation live to get the most recent updates.

A brand new agent is generated. The reasoning model double-checks the work, reads the file, and confirms it exists. Let's look at our new agent. It's in the exact format we asked for.

I'll make a couple of tweaks, specifically to the description, because this determines when your primary agent calls your sub-agent. I like to have concrete triggers.

If they say TTS, TTS summary, use this agent.

I'll also add more detail to guide the primary agent on how to prompt this new sub-agent:

When you prompt this agent, describe exactly what you want them to communicate to the user.
Remember: This agent has no context of any questions or conversations between you and the user.
SO IMPORTANT:
- Provide a concise summary of what was done.
- Run only bash `pwd` and the 11 labs mcbp tools. Don't use any other tools.

Now, we have an operational agent that can quickly summarize work in natural language for us, anywhere, anytime. This is the beauty of agents and reusable prompts.

The Benefits of Sub-Agents

The benefits are pretty straightforward:

• Context Preservation: Each sub-agent operates in its own context, preventing pollution of the main conversation. We are booting up fresh, isolated agent instances for every task.
• Specialized Expertise: We can fine-tune the instructions and tools for each agent, creating highly specialized experts. You can instruct how you want the prompt to flow into the sub-agent via the description.
• Reusability: By storing agents in your repository, you can build a library of tools for your codebase.
• Flexible Permissions: You can lock down the tools each agent can call, enhancing security.
• Focused Agents: A hidden benefit is focus. Because the 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.
• Simple Multi-Agent Orchestration: Combining custom slash commands, hooks, and sub-agents allows you to build powerful yet simple multi-agent systems.

For example, we can create a /prime-tts command:

When you finish, run the TTS summary agent and let the user know you're ready to build.

This chains the work and provides an audio summary upon completion.

The Issues and Downsides

However, there are challenges to consider:

• Context Isolation (The Flip Side): The opposite of context preservation is that the sub-agent has no context history. It only knows what the primary agent prompts it with. It's like calling a one-shot prompt every time.
• Hard to Debug: We don't see the full internal workflows, prompts, and tool call parameters for sub-agents, which makes them harder to debug.
• Decision Overload: As you scale up the number of agents, it becomes harder for the primary agent to know which one to call. You must be very clear in your descriptions to avoid confusion.
• Dependency Coupling: You will inevitably have agents that depend on the output format of other agents. A change in one agent can break the entire chain. Try to keep workflows isolated.
• No Nested Sub-Agents: You cannot call sub-agents from within other sub-agents, at least not yet. This limits the depth of recursive workflows.

This is a very powerful feature. We have numerous more ideas to explore with the combination of agents and custom slash commands. Remember that perspective matters as you start scaling up your multi-agent system. The flow of the big three—context, model, and prompt—matters more than ever.