Agent Skills: Swarm Coordination Skill

Swarm Coordination Skill

Step 1: Analyze Task for Parallelization

Identify parallelizable work:

| Pattern | Example | Strategy | | ----------------- | ------------------------------ | ---------------------- | | Independent tasks | Review multiple files | Spawn in parallel | | Dependent tasks | Design → Implement | Sequential spawn | | Fan-out/Fan-in | Multiple reviews → Consolidate | Parallel + Aggregation | | Pipeline | Parse → Transform → Validate | Sequential handoff |

Step 2: Spawn Agents in Parallel

Use the Task tool to spawn multiple agents in a single message:

// Spawn multiple agents in ONE message for parallel execution
Task({
  task_id: 'task-1',
  subagent_type: 'general-purpose',
  description: 'Architect reviewing design',
  prompt: 'Review architecture...',
});

Task({
  task_id: 'task-2',
  subagent_type: 'general-purpose',
  description: 'Security reviewing design',
  prompt: 'Review security...',
});

Key: Both Task calls must be in the SAME message for true parallelism.

Step 3: Define Handoff Format

Use structured formats for agent communication:

## Agent Handoff: [Source] → [Target]

### Context

- Task: [What was done]
- Files: [Files touched]

### Findings

- [Key finding 1]
- [Key finding 2]

### Recommendations

- [Action item 1]
- [Action item 2]

### Artifacts

- [Path to artifact 1]
- [Path to artifact 2]

Step 4: Aggregate Results

Combine outputs from parallel agents:

## Swarm Results Aggregation

### Participating Agents

- Architect: Completed ✅
- Security: Completed ✅
- DevOps: Completed ✅

### Consensus Points

- [Point all agents agree on]

### Conflicts

- [Point agents disagree on]
- Resolution: [How to resolve]

### Combined Recommendations

1. [Prioritized recommendation]
2. [Prioritized recommendation]

Step 5: Handle Failures

Strategies for partial failures:

| Scenario | Strategy | | ----------------------- | ------------------------------- | | Agent timeout | Retry with simpler prompt | | Agent error | Continue with available results | | Conflicting results | Use consensus-voting skill | | Missing critical result | Block and retry |

</execution_process>

<best_practices>

1. Parallelize Aggressively: Independent work should run in parallel
2. Structured Handoffs: Use consistent formats for communication
3. Graceful Degradation: Continue with partial results when safe
4. Clear Aggregation: Combine results systematically
5. Track Provenance: Know which agent produced each result

</best_practices> </instructions>

Get architecture, security, and performance reviews for the new API design

Swarm Coordination:

// Spawn 3 reviewers in parallel (single message)
Task({ task_id: 'task-3', description: 'Architect reviewing API', prompt: '...' });
Task({ task_id: 'task-4', description: 'Security reviewing API', prompt: '...' });
Task({ task_id: 'task-5', description: 'Performance reviewing API', prompt: '...' });

Aggregated Results:

## API Design Review (3 agents)

### Consensus

- RESTful design is appropriate
- Need authentication on all endpoints

### Recommendations by Priority

1. [HIGH] Add rate limiting (Security)
2. [HIGH] Use connection pooling (Performance)
3. [MED] Add versioning to URLs (Architect)

</usage_example> </examples>

Rules

• Always spawn independent agents in parallel
• Use structured handoff formats
• Handle partial failures gracefully

Related Workflow

This skill has a corresponding workflow for complex multi-agent scenarios:

• Workflow: .claude/workflows/enterprise/swarm-coordination-skill-workflow.md
• When to use workflow: For massively parallel task execution with Queen/Worker topology, fault tolerance, and distributed coordination (large-scale refactoring, parallel code review, multi-file implementation)
• When to use skill directly: For simple parallel agent spawning or when integrating swarm patterns into other workflows

Workflow Integration

This skill powers multi-agent orchestration patterns across the framework:

Router Decision: .claude/workflows/core/router-decision.md

• Router uses swarm patterns for parallel agent spawning
• Planning Orchestration Matrix defines when to use swarm coordination

Artifact Lifecycle: .claude/workflows/core/skill-lifecycle.md

• Swarm patterns apply to artifact creation at scale
• Parallel validation of multiple artifacts

Related Workflows:

• consensus-voting skill for resolving conflicting agent outputs
• context-compressor skill for aggregating parallel results
• Enterprise workflows in .claude/workflows/enterprise/ use swarm patterns

Iron Laws

1. NEVER spawn workers sequentially — all independent agents must be dispatched in a single message
2. ALWAYS implement failure detection; never let a hung worker block the swarm indefinitely
3. NEVER allow cross-worker communication — all coordination must flow through the Queen
4. ALWAYS use structured handoff format for worker reports to enable programmatic aggregation
5. NEVER spawn more than 7 workers in a single fan-out — coordination overhead dominates beyond that

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | -------------------------- | ------------------------------------------------------ | ---------------------------------------------------------- | | Sequential spawning | No parallelism; swarm executes like a queue | Spawn all independent workers in a single message | | Cross-worker communication | O(N²) coordination chaos | All worker-to-worker communication flows through the Queen | | No failure handling | One worker crash stalls the swarm | Detect hung/failed workers and re-spawn with fresh state | | Unbounded parallelism | Coordination overhead exceeds speedup beyond 7 workers | Limit to 5-7 workers per fan-out for optimal throughput | | Free-form worker reports | Cannot aggregate results programmatically | Require all workers to use the structured handoff template |

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.