Apple Shortcuts

Apple Shortcuts

Objective

Help the user list, run, inspect, design recipes for, and troubleshoot Apple Shortcuts on this Mac. Prefer the native shortcuts CLI and existing project scripts. Do not pretend the CLI can create or edit shortcut graphs.

Invocation

/apple-shortcuts

Cursor may also auto-attach when the request matches the description.

Scope

• Inventory shortcuts (shortcuts list)
• Run named shortcuts (shortcuts run "Name")
• Open a shortcut in the app (shortcuts view "Name")
• Sign .shortcut files for import (shortcuts sign)
• Map user intent → best existing shortcut or underlying zsh/AppleScript
• Write setup recipes the user can build in Shortcuts.app
• Relate Stream Deck / Spencer / AUTOGIO ops shortcuts to their scripts

Non-Goals

• Do not claim shortcuts create exists (it does not)
• Do not UI-automate Shortcuts.app to build graphs unless the user explicitly asks for UI automation
• Do not run interactive, destructive, or secret-related shortcuts without explicit confirmation
• Do not print or log API keys / tokens from shortcuts like API Key Saver
• Do not replace macos-health-check remediation policy — health reports stay read-only unless the user asks for fixes separately
• Do not write default dumps into ~/Reports/MacHealthOS/

Authorized Output

Usually no report file — answer in chat with commands and results.

Optional session note only if the user asks to log the run:

/Users/giovannini.eduardogmail.com/Reports/WorkSessions/shortcuts_<slug>_YYYY-MM-DD_HH-MM-SS.md

Follow output-policy.md for folder rules.

Safety Constraints

1. Confirm before run when the shortcut may change Focus, quit apps, clean files, change network/Home settings, print, or touch secrets:
   • Examples: CLEANUP, Clean, Quit_YouTube, Stop Distractions, Home and Away Settings, PRINT_FACTORY_PRINT_Fulo_Filo, API Key Saver, SD-Backup-Todays-Reports
2. Quote names exactly as returned by shortcuts list (spaces, em dashes —, hyphens, accents).
3. Prefer underlying scripts when a Shortcut is only a thin Run Shell Script wrapper — more reliable for agents and logs.
4. Never pass secrets on the command line in chat logs; use files/--input-path when the shortcut needs input.
5. On permission dialogs (Automation, Accessibility, Notes): tell the user to approve in System Settings; do not loop-spam the shortcut.

Consult Safety Policy when overlapping with other skills.

Required Inputs

Workflow

1. Discover

Refresh inventory (do not trust stale memory):

/usr/bin/shortcuts list

Or the helper:

"$HOME/.cursor/skills/apple-shortcuts/scripts/list-shortcuts.zsh"

If the user asks what a name does, open the app view (does not run it):

/usr/bin/shortcuts view "Exact Name"

Load references/library.md for known mappings on this machine. Reconcile with live shortcuts list — names drift (e.g. SD-Start-Workspace vs docs saying SD — Start Workspace).

2. Choose path

3. Run

/usr/bin/shortcuts run "Exact Name"

With input/output when needed:

/usr/bin/shortcuts run "Exact Name" \
  --input-path "/absolute/path/in.txt" \
  --output-path "/absolute/path/out.txt" \
  --output-type public.plain-text

Capture exit code. On failure: check name spelling via list, permissions, and whether the underlying app/CLI is installed (Spencer, Stream Deck scripts, etc.).

4. Report back

Short completion summary:

• Shortcut or script used (exact name/path)
• Exit status
• Side effects observed
• Next action (permissions, rename drift, recipe to create missing Shortcut)

Decision Guide (this machine)

Daily / workspace

Ops / network

Focus / productivity

See full catalog notes in references/library.md.

Creating or fixing Shortcuts (manual)

The agent cannot compile a new shortcut graph via CLI. When the user needs a new one:

1. Write a clear recipe: name, actions, shell body with absolute paths
2. Point to generators only when those projects exist on this Mac:
   • $HOME/Automation/stream-deck-operations/scripts/install-shortcuts.zsh (currently missing)
   • $HOME/Documents/GitHub/ipad-stream-deck-console Spencer install/paste scripts (currently missing)
   • Local desk restores: $HOME/Automation/spencer/restore_*.sh
3. After the user clicks Add Shortcut, verify:

/usr/bin/shortcuts list | grep -F 'expected-name'
/usr/bin/shortcuts run "expected-name"

4. Prefer SD- or SD — prefix for Stream Deck ops; never overwrite unrelated library shortcuts.

Signing an exported file:

/usr/bin/shortcuts sign --mode people-who-know-me \
  --input "/path/in.shortcut" \
  --output "/path/out.shortcut"

Troubleshooting

Examples

User: “Run my start workspace shortcut”

1. shortcuts list → confirm SD-Start-Workspace (or documented alias)
2. Confirm it is non-destructive
3. shortcuts run "SD-Start-Workspace" or run start-workspace.zsh
4. Report exit status

User: “Add a Shortcut that opens Reports”

1. Provide Shortcuts.app recipe (Open Folder → /Users/giovannini.eduardogmail.com/Reports)
2. Suggest name Open-Reports-Root
3. After user creates it, verify with list + run

User: “What Shortcuts do I have for Spencer?”

1. Run list helper
2. Filter CLEANUP / DESKTOP_COMMANDER / NOTEBOOKLM / START_MY_DAY / THINKING_WORKSPACE / PRINT_FACTORY…
3. Summarize table; do not run them unless asked

References

• CLI reference
• Library map (this Mac)
• Spencer local restores: /Users/giovannini.eduardogmail.com/Automation/spencer/
• Stream Deck ops (if restored): /Users/giovannini.eduardogmail.com/Automation/stream-deck-operations/
• iPad Stream Deck console (if restored): /Users/giovannini.eduardogmail.com/Documents/GitHub/ipad-stream-deck-console/