agents-team-builder
Skill3 starsChanged 5 months agoMITView on GitHub
Use to design and launch a Claude Code agent team (2–5 specialized agents that share a task list, talk peer-to-peer, work in parallel). Triggers — "build an agent team", "design a team of agents", "set up a Claude agent team", "I need a multi-agent crew", "create an agent team for X", "spin up a team of teammates", "build me a Claude team", or `/agents-team-builder`. Sibling of `/skill-builder`, `/agent-builder`, `/routines-builder`, `/workflow-builder`, `/plugin-builder` — this one is the agent-teams specialist.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- GerardoRdz96/claude-skillsedited, first seen Jul 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- GerardoRdz96/claude-skills★ 071% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-builderSkill
- aios-auditSkill
- grill-meSkill
- hooks-builderSkill
- level-upSkill
- multi-brainSkill
- onboardSkill
- plugin-builderSkill
- printing-pressSkill
- routines-builderSkill
- session-handoffSkill
- skill-builderSkill
- workflow-builderSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Don't ask "what team do you want to build?" yet.
- Distinctive: line 28
If the chosen option is not agent team, stop here and explain *why* in one line.
- Very specific: line 32
Read .claude/settings.local.json if it exists — it's gitignored, so a fresh clone won't have it.
- Very specific: line 39
Verify the Claude Code version supports agent teams (!claude --version).
- Distinctive: line 43
Ask via AskUserQuestion. Do NOT batch all rounds — one round per AskUserQuestion call so the user focuses.
- Distinctive: line 55
Ask the user to define each role.
- Distinctive: line 80
Run these checks on the answers.
- Distinctive: line 96
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 …
- Very specific: line 181
If the project keeps a references/log.md, append one line:
- Distinctive: line 192
3 is the sweet spot: When in doubt, recommend 3.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/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=1env 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
/goalcommand — just ask Claude to iterate to the done-check, with a numeric cap (seereferences/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=1env 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 existingenvblock. 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:
- Goal (free-form via "Other") — "What's the end deliverable in one sentence?" Provide 0 canned options; require the user to type it.
- Team size — options: 2 / 3 / 4 / 5. Recommended: 3 ("the sweet spot — enough specialization, not too expensive").
- 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:
- Role name — free-form (e.g., "Frontend dev", "QA agent", "Researcher", "Critic").
- Job + outputs — free-form: "What does this teammate do, and what concrete file(s) do they produce?"
- Owns these files — free-form: list of file paths/globs this teammate is the sole writer for.
- Talks to — free-form: which other role(s) by name does this teammate message?
Track answers in a scratch table:
| # | Role | Job | Outputs | Files owned | Talks to |
Round C — Final deliverables + stop condition + approval mode
One AskUserQuestion with three questions:
- Final deliverables — free-form bullet list. What does the human see at the end? (a running app? a PR? a test report? a doc?)
- 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. - 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.
| Gate | Check | If red |
| Team size | 2 ≤ N ≤ 5 | Block. Tell the user why (cost scales linearly; 10+ is 10× more expensive). |
| File ownership | Every teammate has at least one file/glob nobody else writes | Block. Show the overlap. |
| Recipients named | Every teammate that produces a handoff names the recipient | Block. Show the unnamed handoffs. |
| Deliverables concrete | At least one deliverable is a file path or runnable artifact — not "summary" / "ideas" | Block. Ask for a concrete artifact. |
| Goal testable | Goal names an objective, testable end-state — not "improve X" / "make it better" | Block. Make them state a checkable end-state (references/agent-loops.md, Brake 1). |
| Stop condition present | Round C gives BOTH an objective done-check AND a numeric hard cap | Block. A loop missing either brake is a runaway, not a system (references/agent-loops.md, the two brakes). |
| Verification role | At least one teammate verifies the others' output — a functional check where possible — and is a fresh, separate teammate, never grading its own work | Block. No verifier ships confidently-wrong work (references/agent-loops.md, Maker→Checker / No-Self-Review). |
| Goal one-line | Goal is ≤ 200 chars and starts with a verb | Yellow. Trim if longer. |
| Approval mode picked | Phase 3 Round C answered | Block. |
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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

