claude-code:agent-team
npx machina-cli add skill bendrucker/claude/agent-team --openclawAgent Teams
Team Lifecycle
Describe the task and team structure in natural language. Claude creates the team, spawns teammates, and coordinates work.
- Delegate mode (Shift+Tab): restricts the lead to coordination-only tools — no direct implementation
- Plan approval: require teammates to plan before implementing. The teammate works read-only until the lead approves.
- Shutdown: ask the lead to shut down teammates individually, then clean up the team. Always clean up via the lead.
Task Management
Tasks: pending, in progress, completed. Tasks can depend on other tasks — blocked tasks unlock automatically when dependencies complete.
- Lead assigns: tell the lead which task to assign
- Self-claim: teammates pick up unassigned, unblocked tasks after finishing
- File locking prevents race conditions on simultaneous claims
Communication
- message: send to one specific teammate
- broadcast: send to all teammates (use sparingly — costs scale with team size)
- Messages deliver automatically; the lead doesn't need to poll
- Idle notifications are automatic when a teammate finishes a turn
Architecture
Teams are stored locally:
- Team config:
~/.claude/teams/{team-name}/config.json - Task list:
~/.claude/tasks/{team-name}/
The config contains a members array with each teammate's name, agent ID, and type. Teammates read this file to discover each other.
Teammates inherit the lead's permission settings at spawn. Each teammate loads project context (CLAUDE.md, MCP servers, skills) plus the spawn prompt — the lead's conversation history does not carry over.
Limitations
- No session resumption for in-process teammates (
/resumewon't restore them) - Task status can lag — check and nudge if stuck
- One team per session, no nested teams
- Lead is fixed for the team's lifetime
Known Issues
- tmux backend: teammates spawned in tmux panes may never receive their initial prompt or poll their inbox, causing them to idle indefinitely (#23415). A separate race condition between pane creation and shell initialization can prevent the
claudecommand from executing at all (#25315). Usein-processbackend (the default) as a workaround.
References
- references/hooks.md —
TeammateIdleandTaskCompletedquality gate hooks - references/practices.md — task sizing, spawn prompts, file conflicts, team structures
- references/interaction.md — display modes, keyboard shortcuts, direct teammate interaction
- Agent Teams Documentation
Source
git clone https://github.com/bendrucker/claude/blob/main/plugins/claude-code/skills/agent-team/SKILL.mdView on GitHub Overview
Orchestrate Claude Code agent teams across their lifecycle: from creating teams and spawning teammates to assigning tasks and configuring teammate modes. It also supports quality gate hooks to enforce checks before completion. This helps coordinate complex coding efforts and prevent race conditions.
How This Skill Works
Input a natural-language task and team structure; Claude will create the team, spawn teammates, and coordinate work. Task management uses statuses (pending, in progress, completed) with dependencies and auto-unlock; leads assign first task, teammates can self-claim unassigned tasks, and file locking prevents concurrent claims. Teammates read the local config and inherit the lead's permissions at spawn; communications use direct messages or broadcasts.
When to Use It
- Kick off a new project sprint by creating a team, adding teammates, and outlining tasks.
- Enable Delegate mode to restrict the lead to coordination-only tools during planning.
- Require plan approval before implementation to ensure teammate plans are vetted.
- Manage interdependent tasks with dependencies and auto-unlock when prerequisites complete.
- Set up team quality gate hooks and hooks docs to enforce checks on task completion.
Quick Start
- Step 1: Describe the team and spawn teammates; configure modes (e.g., delegate, plan-approval).
- Step 2: Define tasks with dependencies and have the lead assign the first task; enable self-claim for unassigned work as needed.
- Step 3: Start work, use broadcasts for updates sparingly, monitor progress, and clean up the team when done.
Best Practices
- Define team config in ~/.claude/teams/{team-name}/config.json and document members.
- Lead should assign the initial task and verify plan if plan approval is enabled.
- Use self-claim for unassigned, unblocked tasks to maximize throughput.
- Enable file locking to prevent race conditions on concurrent claims.
- Use broadcast sparingly due to costs; ensure timely shutdown and cleanup.
Example Use Cases
- New feature sprint: Lead creates a feature team, spawns four teammates, assigns initial tasks with dependencies, and uses plan approval.
- Bug triage: Quick-team is spawned to fix a critical bug; lead assigns tasks and uses direct messages to a single teammate.
- Delegate-mode coordination: Lead restricts to coordination-only tools while teammates draft implementation plan.
- Quality gate enforcement: Team hooks run checks before task completion to ensure standards are met.
- Local context loading: Teammates load project context (CLAUDE.md, MCP servers, skills) and spawn prompts; lead conversation history does not carry over.
