# Agents Team Builder > 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`,… - **Type:** Skill - **Install:** `agentstack add skill-gerardordz96-aios-starter-kit-agents-team-builder` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [GerardoRdz96](https://agentstack.voostack.com/s/gerardordz96) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [GerardoRdz96](https://github.com/GerardoRdz96) - **Source:** https://github.com/GerardoRdz96/aios-starter-kit/tree/main/.claude/skills/agents-team-builder ## Install ```sh agentstack add skill-gerardordz96-aios-starter-kit-agents-team-builder ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # /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: | # | Role | Job | Outputs | Files owned | Talks to | |---|------|-----|---------|-------------|----------| ### 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. | 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/.md`. Use this exact structure: ```markdown # Agent Team: **Goal:** **Created:** **Status:** ready / re-firable **Stop condition:** · cap: **First-run approval mode:** ## Invocation prompt (paste into a fresh Claude session) GOAL: Create a team called of teammates using : 1. — . Owns: . Talks to: . 2. — . Owns: . Talks to: . 3. — . Owns: . Talks to: . [...continue for N teammates] Final deliverables: - - - Done when (both required — stop and report the moment it's met): - Done-check: - Hard cap: Verification: 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: ## 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/.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: ```markdown - [](.md) — · created ``` **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: Saved template: `.claude/teams/.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/.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. teammates ≈ × 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: ```markdown ## [] create | Agent team — Built via `/agents-team-builder`. Goal: . teammates on . Saved at `.claude/teams/.md`. First-run approval 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. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [GerardoRdz96](https://github.com/GerardoRdz96) - **Source:** [GerardoRdz96/aios-starter-kit](https://github.com/GerardoRdz96/aios-starter-kit) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-gerardordz96-aios-starter-kit-agents-team-builder - Seller: https://agentstack.voostack.com/s/gerardordz96 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.