---

name: swarm-mcp description: Join and coordinate through the swarm MCP server. Use when registering a Claude Code session, coordinating multiple agents, using swarm tasks/messages/KV/locks, or bootstrapping planner, implementer, reviewer, researcher, or generalist roles. argument-hint: "[planner|implementer|reviewer|researcher|generalist]" arguments: [role] metadata: short-description: Coordinate work through swarm-mcp domain: agent-coordination role: workflow scope: workflow

Swarm MCP

Use this skill when the swarm MCP server is available in the current session and the task benefits from multi-agent coordination.

This skill assumes the swarm tools are already mounted. If they are not present, say so clearly and fall back to local work or direct setup help.

Role argument: $role.

If the user invoked this skill with a role argument, follow the matching role reference. If no role was provided, use the generalist flow and load role references only when choosing collaborators or accepting delegated work.

Start Here

1. Bootstrap into the swarm with register
2. Inspect the current swarm with whoami, list_instances, poll_messages, and list_tasks
3. While editing, call lock_file — its response includes any peer annotations, so a separate check call is unnecessary. Skip locking entirely when alone in scope.
4. Delegate or coordinate with request_task, send_message, or broadcast
5. Leave durable context with annotate and small shared state with kv_set
6. Complete a task with a single update_task (terminal status). Locks on the task's files release automatically.

For planner sessions, the server maintains owner/planner automatically. Check it with kv_get to see whether you currently own planner duties.

Role Routing

• planner: load references/planner.md and register with role:planner
• implementer: load references/implementer.md and register with role:implementer
• reviewer: load references/reviewer.md and register with role:reviewer
• researcher: load references/researcher.md and register with role:researcher
• generalist or no role: register without a role: token unless the user specified one, then handle mixed work using the core workflow

When the role is unclear, do not invent one. Ask one short question or proceed as a generalist if the task is already actionable.

Task Features

• Priority: Tasks have an integer priority field (higher = more urgent). list_tasks returns tasks sorted by priority. Claim the highest-priority open task first.
• Unread-message guard: claim_task refuses to claim new open work while you have unread direct messages. Call poll_messages and handle corrections before retrying. Override only when intentionally ignoring those messages.
• Dependencies: Tasks can have a depends_on field (array of task IDs). A task with unmet dependencies starts as blocked and auto-transitions to open when all deps complete. If a dependency fails, downstream tasks are auto-cancelled.
• Approval gates: Tasks can be set to approval_required status. They remain gated until approved (transitions to open) or explicitly cancelled. Use this for true approval checkpoints, not routine code review.
• Idempotency: Tasks can have an idempotency_key field that prevents duplicate creation on retry.

Load References As Needed

Constraints

Must Do

• Call register before using other swarm tools
• Use whoami, list_instances, poll_messages, and list_tasks early in the session. If list_instances returns only you, skip per-edit locking until peers join.
• Call lock_file while editing when peers are present. Read the returned annotations as your pre-edit check.
• Use update_task once at task completion (terminal status). claim_task already moved the task to in_progress.
• Use explicit review tasks for normal review handoff
• Treat role: labels as conventions, not hard schema
• Treat sessions without a role: label token as generalists
• Prefer the highest-priority open task when claiming work
• Include structured results (JSON with files_changed, test_status, summary) when completing tasks

Must Not Do

• Assume other sessions share your exact working directory unless scope and file_root make that true
• Invent role-routing behavior that is not visible from labels, messages, tasks, or instructions
• Hold file locks longer than needed
• Use assignee for a stale or unknown instance
• Confuse direct messages with task handoff; use request_task for structured delegated work
• Try to claim blocked tasks — they will become open automatically
• Shell out to the swarm-mcp CLI from inside your agent loop — use the MCP tools. The CLI exists for helper scripts that cannot speak MCP. See references/cli.md when writing such a script.

Default Behavior

When the skill triggers, prefer this sequence unless the task clearly requires something else:

1. Verify the swarm tools exist
2. register
3. whoami
4. list_instances
5. poll_messages
6. list_tasks
7. Summarize active specialists, open work, and collision risks before taking action
8. Act on any pending work (claim tasks, respond to messages)
9. Enter an autonomous loop using wait_for_activity — react to messages, task changes, KV updates, and instance changes as they arrive. Do not wait for user prompting between tasks.

Collaboration Heuristics

• Prefer request_task when the work should be tracked and completed
• Prefer explicit review tasks over passive review scans
• Prefer send_message for targeted coordination that does not need task state
• Prefer broadcast for short status updates that help everyone
• Prefer annotate for file-specific findings another agent may need later
• Prefer a matching role: token when choosing a specialist
• Prefer a matching team: token when the swarm uses soft teams
• Fall back to any matching specialist, then to a generalist, when the ideal collaborator is unavailable
• Use wait_for_activity as your idle loop — it blocks until new messages, task changes, KV updates, or instance changes arrive, then returns the updates so you can act immediately
• If you are acting as a planner, watch owner/planner on kv_updates so you can resume from plan/latest after failover
• Update your progress with kv_set("progress/<your-instance-id>", ...) while working on tasks so others can check on you without interrupting
• Messages prefixed with [auto] are system notifications (task assignments, completions, stale-agent recovery) — treat them like any other actionable message
• When you receive a [signal:complete] broadcast, the planner is signaling all work is done — finish current work, deregister, and stop

Structured Results Convention

When completing a task, prefer a JSON result:

{
  "files_changed": ["src/foo.ts"],
  "test_status": "pass",
  "summary": "What was done and why."
}

Fall back to a plain string if you cannot produce structured output.