This is the version you keep on hand. Open it when you're about to run an agent team in Claude Code, and tick off the steps in order, from turning the feature on to closing it down cleanly. Every item is one action you can check.
An agent team is several agents working in parallel, sharing one task list, able to talk to each other. Reach for it on a complex job with several distinct areas; a simpler job just needs a single agent or a sub-agent.
0. Before you start — prerequisites
- Check whether the task actually fits a team — see "When not to use a team" below. If it doesn't, stop here and use a single agent or a sub-agent instead.
- Accept that the feature is experimental and off by default — you have to turn it on before the first run.
- Open the official Claude Code agent teams documentation — you'll need it in the next two steps.
1. Turn on the feature and teach the project how teams work
- Turn on the feature with one setting (a variable) in the project's
settings.jsonconfig file. Copy the ready snippet from the official Claude Code documentation, or ask Claude Code to insert it into the project's local settings. - Take the documentation URL and ask Claude Code to turn it into a local guide, a Markdown file in the
docsfolder. - Confirm the file exists. From now on Claude Code reaches for it instead of reading the online documentation every time.
2. Write the prompt
You call a team in plain language, no special syntax. Stick to four steps:
- Start with the goal. State up front what the whole team is working toward, since agents wake up with no context and know only what the main session hands them. That way every agent understands not just its own task but why the others are there.
- Set the roster. Say it plainly, for example "create a team of three agents on model X." Pick from Haiku, Sonnet and Opus, from fastest and cheapest to strongest.
- Describe each role. For every agent, state what it should do, what it should produce, and who to hand the result to once it's done (for example, "when you're done, send the output to the front-end agent").
- Name the end result. Say plainly what you want at the finish: a working app, a test report, or a short document describing what got built and how to run it next.
Rules that keep the team in line
- Give each agent its own files. If several agents edit the same file, they can overwrite each other's work.
- Spell out the deliverable precisely. A vague brief gets you a vague result.
- Name the recipient by role. Don't assume an agent will work out on its own who to write to and why.
- Stay at three to five agents. A bigger swarm turns into chaos and a bigger bill.
- Hand over the full context up front. Agents can read every file in the project, but at the start they get nothing beyond what you tell them.
3. Set what the agents have at the moment they start
- Pre-approve the commands you want in the project settings — agents inherit the main session's permissions, so whatever you pre-approve, they get too.
- Confirm the agents can reach the project files plus the connected tools and skills — everything the main session has access to.
- Decide who approves plans under plan-approval mode. Before an agent acts on anything, it has to present a plan and get it accepted. It's usually more convenient to let the main agent approve plans, though you can also name one team member as the plan reviewer.
4. Run the work and react to problems
Once the team is running, watch the task list and adjust the prompt when something breaks down.
| Symptom | What to do |
|---|---|
| Agents keep asking for permission and stalling | Pre-approve the commands you want in the project settings. |
| The output doesn't add up to a whole | Assign file owners — agents are likely overwriting each other's files. |
| One agent sits idle | Make sure the prompt gives every agent its own work or a clear dependency on the others. |
| Token spend climbs too fast | Use fewer agents — three parallel sessions cost roughly three times as much. |
| Agents lose their work | Ask them to save everything to scratch files they can come back to. |
5. Close the team down properly
- Once the work is done, make sure the main agent sends the team members a request to close out, the equivalent of "wrap up and save your work."
- Let an agent finish if it comes back with "not done yet, don't shut me down." The point is a clean save at the end, not a job cut off halfway.
- Confirm the session left behind a tidy result, not a mess to clean up.
What to watch for — when not to use a team
Agent teams are slower and more expensive than a single agent. Skip them when:
- the process is sequential — the steps run in order (1, 2, 3) and each depends on the one before — that's a job for sub-agents instead,
- everything fits inside one context window — meaning a single conversation and its history,
- the agents would end up working on the same files anyway,
- the task is simply simple — a team there is overkill.
A stronger feature isn't automatically the better choice for what you're doing right now. Reach for a team when the task spans several distinct areas, the parts can be built in parallel, the agents need to react to each other and hand off work between them, and several review steps are watching quality.