Agents Team Builder

/agents-team-builder

Builds Claude Code agent teams: 2–5 specialized agents that share a task list, talk to each other peer-to-peer, and work in parallel. Sibling of /skill-builder, /agent-builder, /routines-builder, /workflow-builder, /plugin-builder.

Agent teams are an experimental Claude Code feature. They require the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var and a recent Claude Code version. The do/don't gates below keep teams cheap and well-scoped.

Phase 0 — Readiness check (silent)

Confirm the user actually wants a team of interacting agents (peer-to-peer messaging, shared task list), not independent parallel sub-agents. If they only need parallel work with no peer comms, that's plain sub-agents — note it and continue to the decision gate, which will catch it.

Phase 1 — Decision gate (mandatory)

Don't ask "what team do you want to build?" yet. First confirm this should even be a team. Ask the user one AskUserQuestion summarizing the task they want done, with these options:

• Agent team — multiple specialized areas, parallel + reactive, quality matters (multi-pass review). Proceed.
• Sub-agents (no team) — independent parallel work, no peer comms needed. Tell the user to just ask Claude to spin sub-agents; don't team.
• Dynamic workflow — wide fan-out (10s–100s agents), no peer comms. Point them at a width-fan-out workflow instead.
• A depth loop — depth not width; iterate to an objective done-check. This kit ships no /goal command — just ask Claude to iterate to the done-check, with a numeric cap (see references/agent-loops.md).
• Just-ask — simple one-shot. Don't fire anything; suggest they just ask Claude.

If the chosen option is not agent team, stop here and explain why in one line. Do not proceed.

Phase 2 — Enablement check

Read .claude/settings.local.json if it exists — it's gitignored, so a fresh clone won't have it; treat a missing file as "not set" and don't error. If present, check env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS == "1".

• If set: confirm to the user "Agent teams enabled at project level — good." and move on.
• If missing or the file doesn't exist: tell the user "Agent teams require the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var. May I add it to .claude/settings.local.json?" On yes, create the file if it's absent with { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }, or add the key to an existing env block. On no, stop and tell them the feature won't fire without it.

Also remind the user: the env var only applies to NEW Claude Code sessions. If you just added it, they need to launch a fresh claude session before the team can run. The skill can still build the prompt + save the template right now — they're persistent artifacts.

Verify the Claude Code version supports agent teams (!claude --version). If the feature isn't available in their version, stop and tell them to update.

Phase 3 — Discovery Interview

Ask via AskUserQuestion. Do NOT batch all rounds — one round per AskUserQuestion call so the user focuses. If the user supplied a one-line goal as an argument or in their trigger message, skip Round A's goal question and just confirm.

Round A — Goal + team size + model

One AskUserQuestion with three questions:

1. Goal (free-form via "Other") — "What's the end deliverable in one sentence?" Provide 0 canned options; require the user to type it.
2. Team size — options: 2 / 3 / 4 / 5. Recommended: 3 ("the sweet spot — enough specialization, not too expensive").
3. Model — options: Haiku / Sonnet (Recommended) / Opus. Sonnet is the right default cost/quality trade for most teams.

Round B — Roles (the heart of the build)

Ask the user to define each role. ONE AskUserQuestion per teammate (so up to 5 rounds). For each:

1. Role name — free-form (e.g., "Frontend dev", "QA agent", "Researcher", "Critic").
2. Job + outputs — free-form: "What does this teammate do, and what concrete file(s) do they produce?"
3. Owns these files — free-form: list of file paths/globs this teammate is the sole writer for.
4. Talks to — free-form: which other role(s) by name does this teammate message?

Track answers in a scratch table:

Round C — Final deliverables + stop condition + approval mode

One AskUserQuestion with three questions:

1. Final deliverables — free-form bullet list. What does the human see at the end? (a running app? a PR? a test report? a doc?)
2. Stop condition — free-form, both parts required: (a) an objective done-check the team can test (a deliverable file exists / a test passes — never "until it's good") and (b) a numeric hard cap (max message rounds, wall-clock, or token budget). Both brakes are mandatory — a team with no cap is a runaway token bill. Doctrine: references/agent-loops.md.
3. First-run approval mode — options:
   • Human approves every teammate's plan (Recommended) — safest first run; relax later.
   • Main session approves teammate plans — lower friction; the orchestrator is the gatekeeper.
   • One teammate is the plan reviewer — specialist pattern; pick which role in the next message.

Phase 4 — Validation gates (block on red)

Run these checks on the answers. Red = block and ask the user to fix. Yellow = warn but proceed.

Phase 5 — Generate the artifact

Step 1 — Name the team. Ask the user for a kebab-case team name (default: derive from the goal, e.g., "landing-page-build" or "research-trio"). This is the file slug.

Step 2 — Write the saved template to .claude/teams/<team-name>.md. Use this exact structure:

# Agent Team: <Team Name>

**Goal:** <one-line goal>
**Created:** <YYYY-MM-DD>
**Status:** ready / re-firable
**Stop condition:** <objective done-check> · cap: <numeric hard cap>
**First-run approval mode:** <Human-approves | Main-approves | Reviewer-teammate>

## Invocation prompt (paste into a fresh Claude session)

GOAL: <goal>

Create a team called <team-name> of <N> teammates using <model>:

  1. <Role 1> — <job + outputs>. Owns: <files>. Talks to: <recipients>.
  2. <Role 2> — <job + outputs>. Owns: <files>. Talks to: <recipients>.
  3. <Role 3> — <job + outputs>. Owns: <files>. Talks to: <recipients>.
  [...continue for N teammates]

Final deliverables:
  - <deliverable 1>
  - <deliverable 2>
  - <deliverable 3>

Done when (both required — stop and report the moment it's met):
  - Done-check: <objective done-check — deliverable files exist / a test passes>
  - Hard cap: <numeric cap — max message rounds / wall-clock / token budget>

Verification: <verifier role> checks the others' output (a functional check where possible) as a fresh, separate teammate — never grade your own work.

Git + send rail: teammates push only to a feature branch — never to main, never deploy, never send externally (including through an inherited MCP) without a human gate.

Approval mode: <approval-mode-instruction>

## Notes
- Each teammate inherits the orchestrator's permissions, MCPs, skills, and project files. No conversation history is passed — context is the prompt above.
- **Two brakes are mandatory:** the objective done-check stops a finished team; the numeric cap stops a stuck one. A team with neither is a runaway token bill (`references/agent-loops.md`).
- **Branch-only rail:** teammates push to a feature branch and never to main/deploy/external-send through an inherited MCP without a human gate.
- For real per-agent visibility, run in tmux (not VS Code).
- **Log each run:** append one line to `.claude/teams/<team-name>.log.md` — `YYYY-MM-DD · what shipped · why it stopped (done-check met / hit cap)`.
- To re-fire this team later: open a fresh Claude session in this repo, then paste the "Invocation prompt" block above.

Step 3 — Append the team to .claude/teams/README.md (the directory's index — create if missing). One-line entry per team:

- [<team-name>](<team-name>.md) — <one-line goal> · created <YYYY-MM-DD>

Step 4 — If Phase 2 had to set the env var, remind the user one more time: "Restart your Claude Code session before firing this team — the env var only applies to new sessions."

Phase 6 — Output to chat (the paste-ready brief)

In the chat, output exactly this block (substitute real values):

## Agent team ready: <team-name>

Saved template: `.claude/teams/<team-name>.md`
Re-fire later by pasting that file's invocation prompt into a fresh session.

### To run now

1. (If env var was just added) Restart Claude Code in this directory.
2. Open a fresh `claude` session — ideally inside tmux for per-agent visibility:
   ~~~
   tmux new -s team
   claude
   ~~~
3. Paste the invocation prompt from `.claude/teams/<team-name>.md`.
4. First run: keep the human-approval mode on; switch to main-approves once the pattern is working.

### Cost reality

Each teammate is a full Claude session. <N> teammates ≈ <N>× the cost of one. Watch the
session limit on first runs; stop early if a teammate goes off-track (the tmux split-pane view
makes this catch easy).

Phase 7 — Log

If the project keeps a references/log.md, append one line:

## [<YYYY-MM-DD>] create | Agent team — <team-name>
Built via `/agents-team-builder`. Goal: <goal>. <N> teammates on <model>. Saved at `.claude/teams/<team-name>.md`. First-run approval mode: <mode>.

Notes / discipline

• Don't pre-fill role definitions. The skill must walk the user through each role even if they want to rush. Pre-filled roles are how teams get bad file-ownership and overlap.
• Don't fire the team for them. This skill builds the prompt and saves the template. The user fires the team manually in a fresh session. The separation matters: build = cheap (just text); fire = expensive (N parallel Claude sessions).
• Don't bypass the decision gate. "Just-ask" is a valid outcome; many tasks users describe with team language are actually sub-agent or just-ask jobs.
• 3 is the sweet spot. When in doubt, recommend 3.
• Skill stays under 500 lines.
• Cost discipline: Tell the user before Phase 5 that this team will be ~N× a single-Claude session. They should know before they save the template.
• Example use: a team you might build — a 3-role "research-trio" (a searcher who gathers sources, a synthesizer who drafts, a critic who fact-checks). The kit doesn't ship pre-built teams; you design your own here.

Related

• .claude/skills/skill-builder/SKILL.md, agent-builder/SKILL.md, routines-builder/SKILL.md, workflow-builder/SKILL.md, plugin-builder/SKILL.md — sibling builders.
• references/agent-loops.md — loop-engineering doctrine (the two brakes, the four verification types, when not to loop). A team that iterates is a loop; give it both brakes and a fresh-lineage checker.