From 8676d3af1d5d28223dfc6f598afddc1b066e3b0b Mon Sep 17 00:00:00 2001 From: Sebastien Tang <128077249+sebastientang@users.noreply.github.com> Date: Tue, 17 Mar 2026 05:35:38 +0900 Subject: [PATCH] feat(skills): add team-builder skill (#501) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(skills): add team-builder skill Interactive agent picker that dynamically discovers agent markdown files, presents a browsable domain menu, and dispatches selected agents in parallel on a user-defined task with synthesized results. * fix: address PR #501 review feedback - Support both flat and subdirectory agent layouts - Multi-path discovery with fallback probe order - Empty-discovery fallback with helpful error message - Enforce 5-agent cap at selection time - Rename sections for clarity (Process → How It Works) Co-Authored-By: Claude Opus 4.6 (1M context) * fix: resolve PR #501 round 2 review feedback - Fix contradictory probe-order semantics: merge-all, not first-wins - Fix flat-layout domain extraction: frequency-based (2+ files) heuristic - Add multi-word domain limitation note for flat layout - Define deterministic ordering for overflow selection (alphabetical) - Clarify TeamCreate as Claude Code tool, not undefined reference - Shorten description frontmatter to ~60 chars Co-Authored-By: Claude Opus 4.6 (1M context) * fix: resolve PR #501 round 3 review feedback - Flat layout example now shows 2+ files per prefix (marketing, sales) to match the documented 2+ rule - Add filename-based fallback when agent file has no # Heading - Add failure handling for parallel agent spawns in Step 4 Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Sebastien Tang <128077249+Sabdenrog@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) --- skills/team-builder/SKILL.md | 161 +++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 skills/team-builder/SKILL.md diff --git a/skills/team-builder/SKILL.md b/skills/team-builder/SKILL.md new file mode 100644 index 00000000..811a6e21 --- /dev/null +++ b/skills/team-builder/SKILL.md @@ -0,0 +1,161 @@ +--- +name: team-builder +description: Interactive agent picker for composing and dispatching parallel teams +origin: community +--- + +# Team Builder + +Interactive menu for browsing and composing agent teams on demand. Works with flat or domain-subdirectory agent collections. + +## When to Use + +- You have multiple agent personas (markdown files) and want to pick which ones to use for a task +- You want to compose an ad-hoc team from different domains (e.g., Security + SEO + Architecture) +- You want to browse what agents are available before deciding + +## Prerequisites + +Agent files must be 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 is inferred from the 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. A prefix counts as a domain when 2+ files share it. Files with unique prefixes go to "General". Note: the algorithm splits at the first `-`, so multi-word domains (e.g., `product-management`) should use the subdirectory layout instead: + +``` +agents/ +├── engineering-security-engineer.md +├── engineering-software-architect.md +├── marketing-seo-specialist.md +├── marketing-content-strategist.md +├── sales-discovery-coach.md +└── sales-outbound-strategist.md +``` + +## Configuration + +Agent directories are probed in order and results are merged: + +1. `./agents/**/*.md` + `./agents/*.md` — project-local agents (both depths) +2. `~/.claude/agents/**/*.md` + `~/.claude/agents/*.md` — global agents (both depths) + +Results from all locations are merged and deduplicated by agent name. Project-local agents take precedence over global agents with the same name. A custom path can be used instead if the user specifies one. + +## How It Works + +### Step 1: Discover Available Agents + +Glob agent directories using the probe order above. Exclude README files. For each file found: +- **Subdirectory layout:** extract the domain from the parent folder name +- **Flat layout:** collect all filename prefixes (text before the first `-`). A prefix qualifies as a domain only if it appears in 2 or more filenames (e.g., `engineering-security-engineer.md` and `engineering-software-architect.md` both start with `engineering` → Engineering domain). Files with unique prefixes (e.g., `code-reviewer.md`, `tdd-guide.md`) are grouped under "General" +- Extract the agent name from the first `# Heading`. If no heading is found, derive the name from the filename (strip `.md`, replace hyphens with spaces, title-case) +- Extract a one-line summary from the first paragraph after the heading + +If no agent files are found after probing all locations, inform the user: "No agent files found. Checked: [list paths probed]. Expected: markdown files in one of those directories." Then 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"): +``` + +- Skip domains with zero agents (empty directories) +- Show agent count per domain + +### Step 3: Handle Selection + +Accept flexible input: +- Numbers: "1,3" selects all agents from Engineering and Sales +- Names: "security + seo" fuzzy-matches against discovered agents +- "all from engineering" selects every agent in that domain + +If more than 5 agents are selected, list them alphabetically and ask the user to narrow down: "You selected N agents (max 5). Pick which to keep, or say 'first 5' to use the first five alphabetically." + +Confirm selection: +``` +Selected: Security Engineer + SEO Specialist +What should they work on? (describe the task): +``` + +### Step 4: Spawn Agents in Parallel + +1. Read each selected agent's markdown file +2. Prompt for the task description if not already provided +3. Spawn all agents in parallel using the Agent tool: + - `subagent_type: "general-purpose"` + - `prompt: "{agent file content}\n\nTask: {task description}"` + - Each agent runs independently — no inter-agent communication needed +4. If an agent fails (error, timeout, or empty output), note the failure inline (e.g., "Security Engineer: failed — [reason]") and continue with results from agents that succeeded + +### Step 5: Synthesize Results + +Collect all outputs and present a unified report: +- Results grouped by agent +- Synthesis section highlighting: + - Agreements across agents + - Conflicts or tensions between recommendations + - Recommended next steps + +If only 1 agent was selected, skip synthesis and present the output directly. + +## Rules + +- **Dynamic discovery only.** Never hardcode agent lists. New files in the directory auto-appear in the menu. +- **Max 5 agents per team.** More than 5 produces diminishing returns and excessive token usage. Enforce at selection time. +- **Parallel dispatch.** All agents run simultaneously — use the Agent tool's parallel invocation pattern. +- **Parallel Agent calls, not TeamCreate.** This skill uses parallel Agent tool calls for independent work. TeamCreate (a Claude Code tool for multi-agent dialogue) is only needed when agents must debate or respond to each other. + +## Examples + +``` +User: team builder + +Claude: +Available agent domains: +1. Engineering (2) — Software Architect, Security Engineer +2. Marketing (1) — SEO Specialist +3. Sales (4) — Discovery Coach, Outbound Strategist, Proposal Strategist, Sales Engineer +4. Support (1) — Executive Summary + +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, each applying their specialty to the codebase] + +Claude: +## Security Engineer Findings +- [findings...] + +## SEO Specialist Findings +- [findings...] + +## Synthesis +Both agents agree on: [...] +Tension: Security recommends CSP that blocks inline styles, SEO needs inline schema markup. Resolution: [...] +Next steps: [...] +```