gh-g-shudy-claude-plugins-plugins-macos-apple-apps/skills/apple-shortcuts/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
apple-shortcuts	Run user-defined macOS Shortcuts for custom automation workflows. Use when user wants to trigger a Shortcut by name or execute a custom automation.	Bash AskUserQuestion

Apple Shortcuts Skill

Run user-defined macOS Shortcuts through Claude Code.

Overview

macOS includes the Shortcuts app for creating custom automation workflows. This skill allows Claude to trigger those Shortcuts via the shortcuts command-line tool.

The shortcuts Command

macOS provides a built-in CLI tool for running Shortcuts:

# List all available shortcuts
shortcuts list

# Run a shortcut by name
shortcuts run "Shortcut Name"

# Run with input
shortcuts run "Shortcut Name" --input-path /path/to/file

# Get shortcut details
shortcuts view "Shortcut Name"

# Sign shortcuts for automation (one-time setup)
shortcuts sign --mode people-who-know-me "Shortcut Name"

Usage Pattern

1. List Available Shortcuts

shortcuts list

This shows all Shortcuts the user has created. Present this list to the user if they ask "What shortcuts do I have?"

2. Run a Shortcut (REQUIRES USER CONFIRMATION)

Always ask user before running a shortcut using AskUserQuestion tool.

shortcuts run "Morning Routine"

3. View Shortcut Details

shortcuts view "Backup Photos"

Shows what the shortcut does (if the user wants to verify before running).

Common Use Cases

User: "What shortcuts do I have?"

shortcuts list

Present the list formatted nicely.

User: "Run my morning routine shortcut"

1. First, list shortcuts to find exact name:

shortcuts list

2. Then, ask user for confirmation: "I found the shortcut 'Morning Routine'. This shortcut will:

• [describe what it does if possible]

Should I run it?"

3. If confirmed, run it:

shortcuts run "Morning Routine"

User: "Create a shortcut to..."

Response: "I can't create Shortcuts directly. You'll need to create it in the Shortcuts app, then I can run it for you. Would you like me to explain how to create it?"

Security & Privacy

ALWAYS REQUIRE CONFIRMATION

Shortcuts can do anything - file operations, network requests, app automation, etc.

Rule: NEVER run a shortcut without explicit user confirmation.

What to Ask Before Running

1. "Which shortcut do you want to run?" (verify exact name)
2. Show what it does (if possible via shortcuts view)
3. "Should I run this now?"

Signing Shortcuts

Some shortcuts may need to be signed for automation:

shortcuts sign --mode people-who-know-me "Shortcut Name"

If a shortcut fails with a signing error, tell the user: "This shortcut needs to be signed for automation. Run this in Terminal: shortcuts sign --mode people-who-know-me \"Shortcut Name\""

Examples

Example 1: Morning Routine

User has a "Morning Routine" shortcut that:

• Sets Focus mode
• Adjusts display brightness
• Opens specific apps
• Reads calendar

shortcuts run "Morning Routine"

Example 2: Export Photos

User has "Export Photos" shortcut that exports recent photos to a folder:

shortcuts run "Export Photos"

May require input path:

shortcuts run "Export Photos" --input-path ~/Desktop/

Example 3: Backup Workflow

User has "Backup to NAS" shortcut:

shortcuts run "Backup to NAS"

Integration with Other Skills

Shortcuts can complement other Apple app integrations:

Calendar → Shortcuts

• User creates Calendar event via apple-productivity skill
• Then triggers "Sync Calendar" shortcut to sync with external service

Health → Shortcuts

• Trigger "Export Health Data" shortcut
• Then query exported data with apple-health-fitness skill

Contacts → Shortcuts

• Lookup contact with apple-productivity skill
• Trigger "Send Birthday Reminder" shortcut for that contact

Limitations

Cannot Create Shortcuts

Claude cannot create or modify Shortcuts - only run existing ones. Shortcuts must be created by the user in the Shortcuts app.

No Direct Shortcut Editing

Cannot view internal structure of shortcuts (they're binary files). Can only run them.

Shortcut Permissions

Shortcuts may require permissions (Automation, Files, etc.). User must grant these in System Settings.

Input/Output

• Simple text input/output works well
• File input via --input-path
• Complex data structures may be tricky

Shortcut Ideas for Users

Suggest these shortcuts users could create:

Productivity

• Morning/Evening routines
• Focus mode triggers
• Calendar sync workflows
• Email templates

File Management

• Backup workflows
• Photo organization
• Document conversion
• File compression/archiving

Health & Fitness

• Export health data
• Log workouts
• Meal tracking
• Sleep analysis

Communication

• Send templated messages
• Email batches
• Social media posts
• Contact management

Development

• Git workflows
• Build/deploy automation
• Test runners
• Environment setup

Troubleshooting

"Shortcut not found"

shortcuts list

Get exact name (case-sensitive, spaces matter).

"Signing error"

shortcuts sign --mode people-who-know-me "Shortcut Name"

Or tell user to open Shortcuts app → Settings → Advanced → Allow Running Scripts

"Permission denied"

Shortcut needs permissions. User must grant in: System Settings → Privacy & Security → Automation

Resources

• Shortcuts User Guide: https://support.apple.com/guide/shortcuts-mac/
• Command-line Tool: Run man shortcuts for details
• Gallery: Open Shortcuts app → Gallery for inspiration

Related Skills

• apple-productivity - Calendar, Contacts, Mail, Messages, Reminders
• apple-health-fitness - Health and Fitness data

---

Remember: Shortcuts are powerful and potentially destructive. ALWAYS confirm with user before running any shortcut.