310 lines
8.6 KiB
Markdown
310 lines
8.6 KiB
Markdown
---
|
|
name: apple-productivity
|
|
description: 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.
|
|
allowed-tools:
|
|
- Bash
|
|
- Read
|
|
- Write
|
|
- AskUserQuestion
|
|
---
|
|
|
|
# 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
|
|
```bash
|
|
calendar-list
|
|
calendar-list -j # JSON output
|
|
```
|
|
|
|
**`calendar-events`** - Query events
|
|
```bash
|
|
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)
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
|
|
**`mail-unread`** - Get unread mail (REQUIRES Mail.app RUNNING)
|
|
```bash
|
|
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)
|
|
```bash
|
|
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)
|
|
```bash
|
|
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 `attributedBody` BLOB 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
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Quick lookup
|
|
contacts-search "Marie"
|
|
|
|
# Full details
|
|
contacts-search -v "Brandon"
|
|
|
|
# Find someone by company
|
|
contacts-search "Best Buy"
|
|
```
|
|
|
|
### Message Search
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
$ 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
|
|
|
|
```bash
|
|
$ 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:
|
|
```bash
|
|
$ calendar-events
|
|
No events found for 2025-11-15
|
|
```
|
|
|
|
## Examples
|
|
|
|
### User: "What's on my calendar today?"
|
|
|
|
```bash
|
|
calendar-events --today
|
|
```
|
|
|
|
Parse output and summarize for user.
|
|
|
|
### User: "What's Brandon's phone number?"
|
|
|
|
```bash
|
|
contacts-search "Brandon"
|
|
```
|
|
|
|
Extract phone number from output.
|
|
|
|
### User: "Any unread emails from Marie?"
|
|
|
|
First check if Mail.app is running:
|
|
```bash
|
|
mail-unread -l 20
|
|
```
|
|
|
|
Then filter output for "Marie" in sender field.
|
|
|
|
### User: "Show my overdue reminders"
|
|
|
|
```bash
|
|
reminders-list -o
|
|
```
|
|
|
|
Present list to user with due dates.
|
|
|
|
### User: "When is Eileen's birthday?"
|
|
|
|
```bash
|
|
contacts-search -v "Eileen"
|
|
```
|
|
|
|
Look for "Birthday:" in verbose output.
|
|
|
|
### User: "Create a calendar event for lunch tomorrow at noon"
|
|
|
|
1. Calculate tomorrow's date
|
|
2. Format as ISO-8601: `2025-11-16T12:00:00`
|
|
3. **ASK USER FOR CONFIRMATION** using `AskUserQuestion`
|
|
4. If confirmed:
|
|
```bash
|
|
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 limited
|
|
- `imessage-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
|
|
|
|
1. **Always check exit codes** - Non-zero = error
|
|
2. **Use JSON output** (`-j`) for complex parsing
|
|
3. **Limit results** when possible to avoid timeouts
|
|
4. **Filter early** - Use script options rather than parsing large outputs
|
|
5. **Batch operations** - Run multiple independent queries in parallel with multiple Bash tool calls
|
|
|
|
## Related Skills
|
|
|
|
- `apple-health-fitness` - Health and Fitness data
|
|
- `apple-shortcuts` - Run macOS Shortcuts
|
|
|
|
---
|
|
|
|
**Remember**: This skill gives you READ access to personal productivity data. ALWAYS ask before WRITING any data.
|