Agent Team Builder

Why build a team of subagents at all

A single Claude Code session is a generalist. It plans, writes, tests, and reviews in one long context, and that context gets noisy. Subagents let you split that work into separate, focused contexts - each with its own system prompt and its own narrow set of tools. The main session becomes an orchestrator that hands a scoped task to the right specialist and gets back a clean result. The practical payoff is fewer mistakes on long tasks, because a reviewer that only reviews is not distracted by the pressure to also ship.

This builder does not invent agents. It maps the shape of your work - feature, bugfix, refactor, greenfield, or research - onto a small set of proven roles, and lets you turn each one on or off. Each role comes with a one-line brief, a sensible default model, and a minimal tool set. The output is a plan you can hand to the Subagent Generator to produce the actual .claude/agents files.

The core roles and what each one is for

• Planner - reads the codebase and turns the goal into an ordered, testable plan. Read-only tools so it cannot start editing before the plan is agreed. Opus for the reasoning depth.
• Researcher - gathers context from code, docs, and the web, and reports findings. Never edits. Ideal for bugs where the cause is unknown and for greenfield where you need to survey options.
• Implementer - the one that actually writes code. It gets Read, Edit, Write, and Bash, and it works one focused change at a time against the plan.
• Reviewer - reads the diff and lists required changes for correctness, security, and style. Read-only, so it cannot quietly fix things and hide problems. Opus, because catching subtle issues is a reasoning task.
• Tester - writes and runs tests, reports failures, and confirms the change is verified. Gets Bash so it can actually run the suite.
• Documenter - updates README, changelog, and inline docs. Cheap work, so Haiku is the right default.

How to scope each agent's tools

The single most useful discipline in multi-agent design is tool scoping. A subagent should only hold the tools it needs to do its job. A reviewer with Edit access is a reviewer that will start editing. A planner with Bash is a planner that will start running commands before the plan exists. When you leave the tools field off a subagent entirely, it inherits all tools - which is convenient but almost never what you want for a specialist. Name the tools explicitly and keep the list short.

Matching models to roles

1. Use Opus 4.x for the roles where reasoning is the bottleneck - the planner and the reviewer. These agents run rarely and their quality sets the ceiling for the whole team.
2. Use Sonnet 4.x for the workhorse roles - implementer, tester, researcher. Sonnet handles most coding and test work at a fraction of Opus cost.
3. Use Haiku 4.5 for mechanical, high-volume roles like the documenter. Fast and cheap is exactly right when the task is formatting, not judgment.
4. Do not default every agent to Opus. A five-agent team all on Opus is expensive and slow, and most of the work does not need it.

The recommended flow

For a typical feature, the flow reads left to right: Planner produces the plan, Implementer builds against it, Tester verifies, Reviewer signs off, Documenter records the change. For a bug, you usually start with Researcher to find the cause, then Implementer, Tester, and Reviewer. You do not have to run every role every time - the value is in having the specialist ready when the task needs it. The plan the widget generates lists your chosen flow so you can paste it into the CLI as the delegation order.

Turning the plan into real files

Each role in your plan becomes one markdown file in .claude/agents/ with YAML frontmatter (name, description, tools, model) and a system prompt body. Project-level agents live in .claude/agents/ and are shared with your team through the repo; user-level agents live in ~/.claude/agents/ and follow you across projects. Once the files exist, the main Claude Code session can delegate to any of them by name. The Subagent Generator on this site produces each file for you from the role brief.

When a team is overkill

Not every task wants a team. A one-line fix does not need a planner, a reviewer, and a tester - the overhead of coordinating agents can cost more than it saves. Reach for a multi-agent team when the task is large enough that context noise, missed edge cases, or skipped review are real risks: multi-file features, risky refactors, and greenfield builds. For small, well-understood changes, a single focused session is faster and cheaper.