Agent skill

clawmail

Canonical joelclaw mail coordination protocol for all agents. Use when announcing work, checking inboxes, reserving files, releasing locks, handling task handoffs, triaging stale reservations, or auditing coordination quality. Triggers on: 'clawmail', 'agent mail', 'joelclaw mail', 'reserve files', 'release locks', 'handoff', 'agent coordination', 'mail status', or any multi-agent collaboration workflow.

View SKILL.md on GitHub Repository
Stars 51
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/joelhooks/joelclaw/tree/main/skills/clawmail

SKILL.md

Clawmail

Canonical agent coordination contract for joelclaw.

joelclaw mail is the only supported mail access surface for pi agents. Do not call mcp_agent_mail HTTP endpoints directly from agent prompts or role instructions.

Interfaces

Canonical interface

  • joelclaw mail ... (CLI)

Pi wrapper tools (allowed, but still CLI-backed)

These wrappers shell to joelclaw mail under the hood:

Tool CLI equivalent
mail_send joelclaw mail send
mail_inbox joelclaw mail inbox
mail_read joelclaw mail read
mail_reserve joelclaw mail reserve
mail_release joelclaw mail release
mail_status joelclaw mail status

Required Protocol (default for shared work)

  1. Check inbox before touching files
    • joelclaw mail inbox --agent <AgentName> --unread
  2. Announce active scope
    • joelclaw mail send --from <AgentName> --to <AgentName|team> --subject "Starting: <work>" "intent + paths + expected output"
  3. Reserve file paths before edits
    • joelclaw mail reserve --agent <AgentName> --paths "path/a.ts,path/b.ts" [--ttl-seconds 900]
  4. If work runs long, renew reservation lease
    • joelclaw mail renew --agent <AgentName> --paths "path/a.ts" [--extend-seconds 900]
  5. Send status/handoff updates during work
    • joelclaw mail send --subject "Status: ..." ...
  6. Release reservations after commit/handoff
    • joelclaw mail release --agent <AgentName> --paths "..."
    • or --all when done with all reserved paths

Subject Taxonomy (for searchability + steering)

Use these prefixes consistently:

  • Starting: — work start / intent announcement
  • Task: — handoff or assignment
  • Status: — progress update
  • Blocked: — dependency/incident requiring intervention
  • Done: — completion with artifact/commit IDs

Daily steering uses these signals to detect protocol drift.

Command Quick Reference

bash
# server + inbox health
joelclaw mail status

# register / refresh identity metadata
joelclaw mail register --agent MaroonReef --program pi --model gpt-5.4 --task "interactive"

# send a coordination message
joelclaw mail send --from MaroonReef --to BlueFox --subject "Task: update prompt docs" "Please edit SYSTEM.md and roles/*.md"

# inbox / read
joelclaw mail inbox --agent MaroonReef --unread
joelclaw mail read --agent MaroonReef --id 12

# reservations
joelclaw mail reserve --agent MaroonReef --paths "SYSTEM.md,roles/interactive.md" --ttl-seconds 900
joelclaw mail renew --agent MaroonReef --paths "SYSTEM.md" --extend-seconds 900
joelclaw mail release --agent MaroonReef --paths "SYSTEM.md,roles/interactive.md"
joelclaw mail release --agent MaroonReef --all

# audit/search
joelclaw mail locks
joelclaw mail search --query "Starting:"

Reliability Checks

Verify protocol health quickly

bash
joelclaw mail status
joelclaw mail locks
joelclaw mail search --query "Starting:"
joelclaw mail search --query "Status:"

joelclaw mail locks should reflect active advisory file reservations from the local git-mailbox file_reservations/ artifacts when that repo is available. This matters because the raw /mail/api/locks endpoint can under-report file reservations while still showing mailbox-internal archive/commit locks.

If search is degraded (DB/tool errors)

  • Treat signal counts as unreliable.
  • Continue using protocol anyway (announce/reserve/release).
  • Escalate to mail backend health repair and log findings.

If CLI flags are rejected unexpectedly

  • Your compiled ~/.bun/bin/joelclaw may be stale relative to source.
  • Rebuild CLI from packages/cli/src/cli.ts and retry.

Prompt Authoring Checklist (shore up prompts)

Any prompt/role/system contract that mentions coordination should:

  1. Reference clawmail as canonical protocol skill.
  2. State that mail access is via joelclaw mail (wrappers allowed, direct MCP not allowed).
  3. Include at minimum: inbox check, announce, reserve, release.
  4. Require path context in coordination messages.
  5. Encourage subject prefixes (Starting:, Task:, Status:, Blocked:, Done:).
  6. Avoid filler about mail when no shared edits/coordination are involved.

Steering Loop Integration

pi/extensions/session-lifecycle runs a daily monitor+steer review and emits:

  • agent-mail/steering.reviewed

Snapshot path:

  • ~/.joelclaw/workspace/agent-mail-steering/YYYY-MM-DD.json

Use steering hints to tighten protocol compliance when drift is detected.

Related

  • skills/agent-mail/SKILL.md (compatibility alias)
  • joelclaw mail --help
  • ADR-0172: Agent Mail via MCP Agent Mail

Recommended Agent Skills

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

joelhooks/joelclaw

skill-review

Audit and maintain the joelclaw skill inventory. Use when checking skill health, fixing broken symlinks, finding stale skills, or running the skill garden. Triggers: 'skill audit', 'check skills', 'stale skills', 'skill health', 'skill garden', 'broken skill', 'skill review', 'fix skills', 'garden skills', or any task involving skill inventory maintenance.

51 3
Explore
joelhooks/joelclaw

cli-design

Design and build agent-first CLIs with HATEOAS JSON responses, context-protecting output, and self-documenting command trees. Use when creating new CLI tools, adding commands to existing CLIs (joelclaw, slog), or reviewing CLI design for agent-friendliness. Triggers on 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output', or any task involving command-line tool creation.

51 3
Explore
joelhooks/joelclaw

daily-summary

Generate a daily system activity summary across all joelclaw subsystems. Triggers on 'daily summary', 'what happened today', 'system report', 'today's tally', 'activity summary', 'what did we do', 'daily report'.

51 3
Explore
joelhooks/joelclaw

inngest-durable-functions

Create and configure Inngest durable functions. Covers triggers (events, cron, invoke), step execution and memoization, idempotency, cancellation, error handling, retries, logging, and observability.

51 3
Explore
joelhooks/joelclaw

recall

Fan-out search across all memory sources when context is unclear or vaguely referenced. Triggers on: 'from earlier', 'remember when', 'what we discussed', 'that thing with', 'the conversation about', 'did we ever', 'what happened with', 'you mentioned', 'we talked about', 'earlier today', 'last session', 'the other day', or any vague reference to past context that needs resolution before the agent can act.

51 3
Explore
joelhooks/joelclaw

inngest-local

Set up self-hosted Inngest on macOS as a durable background task manager for AI agents. Interactive Q&A to match intent — from Docker one-liner to full k8s deployment with persistent state. Use when: 'set up inngest', 'background tasks', 'durable workflows', 'self-host inngest', 'event-driven functions', 'cron jobs', or any request for a local workflow engine.

51 3
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results