| name | team-builder |
| description | Interactive agent picker for composing and dispatching parallel teams from agent persona files. |
Team Builder
Interactive menu for browsing and composing agent teams on demand. Works with flat or domain-subdirectory agent collections.
When to Use
- Multiple agent personas (markdown files) available and you want to pick which ones to use
- Composing an ad-hoc team from different domains (e.g., Security + SEO + Architecture)
- Browsing available agents before deciding
Prerequisites
Agent files are markdown files containing a persona prompt (identity, rules, workflow, deliverables). The first # Heading is used as the agent name and the first paragraph as the description.
Both flat and subdirectory layouts are supported:
Subdirectory layout — domain inferred from folder name:
agents/
├── engineering/
│ ├── security-engineer.md
│ └── software-architect.md
├── marketing/
│ └── seo-specialist.md
└── sales/
└── discovery-coach.md
Flat layout — domain inferred from shared filename prefixes (2+ files sharing a prefix = domain; unique prefixes → "General"). The algorithm splits at the first -, so multi-word domains should use the subdirectory layout.
Configuration
Agent directories are probed in order and results merged:
./agents/**/*.md + ./agents/*.md — project-local agents- Global agents directory — shared agents
Project-local agents take precedence over global agents with the same name.
How It Works
Step 1: Discover Available Agents
Glob agent directories. For each file:
- Subdirectory layout: extract domain from parent folder
- Flat layout: group by filename prefix (2+ shared = domain, unique = "General")
- Extract agent name from
# Heading (fallback: filename → title-case)
- Extract one-line summary from first paragraph
If no agent files found, report which paths were checked and stop.
Step 2: Present Domain Menu
Available agent domains:
1. Engineering — Software Architect, Security Engineer
2. Marketing — SEO Specialist
3. Sales — Discovery Coach, Outbound Strategist
Pick domains or name specific agents (e.g., "1,3" or "security + seo"):
Step 3: Handle Selection
Accept flexible input:
- Numbers: "1,3" selects all agents from those domains
- Names: "security + seo" fuzzy-matches against discovered agents
- "all from engineering" selects every agent in that domain
If more than 5 agents selected, ask the user to narrow down (max 5 per team).
Step 4: Spawn Agents in Parallel
- Read each selected agent's markdown file
- Prompt for task description if not already provided
- Spawn all agents in parallel (general-purpose, independent — no inter-agent communication)
- Note any failures inline and continue with successful results
Step 5: Synthesize Results
Collect outputs and present a unified report:
- Results grouped by agent
- Synthesis: agreements, conflicts/tensions, recommended next steps
If only 1 agent selected, skip synthesis and present output directly.
Rules
- Dynamic discovery only. New files in the directory auto-appear. No hardcoded agent lists.
- Max 5 agents per team. More produces diminishing returns. Enforce at selection time.
- Parallel dispatch. All agents run simultaneously via parallel tool calls for independent work.
Example
User: team builder
Claude:
Available agent domains:
1. Engineering (2) — Software Architect, Security Engineer
2. Marketing (1) — SEO Specialist
Pick domains or name specific agents:
User: security + seo
Claude:
Selected: Security Engineer + SEO Specialist
What should they work on?
User: Review my Next.js e-commerce site before launch
[Both agents spawn in parallel]
Claude:
## Security Engineer Findings
- [findings...]
## SEO Specialist Findings
- [findings...]
## Synthesis
Both agree on: [...]
Tension: Security recommends CSP that blocks inline styles, SEO needs inline schema markup.
Next steps: [...]
