8.6 KiB
name, description, allowed-tools
| name | description | allowed-tools | ||||
|---|---|---|---|---|---|---|
| apple-productivity | Access macOS Apple productivity apps (Calendar, Contacts, Mail, Messages, Reminders) to read events, contacts, messages, and tasks. Use this when user needs to check calendar, look up contacts, read messages/emails, or query reminders. |
|
Apple Productivity Apps Skill
You have access to macOS native productivity apps through helper scripts installed in ~/bin/.
Available Helper Scripts
Calendar
calendar-list - List all available calendars
calendar-list
calendar-list -j # JSON output
calendar-events - Query events
calendar-events # Today's events (default)
calendar-events -d 2025-11-15 # Specific date
calendar-events -w # This week
calendar-events -r 2025-11-15 2025-11-20 # Date range
calendar-events -c "Work" # Filter by calendar
calendar-events -j # JSON output
calendar-add - Add new event (REQUIRES USER CONFIRMATION)
calendar-add -t "Meeting" -s 2025-11-15T14:00:00 -e 2025-11-15T15:00:00
calendar-add -t "Lunch" -s 2025-11-15T12:00:00 -e 2025-11-15T13:00:00 -l "Cafe" -c "Personal"
Important: ISO-8601 format required: YYYY-MM-DDTHH:MM:SS (24-hour time)
Contacts
contacts-search - Search contacts
contacts-search "Marie" # Search by name
contacts-search -v "Brandon" # Verbose (all details)
contacts-search -a # List all contacts
contacts-search -l 5 "Smith" # Limit to 5 results
contacts-search -j # JSON output
Searches: First name, last name, email, phone, company (case-insensitive)
mail-unread - Get unread mail (REQUIRES Mail.app RUNNING)
mail-unread # Last 24 hours (default)
mail-unread 6 # Last 6 hours
mail-unread -d 3 # Last 3 days
mail-unread -l 5 # Limit to 5 messages
mail-unread -j # JSON output
Exit code 1 = Mail.app not running (tell user to open Mail.app)
Messages
imessage-recent - Get recent iMessages (SQLite direct access)
imessage-recent # Last 24 hours (default)
imessage-recent 6 # Last 6 hours
imessage-recent -d 3 # Last 3 days
imessage-recent -l 10 # Limit to 10 messages
imessage-recent -p "lunch" # Filter by keyword
imessage-recent -n # Check for notation patterns
imessage-recent -j # JSON output
Note: Works even when Messages.app is NOT running (direct SQLite access)
Notation patterns checked (-n flag):
(ghsj→cc:,(ghsj:,(cc→ghsj:,(cc-suggest:,(cc-warn:>>move:,>>archive,>>defer:[MUST],[SHOULD]
imessage-search - Advanced iMessage search with full message history (SQLite + attributedBody decoding)
imessage-search --felicitations # Find birthday/holiday/congrats messages
imessage-search --pattern "lunch" # Search for custom keyword
imessage-search --keywords "meeting,call" # Multiple keywords (comma-separated)
imessage-search --felicitations -l 10 # Limit to 10 contacts
imessage-search --pattern "resume" --csv # CSV output
imessage-search --felicitations -o ~/Desktop/contacts.csv # Save to file
Key Features:
- Searches complete message history (not just recent messages)
- Decodes modern iMessage
attributedBodyBLOB format (binary plist) - Groups results by contact with message counts and dates
- Auto-installs dependencies on first run (creates venv with biplist)
- Supports JSON, CSV, and human-readable output formats
Use Cases:
- Find contacts you've sent felicitation messages to (birthdays, holidays, congratulations)
- Search historical messages for specific keywords or topics
- Build contact lists for holiday greetings
- Analyze message patterns over time
Note: First run takes ~10s to setup virtual environment and install dependencies. Subsequent runs are fast.
Reminders
reminders-list - Query reminders
reminders-list # Incomplete reminders (default)
reminders-list -a # All reminders
reminders-list -c # Only completed
reminders-list -d # Due today
reminders-list -o # Overdue
reminders-list -l "Work" # Filter by list name
reminders-list -l "Work" -d # Work reminders due today
reminders-list --limit 20 # Limit results
reminders-list -j # JSON output
Warning: Large queries can timeout (10s limit). Use -l to filter by specific list if needed.
Common Patterns
Morning Context Check
# Today's schedule
calendar-events --today
# Pending tasks
reminders-list -o # Overdue
reminders-list -d # Due today
# Unread communications
mail-unread
imessage-recent -n # Check for notation patterns
Contact Lookup
# Quick lookup
contacts-search "Marie"
# Full details
contacts-search -v "Brandon"
# Find someone by company
contacts-search "Best Buy"
Message Search
# Recent messages about specific topic
imessage-recent -p "resume"
# Check for user directives
imessage-recent -n
# Historical search across all messages
imessage-search --pattern "resume"
# Find contacts for holiday greetings
imessage-search --felicitations --csv -o ~/Desktop/thanksgiving-contacts.csv
Security & Privacy
READ-ONLY (Safe - No Confirmation Needed)
- ✅ Viewing calendar events
- ✅ Looking up contacts
- ✅ Checking unread mail counts/subjects
- ✅ Reading recent iMessages (
imessage-recent) - ✅ Searching historical iMessages (
imessage-search) - ✅ Querying reminder status
WRITE OPERATIONS (ALWAYS Ask User First)
- ❌ Creating/modifying calendar events (
calendar-add) - ❌ Creating/modifying contacts
- ❌ Sending emails
- ❌ Sending iMessages
- ❌ Creating/modifying reminders
Rule: ALWAYS use AskUserQuestion tool before ANY write operation.
Error Handling
Mail Not Running
$ mail-unread
Error: Mail.app not running
Please open Mail.app before running this command
# Exit code: 1
Response: Tell user to open Mail.app, then retry.
Calendar Timeout
$ calendar-events -r 2020-01-01 2025-12-31
Error: Query timed out after 10s
Try a smaller date range or check if Calendar.app is responsive
# Exit code: 3
Response: Use smaller date range (days/weeks, not years).
No Results
All scripts handle "no results" gracefully:
$ calendar-events
No events found for 2025-11-15
Examples
User: "What's on my calendar today?"
calendar-events --today
Parse output and summarize for user.
User: "What's Brandon's phone number?"
contacts-search "Brandon"
Extract phone number from output.
User: "Any unread emails from Marie?"
First check if Mail.app is running:
mail-unread -l 20
Then filter output for "Marie" in sender field.
User: "Show my overdue reminders"
reminders-list -o
Present list to user with due dates.
User: "When is Eileen's birthday?"
contacts-search -v "Eileen"
Look for "Birthday:" in verbose output.
User: "Create a calendar event for lunch tomorrow at noon"
- Calculate tomorrow's date
- Format as ISO-8601:
2025-11-16T12:00:00 - ASK USER FOR CONFIRMATION using
AskUserQuestion - If confirmed:
calendar-add -t "Lunch" -s 2025-11-16T12:00:00 -e 2025-11-16T13:00:00
Limitations
- Mail: Requires Mail.app to be running
- Calendar: Large date ranges (years) may timeout - use smaller ranges
- Reminders: Large lists may timeout - filter by specific list
- Messages:
imessage-recent: Only searches messages with plain text field (~70 messages) - fast but limitedimessage-search: Searches complete history by decoding attributedBody BLOBs - comprehensive but slower- Sending messages requires user interaction (read-only access)
- Contacts: ~700 contacts can be slow to enumerate - use specific searches
Tips
- Always check exit codes - Non-zero = error
- Use JSON output (
-j) for complex parsing - Limit results when possible to avoid timeouts
- Filter early - Use script options rather than parsing large outputs
- Batch operations - Run multiple independent queries in parallel with multiple Bash tool calls
Related Skills
apple-health-fitness- Health and Fitness dataapple-shortcuts- Run macOS Shortcuts
Remember: This skill gives you READ access to personal productivity data. ALWAYS ask before WRITING any data.