How do I install the Mail skill?

Run npx skillmds@latest add modbender/mail in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Mail?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

modbender (@modbender) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Mail by modbender — Agent Skill

Name: Mail
Rating: 4.2 (5 reviews)
Author: modbender

File contents

Requirements

Binaries:

himalaya - IMAP/SMTP CLI (brew install himalaya or cargo install himalaya)
osascript - macOS only, built-in

Credentials:

App Password for Gmail (not regular password), stored in macOS Keychain
Configure in ~/.config/himalaya/config.toml

Data Access

Read-only paths:

~/Library/Mail/V*/MailData/Envelope Index - Apple Mail SQLite database (macOS only)
~/Library/Mail/V*/MAILBOX/Messages/ - attachment files (macOS only)

Scope

This skill:

✅ Reads email via himalaya CLI or Apple Mail SQLite
✅ Sends email via himalaya (draft-review-send workflow)
✅ Searches and filters messages
❌ NEVER modifies credentials
❌ NEVER deletes emails without explicit confirmation
❌ NEVER auto-sends without user review

Quick Reference

Topic	File
Apple Mail SQLite queries	`apple-mail.md`
himalaya CLI patterns	`himalaya.md`
Send/reply protocol	`sending.md`

Core Rules

1. Platform Detection

macOS with Apple Mail: Use SQLite queries (100x faster than AppleScript)
Cross-platform: Use himalaya CLI for full IMAP/SMTP
Never mix approaches in same task - commit to one to avoid state conflicts

2. Apple Mail SQLite

Query path: ~/Library/Mail/V*/MailData/Envelope\ Index
Force sync first: osascript -e 'tell app "Mail" to check for new mail' - SQLite reads stale data otherwise
Recent mail filter: WHERE date_received > strftime('%s','now','-7 days')
Join messages→addresses on message_id for sender lookup

3. himalaya CLI

Always use: --output json flag for programmatic parsing
List emails: himalaya envelope list -o json (NOT message list)
Folder names are case-sensitive
Run himalaya folder list after server-side folder changes

4. Send Protocol

Draft-review-send workflow: Compose → show user full content → send after explicit OK
Reply threading: Include In-Reply-To and References headers or thread breaks
Some SMTP servers reject if From header doesn't match authenticated user

5. Credential Management

macOS Keychain: security add-internet-password -s imap.gmail.com -a user@gmail.com -w 'app-password'
Gmail/Google Workspace: Requires App Password with 2FA enabled
OAuth: himalaya supports XOAUTH2 via token_cmd in config.toml

6. Thread Intelligence

Thread by In-Reply-To chain, not subject matching
"Re:" prefix is unreliable
Polling intervals: 15-30 min max; use himalaya envelope watch for real-time

---name: maildescription: Execute email operations with platform-specific optimizations and secure credential handling.--- ## Requirements **Binaries:** - `himalaya` - IMAP/SMTP CLI (`brew install himalaya` or `cargo install himalaya`) - `osascript` - macOS only, built-in **Credentials:** - App Password for Gmail (not regular password), stored in macOS Keychain - Configure in `~/.config/himalaya/config.toml` ## Data Access **Read-only paths:** - `~/Library/Mail/V*/MailData/Envelope Index` - Apple Mail SQLite database (macOS only) - `~/Library/Mail/V*/MAILBOX/Messages/` - attachment files (macOS only) ## Scope This skill: - ✅ Reads email via himalaya CLI or Apple Mail SQLite - ✅ Sends email via himalaya (draft-review-send workflow) - ✅ Searches and filters messages - ❌ NEVER modifies credentials - ❌ NEVER deletes emails without explicit confirmation - ❌ NEVER auto-sends without user review ## Quick Reference | Topic | File | |-------|------| | Apple Mail SQLite queries | `apple-mail.md` | | himalaya CLI patterns | `himalaya.md` | | Send/reply protocol | `sending.md` | ## Core Rules ### 1. Platform Detection - **macOS with Apple Mail**: Use SQLite queries (100x faster than AppleScript) - **Cross-platform**: Use himalaya CLI for full IMAP/SMTP - **Never mix approaches** in same task - commit to one to avoid state conflicts ### 2. Apple Mail SQLite - Query path: `~/Library/Mail/V*/MailData/Envelope\ Index` - **Force sync first**: `osascript -e 'tell app "Mail" to check for new mail'` - SQLite reads stale data otherwise - Recent mail filter: `WHERE date_received > strftime('%s','now','-7 days')` - Join `messages→addresses` on `message_id` for sender lookup ### 3. himalaya CLI - **Always use**: `--output json` flag for programmatic parsing - List emails: `himalaya envelope list -o json` (NOT `message list`) - Folder names are case-sensitive - Run `himalaya folder list` after server-side folder changes ### 4. Send Protocol - **Draft-review-send workflow**: Compose → show user full content → send after explicit OK - Reply threading: Include `In-Reply-To` and `References` headers or thread breaks - Some SMTP servers reject if From header doesn't match authenticated user ### 5. Credential Management - macOS Keychain: `security add-internet-password -s imap.gmail.com -a user@gmail.com -w 'app-password'` - Gmail/Google Workspace: Requires App Password with 2FA enabled - OAuth: himalaya supports XOAUTH2 via token_cmd in config.toml ### 6. Thread Intelligence - Thread by `In-Reply-To` chain, not subject matching - "Re:" prefix is unreliable - Polling intervals: 15-30 min max; use `himalaya envelope watch` for real-time

Frequently asked questions

Mail