Mail

Execute email operations with platform-specific optimizations and secure credential handling.

Security Scan

The skill's requirements and instructions are coherent with an email client helper: it expects the himalaya CLI (and macOS tooling when on Darwin) and describes reading mail stores and using Keychain/IMAP credentials — but there are a few operational and privacy cautions you should review before installing.

Purpose & Capability

Name/description match the implementation: the skill is an instruction-only mail helper that uses himalaya for IMAP/SMTP and Apple Mail SQLite on macOS. Requested binaries and file access are consistent with reading and sending email.

Instruction Scope

Instructions explicitly tell the agent to read Apple Mail SQLite files and attachment directories (sensitive personal data) and to call himalaya/osascript. That is appropriate for an email helper, but the docs also include example commands that place credentials on the shell command line (e.g., security add-internet-password -w 'app-password'), which can expose secrets via shell history or process lists. The skill states 'NEVER auto-send' and a draft-review-send flow, which is good, but enforcement depends on the host agent following these instructions.

Install Mechanism

No install spec / no code files — instruction-only skill. This minimizes supply-chain risk (nothing is downloaded or written by the skill itself). The skill expects the user to install himalaya from known sources (brew/cargo).

Credentials

No environment variables or remote credentials are declared in registry metadata; the skill relies on local credentials: macOS Keychain and ~/.config/himalaya/config.toml (or XOAUTH2 token_cmd). These are proportionate to email functionality. However, the documentation demonstrates insecure CLI usage that can leak credentials (passing app-password in -w). The registry metadata omits osascript as a required binary even though SKILL.md references it for macOS; minor metadata inconsistency.

Persistence & Privilege

always is false and the skill does not request persistent system-wide modifications. It does instruct storing credentials into Keychain/config files (normal for mail clients) but does not request elevated or cross-skill privileges.

Assessment

This skill appears to be what it says — an instruction-only mail helper that uses himalaya and (on macOS) Apple Mail data. Before installing: 1) Accept that the agent will read email content and attachments if you allow it — this is necessary for the feature. 2) Prefer Keychain usage or XOAUTH2; do not paste raw passwords on command lines (examples in the docs show -w 'app-password' which can leak to shell history/process lists). 3) Install himalaya from a trusted source (brew or the official crate). 4) Confirm the agent will adhere to the draft-review-send workflow (the skill says it will not auto-send, but autonomous agent behavior depends on the platform). 5) Note the small metadata inconsistency (osascript mentioned in docs but not declared as required binary) — verify macOS-only behavior if you run on Linux. If you need higher assurance, ask the skill author to remove insecure example commands and to declare Keychain/OAuth requirements explicitly in metadata.

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 [e-mail] -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