Agent skill

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.

View SKILL.md on GitHub Repository
Stars 25
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/leegonzales/AISkills/tree/main/AgentMail/agent-mail

SKILL.md

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:

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

If not initialized:

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

Core Rituals (MANDATORY)

1. Session Start

Before ANY work, join and check inbox:

bash
agent-mail join claude
agent-mail check claude

If unread messages exist:

bash
agent-mail read claude

Process all messages before proceeding.

2. Before Claiming Work

Notify partners before starting any task:

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

3. After Completing Work

Report completion immediately:

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

4. When Blocked

Notify with HIGH priority:

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

5. Periodic Check-in

For long tasks (>5 minutes):

bash
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

bash
# 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:

    bash
    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:

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

Examples

See references/examples.md for full conversation examples.

Recommended Agent Skills

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

leegonzales/AISkills

context-continuity

High-fidelity context transfer protocol for moving conversations between AI agents. Preserves decision tempo, open loops, and critical context with graceful degradation. Use when the user says "transfer," "handoff," "continue this in another chat," or needs to work around context window limits. Produces structured artifacts (Minimal ~200 words, Full ~1000 words). DO NOT trigger on simple "summarize our conversation" requests—only when transfer intent is explicit.

25 5
Explore
leegonzales/AISkills

codex-peer-review

25 5
Explore
leegonzales/AISkills

silicon-doppelganger

Build psychometrically accurate personal proxy agents for the PAIRL Conductor system. Extracts personality, decision heuristics, and values into portable schemas that enable AI agents to negotiate, filter, and act on a principal's behalf.

25 5
Explore
leegonzales/AISkills

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements. Dispatches three independent reviewers in parallel.

25 5
Explore
leegonzales/AISkills

fabric-patterns

Run danielmiessler/fabric CLI patterns for content analysis, extraction, summarization, writing, security analysis, and more. Use when user asks to "use fabric," "run a pattern," "extract wisdom," "summarize with fabric," or when piping content through AI patterns would be more effective than inline processing. Triggers include "fabric," "pattern," "extract wisdom," "summarize this article," "analyze this threat report," or any reference to a specific fabric pattern name.

25 5
Explore
leegonzales/AISkills

moltbook-enclave

Secure, air-gapped interface for Moltbook (social network for AI agents). Isolates untrusted external content from your main agent's memory and context.

25 5
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results