Agent Teams
An Agent Team groups a lead agent with a set of member agents so they can tackle a task together. You delegate a task to the lead; it decomposes the work, fans it out to its members, and synthesizes their results into a single answer — the "swarm" pattern, configured once in your workspace.
SuperClawd Pipelines can hand a ticket from your board to Claude and let a team like this run autonomously — working in an isolated git worktree and opening a PR for your review. Learn more.
What an Agent Team Is
Where an agent is a single configured persona, a team is a composition of agents that work as a unit. A team is built from:
- A lead agent — the agent you delegate the whole task to. It must be a primary-mode agent (the mode designed to drive a session and orchestrate others). The lead decomposes the task and delegates pieces to its members.
- Member agents — the subagents the lead fans work out to. A team can have up to 4 members (5 agents total, including the lead). Each member runs with its own configuration and loads its own linked skills when it does its piece of the work.
- Linked workflows (optional) — up to 5 procedure workflows the lead may run as part of the job. These are resolved live and surfaced to the lead as available procedures.
At launch the lead is served to Claude Code as a subagent carrying a directive to delegate to its members, so the whole team behaves like one orchestrated unit. Teams live in your workspace alongside agents; you manage them from the Agent Teams page.
Each member is a full agent in its own right. When the lead delegates a piece of work to a member, that member loads its own linked skills and runs under its own tool permissions — so a team can blend several specialists into one task.
How a Team Runs a Task
You don't talk to the members directly. The flow is:
- You delegate a task to the team's lead.
- The lead decomposes the work into pieces.
- It fans those pieces out to its members, each of which does focused work (loading its own skills and respecting its own permissions).
- The lead synthesizes the members' results into a single response.
Linked workflows are presented to the lead as procedures it may run while working — they are read-only references the lead can follow, not steps that fire automatically.
Running a Team from a Command
A command can be linked to a team. When you run a command that is linked to a servable team, the command's body is prefixed with a directive to delegate the task to the team's lead — so the command becomes a one-shot way to put the whole team on a job. The link is read live (it is not frozen into command versions); if the team is later deleted, the command is simply unlinked and runs on its own.
Constraints
Teams are validated when you create or edit them. The rules that matter:
- The lead must be a primary agent. Only
primary-mode agents can lead a team — subagent-mode (or any other mode) agents cannot. - The lead cannot also be a member. A lead delegates to its members, so it can't delegate to itself.
- Up to 5 agents per team — the lead plus at most 4 members.
- Up to 5 linked workflows, each a procedure-mode workflow.
- Team names are unique per workspace. Names are 1–40 characters.
- The lead, every member, and every linked workflow must belong to the same workspace, be enabled, and have a stable release — an unreleased entity isn't served to Claude Code, so it can't take part in a team.
Serving, Experimental & Disabling
Unlike skills, agents, and workflows, teams are not versioned — there is no release snapshot. A team always serves live: whatever its current lead, members, and links resolve to is what runs. A team only reaches Claude Code when it is enabled, has a lead that is still present and is a primary agent, and has at least one enabled member to delegate to.
- Experimental flag — like other entities, a team carries a per-entity experimental flag. A team flagged experimental is served only in an experimental session; a non-experimental team is always served. (This is the same two-key gate used by agents and skills.)
- Disabling — disable a team to take it out of service without deleting it. A disabled team is never served. Deleting the lead agent leaves the team lead-less, which also takes it out of service until you assign a new lead.
A team is just a grouping of agents and workflows — and those underlying entities are versioned. Each member serves its own stable release (or its draft in an experimental session), so the team composes already-versioned parts rather than snapshotting them again.
Creating a Team
- Navigate to Agent Teams in your workspace
- Click New Team
- Enter a name (and an optional description)
- Pick the lead — a primary agent from your workspace
- Add members — up to 4 agents to delegate to (you can also start empty and add members later via Edit Members)
- Optionally link workflows — up to 5 procedure workflows the lead may run
- Save the team
You can edit the lead, members, and linked workflows at any time, flag the team experimental, or disable it — all from the team's actions on the Agent Teams page. To run a team from a slash command, link it to a command (see Running a Team from a Command).
Tier Limits
The number of teams you can create per workspace depends on your billing account tier:
| Tier | Teams per workspace |
|---|---|
| Free | 1 |
| Paid | 25 |
See Limits and Billing & Credits for how tiers and workspace item limits work.
Best Practices
- Give the lead a clear orchestration prompt — its job is to plan, delegate, and synthesize, not to do every piece itself
- Make each member a focused specialist with just the tools and skills it needs
- Keep teams small; 5 agents is the ceiling, but a tight 2–3 agent team is often easier to reason about
- Link only the workflows the lead should actually have on hand for the job
- Flag a team experimental while you tune its lead and members, then clear the flag once it's solid