mac-automation

Mac Automation via AppleScript

This skill enables control of macOS applications and system functions through AppleScript execution via the osascript command.

Core Principle

Execute AppleScript commands using the Bash tool with osascript:

osascript -e 'AppleScript code here'

For multi-line scripts:

osascript <<'EOF'
tell application "App Name"
    -- commands here
end tell
EOF

Supported Applications & Functions

1. Mail

• Send emails with subject, body, recipients
• Read unread emails
• Search emails
• Create drafts

2. Reminders

• Create reminders with due dates
• List reminders by list
• Complete/delete reminders
• Create reminder lists

3. Calendar

• Create events with time, location, notes
• List today's/upcoming events
• Delete events
• Create calendars

4. Notification Center

• Display system notifications
• Custom title, subtitle, message
• Sound alerts

5. Safari

• Open URLs
• Get current page info
• Execute JavaScript
• Manage tabs and windows

6. Finder

• Open folders
• Get/set file info
• Move, copy, delete files
• Create folders
• Reveal files

7. System Controls

• Volume control (mute, set level)
• Brightness (via external tools)
• Open applications
• System info queries
• Sleep/restart/shutdown (with care)

8. Third-Party Applications

Many third-party apps support AppleScript. Common categories include development tools (iTerm2, VS Code), task management (OmniFocus, Things), media players (Spotify), browsers (Chrome), and communication tools. To check if an app supports AppleScript, open Script Editor to browse its dictionary, or try basic commands like tell application "AppName" to get name.

Execution Guidelines

Security Considerations

1. Permission Prompts: First-time use of certain apps triggers macOS permission dialogs. Inform user if automation fails due to permissions.

2. Sensitive Operations: For destructive operations (delete, shutdown), confirm with user before executing.

3. Privacy-Sensitive Data: When reading emails or calendar events, only display what user explicitly requests.

Error Handling

Common errors and solutions:

• "Application not found" → Check app name spelling
• "Not authorized" → Guide user to System Preferences > Privacy & Security
• "Can't get..." → Resource doesn't exist, handle gracefully

Best Practices

1. Use exact app names: "Mail", "Reminders", "Calendar", "Safari", "Finder"
2. Escape special characters: Use \" for quotes in strings
3. Handle Unicode: AppleScript handles Chinese/Unicode natively
4. Check app state: Some operations require app to be running

Quick Reference

Notifications

osascript -e 'display notification "消息内容" with title "标题"'

Open Application

osascript -e 'tell application "AppName" to activate'

Volume Control

# Get volume
osascript -e 'output volume of (get volume settings)'
# Set volume (0-100)
osascript -e 'set volume output volume 50'
# Mute
osascript -e 'set volume output muted true'

System Commands

# Get clipboard
osascript -e 'the clipboard'
# Set clipboard
osascript -e 'set the clipboard to "text"'

Additional Resources

Reference Files

For detailed AppleScript patterns by application, consult:

• references/mail-applescript.md - Email operations: send, read, search, drafts
• references/reminders-applescript.md - Reminder operations: create, list, complete
• references/calendar-applescript.md - Calendar operations: events, calendars
• references/safari-applescript.md - Safari operations: URLs, tabs, JavaScript
• references/finder-applescript.md - Finder operations: files, folders
• references/system-applescript.md - System controls: volume, apps, clipboard

Example Files

Working examples in examples/:

• daily-briefing.applescript - Get today's calendar and unread emails
• quick-note.applescript - Create reminder from clipboard

Utility Scripts

Scripts in scripts/:

• run-applescript.sh - Wrapper for safe AppleScript execution

Workflow Patterns

Pattern 1: Information Retrieval

1. Execute AppleScript to query data
2. Parse output
3. Present formatted results to user

Pattern 2: Action Execution

1. Confirm action with user if destructive
2. Execute AppleScript
3. Verify success
4. Report result

Pattern 3: Multi-App Automation

1. Chain multiple AppleScript calls
2. Pass data between calls using shell variables
3. Handle errors at each step

Common User Requests

User Request	Action
"Send email to xxx"	Use Mail to create and send
"Remind me tomorrow..."	Create Reminder with due date
"Add calendar event"	Create Calendar event
"Open xxx website"	Safari open URL
"Turn down the volume"	Set volume lower
"Show notification"	Display notification
"Open folder"	Finder reveal

Troubleshooting

If AppleScript fails:

1. Check app is installed
2. Verify permissions in System Preferences
3. Ensure app name is exact
4. Try running app manually first
5. Check for syntax errors in script

For permission issues, guide user to: System Preferences > Privacy & Security > Automation

Self-Improvement Protocol

When an AppleScript execution fails or produces unexpected results, follow this protocol to improve the skill's reference documentation:

1. Error Analysis

• Identify the root cause of the failure
• Determine if it's a code issue, permission issue, or conceptual misunderstanding
• Check if the error is reproducible

2. Reference File Review

• Locate the relevant reference file in references/ directory
• Review existing examples for similar patterns
• Identify if the error stems from incorrect or incomplete examples

3. Documentation Update

When you identify a fixable issue in the reference documentation:

For incorrect examples:

• Update the example code with the correct implementation
• Add inline comments explaining the fix
• Test the corrected code to verify it works

For missing edge cases:

• Add a new example demonstrating the correct approach
• Include explanatory comments about why this approach is needed

For common pitfalls:

• Add a "Common Pitfalls" or "Important Notes" section
• Document the error message users might encounter
• Explain the correct solution

4. Update Guidelines

Use the Edit tool to modify reference files:

Edit tool on: references/{app}-applescript.md
- Fix incorrect code examples
- Add warning notes for known issues
- Include error messages and solutions

5. Documentation Standards

When updating reference files, maintain:

• Clear, working code examples
• Inline comments for complex logic
• Error messages and their solutions
• Date-stamped notes for significant fixes

6. Version Tracking

After significant improvements:

• Update the version number in SKILL.md frontmatter
• Consider documenting major fixes in a changelog

This protocol ensures the skill continuously improves based on real-world usage and errors encountered.