swarm-mail

Coordinate with other agents using Swarm mail and file locking

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill facilitates advanced multi-agent coordination and resource management within Swarm deployments. It enables agents to communicate through structured mail handoffs, manage asynchronous tasks via queues, and prevent development conflicts using a robust advisory file-locking system, ensuring high-integrity collaboration on shared codebases.

Use Cases

  • Collaborative Coding: Enable multiple AI agents to work on the same repository simultaneously by using file locks to prevent merge conflicts and code overwrites.
  • Structured Task Handoffs: Use the Swarm mail system to transfer context and specific instructions between specialized agents, ensuring seamless transitions in complex workflows.
  • Automated Code Reviews: Orchestrate a workflow where a developer agent automatically requests a review from a specialized QA agent upon completing a task.
  • Asynchronous Task Management: Utilize the queue system to allow agents to schedule follow-up actions or manage long-running sequences without blocking immediate progress.
  • Conflict Resolution: Check for existing file claims before editing critical infrastructure or configuration files to maintain system stability in multi-agent environments.
nameswarm-mail
descriptionCoordinate with other agents using Swarm mail and file locking
alwaysApplytrue

Swarm Multi-Agent Coordination

You are part of a Swarm deployment with multiple AI agents working on the same codebase. Use these patterns to coordinate effectively.

When to Use Mail vs Queue vs Direct

  • Mail: Handoff tasks to specific agents, request reviews, report completion
  • Queue: Send work to yourself for later (cooldown, complex sequences)
  • Direct: Only for emergency interrupts (use swarm inject)

Writing Actionable Handoff Messages

Good handoff messages require no follow-up questions.

Good Example

Subject: Review PR #123 - User authentication refactor Body:

  • PR is ready for review at https://github.com/...
  • Focus on: error handling in login flow
  • Tests pass locally, CI pending
  • After review, send results to agent-xyz

Bad Example

Subject: Please review Body: The PR is ready.

Advisory File Locking

Before editing files, claim a lock:

swarm lock claim --agent $AGENT_ID --path "src/api/auth.go" --ttl 30m

Check for conflicts before claiming:

swarm lock check --path "src/api/auth.go"

Always release when done:

swarm lock release --agent $AGENT_ID

Subject/Body Conventions

Subjects should be:

  • Specific: "Fix null pointer in UserService.getById()"
  • Searchable: Include file names, function names, issue numbers
  • Actionable: Start with verb (Fix, Review, Implement, Update)

Checking Your Inbox

Poll for new work regularly:

swarm mail inbox --agent $AGENT_ID --unread

Additional template files

See the templates in templates/:

  • templates/handoff.md
  • templates/review-request.md
  • templates/conflict-resolution.md