apple-shortcuts

name	apple-shortcuts
description	Generate importable Apple Shortcuts (.shortcut / plist XML) for macOS and iOS. Use this skill whenever the user wants to create, modify, reverse-engineer, or understand Apple Shortcuts, including native actions, third-party app integrations (Actions, Data Jar, Toolbox Pro, Scriptable, a-Shell, Jayson, Pushcut), automations, and complex control flow. Trigger on mentions of "shortcut", "raccourci", "workflow iOS/macOS", ".shortcut file", "Apple automation", or any request to produce a file the user can import into the Shortcuts app.
metadata	{"version":"1.0.0"}

Apple Shortcuts

Generate plist XML that the Shortcuts app imports. Targets macOS 12+ and iOS 15+. Use this skill for creation, modification, reverse engineering, and reference lookups.

Critical upfront fact: signing

Since iOS 15 / macOS 12, Shortcuts refuses unsigned files. This skill produces plist XML. Delivery to the user requires one of:

1. macOS 12+: run shortcuts sign -i in.plist -o out.shortcut -m anyone to produce a distributable .shortcut. The user double-clicks or runs open -a Shortcuts out.shortcut.
2. macOS, manual route: open the plist in Shortcuts.app (rename to .shortcut first), re-save — Shortcuts re-signs it.
3. iOS, no signing toolchain: the user must receive a signed .shortcut via iCloud share link (https://www.icloud.com/ shortcuts/...), AirDrop, or Messages. Unsigned plist XML cannot be imported on iOS.

State this cost to the user before generating. If they lack macOS, the deliverable is XML plus instructions; full binary signing without macOS is a rabbit hole this skill does not enter.

See gotchas/signing-and-sharing.md for the full story.

Quickstart (three steps)

1. Identify the action set

If you know the action by name but not its identifier:

./tools/find-action-identifier.py "send message"

If you need to discover an unknown third-party action on macOS:

./tools/list-app-intents.py --bundle com.example.app

If you need the full native action catalog:

./tools/list-native-actions.py

2. Generate the plist

Consult references in this order:

• references/plist-format.md for the envelope and top-level keys.
• references/variables-and-types.md for magic variable wiring.
• references/actions-native-*.md for concrete action schemas.
• patterns/*.md if the task matches a known pattern.
• templates/*.plist as starting points.

Write the plist as XML. Every action dict must carry at minimum WFWorkflowActionIdentifier and WFWorkflowActionParameters.

3. Validate and deliver

./tools/validate-shortcut.py path/to/shortcut.plist

Fix any errors. Then either sign on macOS or instruct the user to.

Progressive disclosure table

Load only the files your current task needs. This table maps request types to files.

Request contains	Load
"how do I make a shortcut that..."	patterns/ + relevant actions-*.md
"what's the identifier for X action"	actions-native-full-index.md or find
"why won't my shortcut import"	gotchas/signing-and-sharing.md
"what does this .shortcut file do"	tools/inspect-shortcut.py
"call an API / fetch JSON"	patterns/http-api-calls.md
"show a menu to the user"	patterns/user-input.md
"run another shortcut"	patterns/shortcuts-chaining.md
"personal automation / trigger"	patterns/automation-triggers.md
"use action"	third-party/<app>.md
"variables aren't working"	references/variables-and-types.md
"compare two shortcuts"	tools/diff-actions.py
"what actions are in WorkflowKit"	tools/list-native-actions.py

Canonical generation workflow

1. Detect target platform. iOS-only, macOS-only, or cross-platform shapes the action set. Shell Script, AppleScript, JXA, and window management are macOS-only. Health, HomeKit scene execution, and camera actions are iOS-only.
2. Resolve identifiers. Every action string must be real. If an identifier is unverified, mark it ⚠ unverified in your plan and prefer a verified alternative.
3. Load references. Pull in only the specific references/*.md and third-party/*.md you need. Do not eagerly load the full catalog.
4. Generate the plist. Emit the XML envelope, icon dict, WFWorkflowActions array. Assign a UUID to every action whose output is referenced later. Wire magic variables via attachmentsByRange using {position, length} strings and the U+FFFC object replacement character (see references/variables-and-types.md).
5. Validate. Run tools/validate-shortcut.py. Do not skip this step.
6. Deliver with import instructions. Provide the three import paths (macOS CLI, macOS GUI, iOS), noting the signing requirement explicitly.

Minimum viable plist shape

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>WFWorkflowClientVersion</key>
  <string>2607.0.3</string>
  <key>WFWorkflowMinimumClientVersion</key>
  <integer>900</integer>
  <key>WFWorkflowMinimumClientVersionString</key>
  <string>900</string>
  <key>WFWorkflowIcon</key>
  <dict>
    <key>WFWorkflowIconGlyphNumber</key>
    <integer>59511</integer>
    <key>WFWorkflowIconStartColor</key>
    <integer>463140863</integer>
  </dict>
  <key>WFWorkflowImportQuestions</key>
  <array/>
  <key>WFWorkflowInputContentItemClasses</key>
  <array>
    <string>WFStringContentItem</string>
  </array>
  <key>WFWorkflowTypes</key>
  <array/>
  <key>WFWorkflowActions</key>
  <array>
    <dict>
      <key>WFWorkflowActionIdentifier</key>
      <string>is.workflow.actions.gettext</string>
      <key>WFWorkflowActionParameters</key>
      <dict>
        <key>WFTextActionText</key>
        <string>Hello from Claude</string>
      </dict>
    </dict>
    <dict>
      <key>WFWorkflowActionIdentifier</key>
      <string>is.workflow.actions.showresult</string>
      <key>WFWorkflowActionParameters</key>
      <dict>
        <key>Text</key>
        <string>Hello from Claude</string>
      </dict>
    </dict>
  </array>
</dict>
</plist>

This is templates/minimal-shortcut.plist. It imports after signing.

Import methods (three paths)

macOS, CLI (requires macOS 12+)

# Save plist with .shortcut extension
mv out.plist out.shortcut

# Sign it for public sharing
shortcuts sign -i out.shortcut -o out.signed.shortcut -m anyone

# Open in Shortcuts.app to complete import
open -a Shortcuts out.signed.shortcut

Signing modes:

• anyone — distributable via any channel; lax trust.
• people-who-know-me — requires recipient to be in Contacts.

macOS, drag and drop

mv out.plist out.shortcut
open -a Shortcuts out.shortcut

Shortcuts.app imports, signs locally, and stores in ~/Library/Shortcuts/.

iOS, iCloud / AirDrop

There is no iOS signing toolchain. The user must receive a shortcut that was signed on macOS. Paths:

• iCloud share link — sign on macOS, upload to iCloud, share the https://www.icloud.com/shortcuts/<uuid> link. Recipient taps link, Shortcuts opens.
• AirDrop a signed .shortcut file from macOS to iOS.
• Email / Messages attachment of a signed .shortcut file.

If the user is iOS-only and has no macOS device, the skill cannot fully close the loop. Deliver the plist XML and document the gap.

Reference files inventory

• references/plist-format.md — envelope, top-level keys, content item classes, XML rules.
• references/variables-and-types.md — magic variables, attachmentsByRange, serialization types, coercion.
• references/control-flow.md — If, Repeat, Choose from Menu, GroupingIdentifier, WFControlFlowMode.
• references/actions-native-core.md — Text, Dictionary, List, Variables, Scripting, Device.
• references/actions-native-web.md — URL, Get Contents of URL, JSON parsing, headers, authentication.
• references/actions-native-files.md — Files, Photos, Documents, archive, hash.
• references/actions-native-communication.md — Messages, Mail, Notifications, Speak Text.
• references/actions-native-automation.md — Automations, triggers, focus, personal vs home.
• references/actions-native-full-index.md — Flat identifier index, fallback lookup.

Third-party catalog

• third-party/actions-app.md — Sindre Sorhus's Actions (OSS, free, covers ~80% of gaps).
• third-party/data-jar.md — Simon Støvring's persistent key-value store.
• third-party/toolbox-pro.md — Alex Hay's advanced utilities.
• third-party/scriptable.md — JavaScript bridge.
• third-party/a-shell.md — iOS shell bridge.
• third-party/jayson.md — JSON manipulation.
• third-party/pushcut.md — Automation server, webhooks.
• third-party/discovery-pattern.md — Reverse engineer any unknown third-party app's actions.

Patterns

• patterns/http-api-calls.md — REST calls, auth headers, pagination.
• patterns/json-parsing.md — Dictionary access, Get Dictionary Value.
• patterns/error-handling.md — Exit, fallback, validation.
• patterns/user-input.md — Ask, Choose from Menu, Show Alert.
• patterns/shortcuts-chaining.md — Run Shortcut with parameters, output passing.
• patterns/automation-triggers.md — Personal automation, Home, limits, confirmation.

Gotchas

• gotchas/platform-differences.md — iOS vs macOS vs watchOS action availability.
• gotchas/signing-and-sharing.md — iOS 15+ signing requirement, share links, trust prompts.
• gotchas/common-pitfalls.md — Variable scope, UUID duplicates, magic variable binding bugs.
• gotchas/performance.md — Action limits, timeouts, Get Contents of URL failure modes.

Tools

• tools/validate-shortcut.py — Validate a plist. Check syntax, required keys, identifier existence, variable referencing.
• tools/inspect-shortcut.py — Dump a .shortcut or .plist as structured JSON or human-readable list.
• tools/list-native-actions.py — Extract WFWorkflowActionIdentifier values from WorkflowKit.framework (macOS) or fall back to embedded index.
• tools/list-app-intents.py — Scan installed apps for App Intents metadata and enumerate their Shortcuts actions.
• tools/find-action-identifier.py — Fuzzy search for an action by name across native and known third-party catalogs.
• tools/diff-actions.py — Semantic diff between two shortcuts (action-by-action, reorder-aware).
• tools/README.md — Script inventory, usage examples, exit codes.

Hard rules

• No invention. If an identifier, parameter key, or version number is not verified, mark it ⚠ unverified in output and suggest the user confirm via tools/list-native-actions.py or by round-tripping through Shortcuts.app.
• One source of truth per fact. Identifier strings live in actions-native-full-index.md and third-party/*.md; prose references link there rather than re-state.
• Templates are importable. Every file in templates/ passes plutil -lint and tools/validate-shortcut.py.
• English-only in code and documentation. User-facing prose in chat may be in the user's language; files in this skill are English.

When the request is ambiguous

Before generating, resolve:

1. Target platform — iOS only, macOS only, or both.
2. Trigger — manual run, share sheet, personal automation, Home automation, menu bar (macOS).
3. Input — no input, Shortcut Input, explicit prompt (Ask for Input).
4. Output — none, Show Result, Quick Look, return to caller.
5. Third-party dependencies — any action outside is.workflow.actions.*?

Do not guess. Ask the user for any of the five that remain unclear after reading the request.