/macos-tools

name: macos-tools
description: "macOS native integrations: screen capture, calendar, reminders, contacts, email (Mail.app), Spotlight search. Use when the user asks about their screen, schedule, to-do list, contacts, or wants to send email on macOS."

macOS Tools

Native macOS integrations via AppleScript. No API keys needed — works on any Mac.

When to Use

• **Screen**: "What's on my screen?", "help me with this", "describe what I'm looking at"
• **Calendar**: "What's on my schedule?", "do I have meetings today?"
• **Reminders**: "Add a reminder", "what's on my todo list?", "mark X as done"
• **Contacts**: "What's Bob's email?", "find contact for..."
• **Email**: "Send an email to...", "draft a message to..."
• **File search**: "Find my resume", "where's that PDF?"

Tools

Screen Capture

bash "$SKILL_DIR/scripts/screen-capture.sh"

Returns path to PNG screenshot. Use the Read tool on the path to view it.

Calendar

Prefer the `google-calendar` skill if installed. Fallback to macOS Calendar:

python3 "$SKILL_DIR/scripts/calendar-reader.py" 7          # next 7 days, JSON
python3 "$SKILL_DIR/scripts/calendar-reader.py" 1 text     # today, plain text

Reminders

python3 "$SKILL_DIR/scripts/reminders.py" list              # all incomplete
python3 "$SKILL_DIR/scripts/reminders.py" add "Call Bob"     # add reminder
python3 "$SKILL_DIR/scripts/reminders.py" add "Fix bug" "2026-03-17"  # with due date
python3 "$SKILL_DIR/scripts/reminders.py" complete "Call Bob" # mark done

Contacts

python3 "$SKILL_DIR/scripts/contacts.py" search "Bob"       # find by name

Returns name, emails, phones. Use before sending email to resolve names to addresses.

Email (Apple Mail)

python3 "$SKILL_DIR/scripts/email-sender.py" "to@example.com" "Subject" "Body"
python3 "$SKILL_DIR/scripts/email-sender.py" "to@example.com" "Subject" "Body" --draft

Sends via Mail.app. Use `--draft` to create without sending. **Always confirm with user before sending.**

Spotlight File Search

mdfind "quarterly report"                    # search by content or filename
mdfind -name "resume.pdf"                    # search by filename only

Requirements

• macOS (uses AppleScript)
• Calendar, Reminders, Contacts, Mail apps (built into macOS)
• Grant Accessibility permissions if prompted