agent-mail_skill

Overview

This skill provides a project-local Maildir-style messaging system for coordinating multiple AI agents working in tandem. It offers email-like semantics to claim tasks, report completion, broadcast status, and escalate blocks across terminals. The tool is optimized for workflows involving Claude, Gemini, or other agent instances. It keeps coordination local to the project to avoid external dependencies.

How this skill works

Agents join a project mailbox and use simple CLI commands to check, read, send, broadcast, reply, and view history. Messages are stored in a .agent-mail folder in the project root using Maildir conventions so every agent can inspect inboxes and mark messages. Common subjects (Claiming Task, Task Complete, BLOCKED, Status Update) standardize intent so agents can programmatically interpret and act on signals. Integrations with task trackers (like beads) make claims and closures explicit across systems.

When to use it

• When running multiple AI agents in tandem (Claude, Gemini, etc.) within the same project.
• At the start of a session to join and process pending messages before doing any work.
• Before claiming a task to notify peers and avoid duplicated effort.
• Right after finishing work to report completion and provide output locations for handoff.
• When blocked and needing urgent help from other agents or human operators.
• During long-running tasks to send periodic check-ins and avoid stale assumptions.

Best practices

• Always run join and check before starting any work to clear unread messages first.
• Broadcast claims before starting and broadcast completion immediately after finishing.
• Use the BLOCKED subject with high priority for urgent impediments so partners can respond fast.
• Integrate with your task tracker (beads) — claim in beads first, then broadcast the claim.
• Keep message bodies concise and include clear identifiers (task ID, path to results, percent complete).

Example use cases

• Two language models coordinating a dataset labeling pipeline: one agent claims a file, the other skips claimed items.
• A generator and verifier agent: generator broadcasts completion with output path, verifier picks it up and reports issues.
• Multiple Claude instances sharing test cases: agents broadcast status updates to avoid duplicate runs.
• Agent hits a blocking bug in a build step and sends a BLOCKED message to request assistance from a human or another agent.
• Long analysis job where the agent sends periodic Status Update messages every few minutes to keep collaborators informed.