macos-automation - SKILL.md Agent Skill

name: macos-automation description: Automate native macOS apps and system interactions via osascript (AppleScript) compatibility: "Designed for Vellum personal assistants" metadata: icon: assets/icon.svg emoji: "🍎" vellum: category: "system" display-name: "macOS Automation" activation-hints: - "Interacting with native macOS apps (Messages, Contacts, Calendar, Mail, Reminders, Music, Finder, etc.) via osascript" avoid-when: - "Tasks that can be done entirely in the sandbox or via CLI tools"

Use this skill to interact with native macOS apps and system-level features via osascript (AppleScript) through host_bash. Always prefer osascript over browser automation or computer-use for anything involving a native macOS app.

Supported Apps

Communication: Messages, Mail, Microsoft Outlook, FaceTime Contacts & Calendar: Contacts, Calendar, Reminders Notes & Writing: Notes, TextEdit, Pages, BBEdit, CotEditor Files: Finder, Path Finder Browsers: Safari, Google Chrome Music & Media: Music (iTunes), Spotify, VLC, Podcasts, TV Productivity: OmniFocus, Things 3, OmniOutliner, OmniPlan, OmniGraffle Office: Microsoft Word, Microsoft Excel, Numbers, Keynote Developer tools: Xcode, Terminal, iTerm2, Script Editor System: System Events (UI scripting for any app), System Settings Automation: Keyboard Maestro, Alfred, Automator Creative: Adobe Photoshop, Final Cut Pro

For any unlisted app, check scriptability first:

osascript -e 'tell application "AppName" to get name'

Examples

# Send an iMessage
osascript -e 'tell application "Messages" to send "Hello!" to buddy "user@example.com"'

# Look up a contact
osascript -e 'tell application "Contacts" to get {name, phones} of every person whose name contains "Marina"'

# Read upcoming calendar events
osascript -e 'tell application "Calendar" to get summary of every event of calendar "Home" whose start date > (current date)'

# Create a reminder
osascript -e 'tell application "Reminders" to make new reminder with properties {name:"Buy milk", due date:((current date) + 1 * hours)}'

# Send an email
osascript -e 'tell application "Mail" to send (make new outgoing message with properties {subject:"Hi", content:"Hello", visible:true})'

# Create a note
osascript -e 'tell application "Notes" to make new note at folder "Notes" with properties {body:"My note"}'

# Open a URL in Safari
osascript -e 'tell application "Safari" to open location "https://example.com"'

# Play/pause Music
osascript -e 'tell application "Music" to playpause'

# Display a system notification
osascript -e 'display notification "Done!" with title "Vellum"'

Tips

For multi-line scripts, write them to a .applescript file and run with osascript path/to/script.applescript
Use System Events for UI scripting apps that don't have their own AppleScript dictionary
AppleScript permissions are gated by macOS TCC - if a command fails with a permission error, use request_system_permission to prompt the user