---
title: 'How to Build Claude Agent Teams Better Than 99% of People'
source: 'https://youtube.com/watch?v=vDVSGVpB2vc'
video_id: 'vDVSGVpB2vc'
date: 2026-07-31
duration_sec: 989
---

# How to Build Claude Agent Teams Better Than 99% of People

> Source: [How to Build Claude Agent Teams Better Than 99% of People](https://youtube.com/watch?v=vDVSGVpB2vc)

## Summary

This video demonstrates how to build and manage Claude Code agent teams — teams of AI agents (e.g., front-end, back-end, QA) that share a task list, communicate with each other, and work in parallel under a main orchestrator. The creator walks through enabling the experimental feature, creating a local reference guide, writing effective team-creation prompts, and shares best practices, pitfalls, and when to use agent teams vs. subagents.

### Key Points

- **Live demo: spawning a three-agent team** [00:01] — Using the 'team create' tool, Claude Code spawns a front-end developer, back-end developer, and QA agent in parallel. They share a task list and talk to each other; the QA agent sent work back to the devs for fixes, producing a polished landing page.
- **Agent teams vs. subagents** [01:33] — Agent teams have a team lead (or project manager) and a shared task list, and individual teammates can communicate directly. Subagents work independently and only report back to the main session.
- **Enabling the experimental feature** [02:38] — Agent teams are disabled by default. You need to add the enable variable to your project's settings.local.json inside the .cloud folder (or in your user settings).
- **Create a local documentation guide** [03:28] — Copy the official agent teams documentation URL and ask Claude Code to create a master reference guide markdown file in your project so it can answer questions faster and more accurately.
- **Agent teams are slower but higher quality** [04:32] — The honest trade-off: agent teams cost more time and tokens but produce much higher-quality results if you prompt them correctly.
- **The natural-language team creation pattern** [04:46] — Follow this pattern: 'Create a team of X agents using model Y. The first agent is role X, should do this, and produce this. It can talk to other agents to do X.' List each agent similarly.
- **Establish a goal first** [05:13] — Agents wake up with zero context — they only receive the main session prompt. Stating the goal (e.g., 'stack app with REST API and React front end') helps agents understand what they're working toward and why teammates exist.
- **Dos and don'ts for agent teams** [06:33] — Do assign each agent specific files, define output recipients, keep teams at 3–5 agents, and give full context. Don't force massive 10+ agent swarms or assume agents know who to message.
- **Live prompt: research team** [07:12] — A team of researcher, strategist, and critic reviews documentation, finds 11 gaps, and produces a detailed 'Agent Teams Patterns' document. The main agent can direct-message teammates and even correct them.
- **Watch agents in tmux** [09:46] — Running Claude Code in a tmux terminal lets you see each agent (colored differently) working and thinking, and lets you directly message any teammate.
- **Three key rules** [11:31] — Give each agent its own territory/files; encourage direct messaging between agents; allow parallel work with continuous communication rather than just sequential handoffs.
- **When to use agent teams** [14:05] — Use them for complex, multi-specialist parallel work requiring high quality. Avoid them for sequential, single-context, or simple tasks where they're overkill and expensive.

### Conclusion

Agent teams are a powerful but resource-hungry feature: use them for complex, parallel, multi-expert work, give agents clear goals, file ownership, and permissions, and monitor them in tmux for full control. Master the prompt pattern and you'll consistently build better AI teams.

## Transcript

create a team called Neuroflow of three teammates using Sonnet. The first one is a front-end developer, the second one is a back-end developer, and the third one is a QA agent. So, this now invoked a tool called team create. And you can see
created this team, it's spawning up three teammates in parallel. And these we can see we have our front-end developer, we have our back-end developer, and we have our QA agent. So, what's happening is right now we have
our main session. They all share a task list, they can talk to each other, and once this is done. Okay, so this is really interesting. The front-end and back-end developer sent work over to the QA agent, and then the QA agent found
agent said that it's going to send all of this work right back to those first So, here's where you can see it sent off those messages to the front-end And now they're all back to work once again. And there we go, the second time
of those critical issues have been resolved. And then it was able to obviously there are some things that aren't perfect about this and we'd want to go back and iterate, but considering in the prompt all I said was to build me
a landing page for a fictional AI startup and we get all of this text, we stuff to come in dynamically, and it feels pretty polished. It came up with all the copy, the color scheme, all of it. This is truly one of the most
used, but you have to know how to use it right, which is why in today's video I'm know, what they are, how to set them up, how to use them, when not to use them, waste any time and get straight into the video. So, agent teams. As you guys saw
called Neuroflow, and in that team we had three agents. We had the front-end what happens is the main orchestrator, the Claude code session you're talking to, creates these different agents and manages them. But not in the same way
agents work independently and then they send their individual result back to the main agent. Agent teams have a team lead, maybe like a project manager, and it creates all of these different agents and a shared task list. So, the huge
unlock here is that individual teammates can talk to each other. So, sometimes something from teammate two, and they can just talk. And you can get in these have the QA agent like we just saw in the demo, where one of the teammates
good enough." and send the work back. And then the main agent, like I said, is getting done and that they're all high quality. So, that's the big difference I had to clear that up because I know that's probably where there's some
stuff down, but what I want to do first is just show you guys how to set this up just to be able to play around with stuff. And all you have to do to set into your project setting. So, let me show you how that works right now. All
right, here I am in Cloud Code. I like to use it in VS Code, but you can use the agent teams feature wherever you decide to use Cloud Code. You can see nothing in it. So, this is exactly what one of you guys' setup should look like
said, we need to enable the feature, and I'm going to do that in this demo on the is go to the official Cloud Code documentation for agent teams, and you disabled by default because it's an experimental feature. So, you have to
enable them by adding this variable into your settings.json. So, what I'm going right here and come into Cloud Code and say, "Hey, I need you to put this in our local settings in this project." and
I'm going to go ahead and shoot that to create that file for us. So, you can see that it set everything up. We now have a .cloud folder. If I click in here, we have a settings.local.json,
and it has put that command in there. And now our project should be set up to Now, before we dive in and I start showing you guys how to do that, there first. And that's basically training your Cloud Code project on how agent
teams work so that they can actually be used as effectively as possible. So, the documentation on agent teams, you take the URL, and you copy it. And then I said, "Hey, create me a master reference guide for agent teams in a folder called
build better and more effective agents in the future." And now it's going to if you ever have questions about agent teams or if it ever needs to look up already has that locally here stored as markdown. So it's going to be much
documentation about enabling them, when to use them, display modes, task management, hooks, best practices, tons of stuff like that. And that can be found in the docs folder in this section, which is a full markdown file
hundreds of lines. And that's just a little tip. That's something that I like to do whenever I have like maybe a big MCP server or certain documentation that constantly. So now that we're pretty much set up and ready to start building,
actually tell Claude code to build us agent teams, but not just to build them, give you what you want. Because the truth about agent teams is that they are slower, but you do get much higher quality if you use them right. Now the
them just using natural language. So I kind of follow this pattern. Create a team of X number of agents using X And then you basically just say the agents that you want. You would say
the first agent is X role. This agent should be doing this and it should produce me this. It can talk to the other agents to do X, And so pretty much just listing that out in natural language. Whether that be an
in natural language. Whether that be an API designer, a database engineer and or quick look at an example prompt. So I'm going to read this full one out. Now what you'll notice is I start off by establishing a goal. The reason I do
this is because when the agents wake up, they have no context. They basically only get the prompt that the main session feeds into them. So if we tell agents, they understand a little bit better, you know, like what they're
working towards, but also why they have their teammates next to them. So the stack app with a rest API and a react front end. The end result should be a host. It should have users and post functionality plus a QA test report
then I said, "Hey, create me a team of three teammates using Sonnet. The first one's a back-end dev, it should be doing this. The second one is a front-end dev, and it should be doing this. And the third one is a QA agent that should be
descriptions I said, "When you're done, message the front-end dev." And then in dev's message, and then you will send all this stuff to the QA." And then I'm should be because the main agent spins these three up, and then it's going to
do I actually want at the end of the day? I want a running app, I want a report about pass and fail tests, and then I want a doc, which is basically what was built, key decisions, and how we run this moving forward. So we're
about to hop right back into Claude Code and live prompt an agent. But real quick, let's talk about some dos and don'ts. So do have each agent own specific files because if you don't do this and agents are sharing files, they
might overwrite each other's work, which is not good. Do define the output, don't recipients, don't just assume that they're going to understand who to talk to and why. Do have about three to five teammates, don't go for massive agent
swarms of 10+. That'll also be 10 times more expensive. And do give full context given beforehand. Now of course, they project, they can still look through all of those files, but no context is fed in
what I mean by that when we go in here and spin up a new agent team. Okay, so together. I'm in a fresh session, and I'm going to send off this prompt. I up the workspace. We have three agents called research team. We're using
strategist, and a critic, and they're basically just going to read through everything's accurate and make sure that we're set up good. Let's take a look at what's going on. It's creating the research team, right? So it's created
Now what it's doing is it's going to spawn the three teammates in parallel. actually show you how. So the first one is a researcher. If I click into this, is basically saying this is what the main agent sent to the agent. You are
here is what your job is, and you have to be thorough and include anything that might be helpful. So this is basically the prompt that spun up that agent. You can see same exact thing happened for the strategist and for the critic. And
read exactly what they were prompted to do and the step-by-step instructions. send your five use cases to the critic teammate using the send message tool. agents are able to talk to each other and send messages to each other. So now
are running and they are all basically just waiting for their turn. And you'll time there's a new update, it updates me. So here comes another live update. done. There we go, it's done. So now what happens is we sent a message off to
see what that message actually said. So this is the main agent talking to the researcher. It said, "Did you send your structured inventory to both the sure the strategist also received it. You were asked to message both
teammates." And then we can see that the researcher confirmed that both teammates critic is running. All right, so everything just finished up. All the wanted to draw your attention to this. The main agent said, "Cool, let me shut
down the teammates and finalize." I'll touch on this a little bit later, message to each of them, the researcher, the strategist and the critic, and Save your work." So anyways, we'll come back to that in a little bit, but we now
have an output, which is a new document over here, Agent Teams Patterns, and it found a ton of stuff. There were 11 documentation gaps identified that are doc. So anyways, let's just click into the doc real quick. We're not going to
it is super long, but this is the actual output that we just got from this agent insanely thorough. So, if you wanted to really, really understand how agent teams work, then spin up an agent team to help you explain agent teams. Now,
of able to see what was going on, but not really under the hood. We couldn't thinking or doing, and that's because extension. If you do this in your terminal, and specifically if you have
tmux installed, you can actually see the different agents working and thinking, to them. Because right here we're kind of only communicating through the main messages to the other ones. But one of the value props of agent teams is that I
could individually message a sub-agent if I wanted to. So, let me show you what All right, so right now I'm running Cloud Code in a tmux terminal. Now, if little bit of a work around, but you just have to be in a tmux terminal. So,
on it right now, but I literally just had Cloud Code walk me through it, and did here is I just pasted in this prompt, which obviously is like we talked about, we have the goal, we say create me an agent team, and then we
dev, and our QA. This is basically the same exact prompt that I ran in the actual deliverable. What I want to show you guys here is the way that we can it's going to do is it's going to spin up that agent team for us, right? It's
it's assigning owners, and now it's spawning those agents. And there we go, we just got our front-end dev created right here, and this is the blue agent. the back-end dev, and this is the green agent. And there we go, we just got our
QA agent, which is the yellow one. So, now I very clearly can see what each of these agents is doing, which is super cool. And now if I wanted to, I could team status with the main session. I could come up here, and I could talk to
things, or I could give it more info. Same exact thing with the QA, or same now I literally have an agent team that I can watch, and I can interact with any of them. And I can also watch them do research, create things, talk to each
I said, I'm not going to run this whole thing out. I just wanted to show you guys that this is possible. Okay, now that we've seen some cool demos, let's talk about how do we actually make these things better and better and understand
So, here are three key rules. The first their own territory. So, they should have their own file and they should be can send them across and they can communicate, but they should only really
second thing is, once again, direct messaging. They can talk to each other. the main session. And then the third piece is that they can be working at the one hands off to agent two and then agent two hands off to agent three,
because that honestly might not even call for an agent team. Agent teams work communicate throughout the whole process. So, what do teammates instantly that they don't have any context from the jump. What they do have is they
inherit the permissions from the main session. So, if you're on bypass going to be on bypass permissions. If you allow all bash commands, then those same permissions will once again be inherited by the teammates. But the
other thing to know that's very important is that any of your files, any of your MCP servers, any of your skills, all of the teammates can use and access ability to use something called plan approval mode. So, you guys know how
I've told you always start in plan mode. If you plan with your main session before anything actually happens, it's way better. What we can do is we can have all of those agent teammates plan first and they have to basically get
before they're actually allowed to go also set it up where you're actually the one who has to approve every single plan, but I think it's probably better to just have the main session do that.
Or maybe even one of the teammates is just the plan reviewer and approver. So, I wanted to talk about some common pitfalls or mistakes that you might be that. So, the first one is if the agents keep
stopping for that. You can pre-approve certain tools. So, that would be in your project settings or your local settings. You can allow certain commands, and that every couple seconds. If the deliverables aren't coming out feeling
overridden, so make sure that you assign file owners. If you spin up an agent agents isn't really doing much or is just sitting around, then maybe you want to specifically make sure you're assigning each agent work or some sort
prompt. If you're burning through way too many tokens, just use fewer agents. work, then tell them to basically store everything as a temporary file that they getting the wrong approval and it just seems like it's off, then maybe just try
things to start until you understand the flow of how these teams work a little talk about when to use agent teams because like I said earlier, they can be slow and expensive, so you really just want to use them when you need something
pretty complex done, and you need lots of different specialized agents. So, think about using them if your specific process or project has multiple areas, specialized in each of those. If you need those things to be done in
react to each other, assign tasks to each other, communicate with each other. really high quality and you want tons of different steps to make sure, then an Now, if you have a process that could be done sequentially, meaning every time it
those steps are dependent on each other, then maybe an agent team isn't the right you need everything in one specific conversation history or one context window, then don't use teams. If you're just kind of working on the same files,
simple task, then agent teams would be overkill. There might be a lot of times instead. Like I said, with sequential or if you need a very focused result. If communicate, and if you want to save some tokens. Because once again, if you
basically going to be three times the cost. So, if you have five, it'll be five times the cost. Which means I like to stay around maybe two to five agents max. You can keep them running parallel. Otherwise, you can use sub agents and
make sure that you are shutting them down if you see them early on going off reason why I think it's helpful to use the tmux version, so you can actually when I say shut down, which is kind of what we saw earlier, I just mean
basically at the end of every session saving your work. Because remember right here how we saw the main session say, "Hey, this is a shut down request." The "I'm not done yet. Let me save stuff.
ready to be shut down, that means that everything's good and we can essentially cleanly save that work. So everything gets cleaned up and then we're good to agent team rather than just force killing it right away where things might
be all out of control and not cleaned up yet. Well, all right. That is agent hop into Cloud Code and start building with some agent teams. And if you want to check out other Cloud Code stuff that I've been doing to expand your learning,
guys over there, but that is going to be the end of the video. So if you enjoyed give it a like. It definitely helps me out a ton. And as always, I appreciate video. I'll see you on the next one. Thanks, everyone.