Agent-Skills.md

Agent Skills: Agent Mail

Coordinate with other AI agents via project-local Maildir messaging. Use when operating in tandem mode with Claude, Gemini, or other agents. Enables claiming tasks, reporting completion, handling blocks, and synchronizing work across terminals.

UncategorizedID: leegonzales/aiskills/agent-mail

Repository

leegonzales/aiskills
leegonzalesLicense: MIT
165

Install this agent skill to your local

pnpm dlx add-skill https://github.com/leegonzales/AISkills/tree/HEAD/AgentMail/agent-mail

Skill Files

Browse the full folder contents for agent-mail.

Download Skill

Loading file tree…

AgentMail/agent-mail/SKILL.md

Skill Metadata

Name
agent-mail
Description
Coordinate with other AI agents via project-local Maildir messaging. Use when operating in tandem mode with Claude, Gemini, or other agents. Enables claiming tasks, reporting completion, handling blocks, and synchronizing work across terminals.

Agent Mail

Project-local messaging system for multi-agent coordination. Email semantics for AI agents working together.

When to Use

Invoke when:

  • Operating in tandem mode with other AI agents (Claude + Gemini, multiple Claudes)
  • Starting a session and need to check for messages from partners
  • Claiming a task and need to notify other agents
  • Completing work and need to report handoff
  • Blocked and need to notify partners urgently
  • Need to coordinate or synchronize work across terminals

Pre-requisites

Check if agent-mail is initialized:

ls .agent-mail/  # Should exist in project root

If not initialized:

npx tsx ~/Projects/leegonzales/agent-mail/src/mail.ts init

Core Rituals (MANDATORY)

1. Session Start

Before ANY work, join and check inbox:

agent-mail join claude
agent-mail check claude

If unread messages exist:

agent-mail read claude

Process all messages before proceeding.

2. Before Claiming Work

Notify partners before starting any task:

agent-mail broadcast claude "Claiming Task" "Claiming IE-XX. Starting now."

3. After Completing Work

Report completion immediately:

agent-mail broadcast claude "Task Complete" "IE-XX complete. Output at: path/to/result"

4. When Blocked

Notify with HIGH priority:

agent-mail send claude gemini "BLOCKED" "IE-XX blocked: reason" --priority high

5. Periodic Check-in

For long tasks (>5 minutes):

agent-mail broadcast claude "Status Update" "Still on IE-XX. 60% complete."

Message Types

| Subject | Purpose | |---------|---------| | Claiming Task | Announcing you're taking a task | | Task Complete | Work finished, ready for handoff | | BLOCKED | Cannot proceed, need help | | Status Update | Progress on long task | | Question | Need clarification | | Answer | Responding to question | | Handoff | Explicitly passing work | | Sync Request | Asking for partner status |

Quick Reference

# Project
agent-mail init                    # Initialize in current project
agent-mail join claude             # Register as agent
agent-mail who                     # See active agents
agent-mail info                    # Project info

# Messaging
agent-mail check claude            # Peek inbox (no mark)
agent-mail read claude             # Read + mark as read
agent-mail send claude gemini "Subject" "Body"
agent-mail broadcast claude "Subject" "Body"
agent-mail reply claude <id> "Body"
agent-mail status                  # All inboxes
agent-mail history claude 10       # Message history

Integration with Beads

When using beads task tracking:

  1. Claim in beads first, then notify:

    bd update IE-XX --status in_progress --assignee Claude
agent-mail broadcast claude "Claiming Task" "Claimed IE-XX in beads"

  2. Close in beads, then notify:

    bd close IE-XX "Completed"
agent-mail broadcast claude "Task Complete" "IE-XX closed"

Examples

See references/examples.md for full conversation examples.