Agent skill

agent-mail

Inter-agent communication for multi-agent workflows. Use when multiple agents need to coordinate, share information, or reserve resources.

View SKILL.md on GitHub Repository
Stars 21
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/johnlindquist/claude/tree/main/skills/agent-mail

SKILL.md

Agent Mail System

Communication system for coordinating multiple agents.

Overview

Agent mail enables:

  • Message passing between agents
  • File reservation to prevent conflicts
  • Session tracking across agents
  • Thread-based conversations

Session Management

Start Agent Session

Register agent and get inbox:

bash
# Initialize session
curl -X POST http://localhost:3847/api/session/start \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "program": "claude-code",
    "model": "opus-4",
    "agent_name": "agent-1",
    "task_description": "Working on auth module"
  }'

List Agents

bash
curl http://localhost:3847/api/agents?project_path=/path/to/project

Agent Info

bash
curl http://localhost:3847/api/agents/agent-1?project_path=/path/to/project

Messaging

Send Message

bash
curl -X POST http://localhost:3847/api/mail/send \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "sender_name": "agent-1",
    "to": ["agent-2"],
    "subject": "Auth module complete",
    "body_md": "## Summary\nAuth implementation is done.\n\n## Files changed\n- src/auth/*",
    "importance": "normal",
    "ack_required": false
  }'

Check Inbox

bash
curl "http://localhost:3847/api/mail/inbox?project_path=/path/to/project&agent_name=agent-1"

Reply to Message

bash
curl -X POST http://localhost:3847/api/mail/reply \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "message_id": 123,
    "sender_name": "agent-2",
    "body_md": "Thanks! I'\''ll start on the API integration."
  }'

Acknowledge Message

bash
curl -X POST http://localhost:3847/api/mail/ack \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-2",
    "message_id": 123
  }'

Search Messages

bash
curl "http://localhost:3847/api/mail/search?project_path=/path/to/project&query=authentication"

File Reservations

Prevent conflicts when multiple agents edit files.

Reserve Files

bash
curl -X POST http://localhost:3847/api/files/reserve \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-1",
    "paths": ["src/auth/*.ts", "src/config.ts"],
    "exclusive": true,
    "reason": "Implementing authentication",
    "ttl_seconds": 3600
  }'

Check Reservations

bash
curl "http://localhost:3847/api/files/reservations?project_path=/path/to/project"

Release Files

bash
curl -X POST http://localhost:3847/api/files/release \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-1",
    "paths": ["src/auth/*.ts"]
  }'

Thread Management

Get Thread Summary

bash
curl "http://localhost:3847/api/mail/thread/THREAD_ID/summary?project_path=/path/to/project"

Thread Operations

Threads are automatically created when replying to messages.

Coordination Patterns

Task Handoff

markdown
Agent 1 completes task:
1. Reserve output files
2. Complete work
3. Send message to Agent 2 with handoff details
4. Release file reservations

Agent 2 receives:
1. Get inbox
2. Reserve input files
3. Continue work
4. Acknowledge receipt

Parallel Work

markdown
Coordinator:
1. Reserve coordination files
2. Send tasks to agents
3. Wait for completion messages
4. Merge results

Workers:
1. Reserve assigned files
2. Complete task
3. Send completion message
4. Release files

Review Request

markdown
Author:
1. Complete code
2. Send review request to reviewer agents
3. Wait for feedback

Reviewers:
1. Get inbox
2. Review code (read-only, no reservation needed)
3. Send feedback message

Health Check

bash
curl http://localhost:3847/api/health

Message Importance Levels

Level Use Case
low FYI, status updates
normal Standard communication
high Needs attention soon
urgent Blocking, needs immediate response

Best Practices

  1. Reserve before editing - Prevent conflicts
  2. Use meaningful subjects - Easy inbox scanning
  3. Acknowledge important - Confirm receipt when ack_required
  4. Release promptly - Don't hold reservations unnecessarily
  5. Use threads - Keep related messages together
  6. Check inbox regularly - Don't miss messages
  7. Handoff cleanly - Include all needed context

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

johnlindquist/claude

testgen

Generate tests using AI and run test suites. Use for generating unit tests, running coverage reports, and mutation testing.

21 5
Explore
johnlindquist/claude

article

Generate technical articles and documentation using AI. Use for writing blog posts, documentation, and technical content.

21 5
Explore
johnlindquist/claude

packx

Bundle code context for AI. ALWAYS use --limit 49k unless user explicitly requests otherwise. Use for creating shareable code bundles and preparing context for LLMs.

21 5
Explore
johnlindquist/claude

long-agent

Manage long-running agent sessions. Use for tracking progress in extended tasks, maintaining context across long sessions, and managing multi-step workflows.

21 5
Explore
johnlindquist/claude

db

Database operations for SQLite, PostgreSQL, and MySQL. Use for queries, schema inspection, migrations, and AI-assisted query generation.

21 5
Explore
johnlindquist/claude

investigate

Debug and investigate code issues using search and AI analysis. Use when stuck on bugs, tracing execution flow, or understanding complex code.

21 5
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results