/shortcuts-playground

name: shortcuts-playground
description: Build, validate, sign, archive, and REMIX macOS/iOS Shortcuts by creating plist files. Use when asked to create, modify, or remix shortcuts; automate workflows; build .shortcut files; or generate Shortcuts plists. Covers WF actions, AppIntents, third-party actions, variable references, and control flow using bundled target-gated ToolKit snapshots.
effort: max
allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Shortcuts Playground

Generate valid `.shortcut` files that can be signed and imported into Apple's Shortcuts app. The plugin supports two workflows — building new shortcuts from scratch AND remixing existing XML shortcuts with a natural-language diff.

**Two slash commands / two specialized agents:**

| Command | Agent | Purpose | |---------|-------|---------| | `/shortcuts-playground:build <brief>` | `shortcut-builder` | Create a new shortcut from scratch based on a natural-language brief. | | `/shortcuts-playground:remix <path-to-xml> <idea>` | `shortcut-remixer` | Apply a surgical diff to an existing unsigned `.xml` shortcut. Preserves UUIDs, icon, metadata, and every action the user didn't ask to touch. |

Both commands share the same skill docs, the same validator, the same `PostToolUse` auto-validation hook, and the same `sign-shortcut` archive-and-sign pipeline. The only difference is the starting point (empty plist vs. an existing source XML).

**Plugin-provided commands.** When this skill is active, three wrapper commands are on the Bash `PATH`:

| Command | Purpose | |---------|---------| | `resolve-icon` | Pick a Shortcuts glyph + color from a natural-language prompt (required step 5 in the build workflow; skipped for remixes, which preserve the source icon). | | `validate-shortcut` | Run the Craig Loop preflight validator against a `.xml`/`.shortcut` file. | | `sign-shortcut` | Archive the unsigned XML, sign with `shortcuts sign`, and write the final `.shortcut` to the configured output directory. |

Prefer these wrappers over calling the underlying `python3 scripts/*.py` files directly — they work from any working directory and respect plugin configuration.

**Auto-validation hook.** A `PostToolUse` hook fires on every `Write`/`Edit` that produces a Shortcuts plist file and runs `validate-shortcut` automatically. Do not skip the Craig Loop when the hook reports errors — it already ran the validator for you, so read the errors and fix them before retrying. The hook applies to BOTH the builder and the remixer; neither agent needs to invoke `validate-shortcut` manually for edits it just made.

**Mandatory**: Follow the guidelines in [BEST_PRACTICES.md](BEST_PRACTICES.md) for every shortcut. If guidance here conflicts with [BEST_PRACTICES.md](BEST_PRACTICES.md), follow `BEST_PRACTICES.md`.

**Definition of done**: a new build is not complete when XML validation passes. It is complete only after `sign-shortcut` archives the unsigned XML, writes the signed `.shortcut`, and you verify the signed file exists with non-zero size.

**Pipeline-first rule**: write the smallest complete shortcut that implements the request, validate it, sign it, and verify the signed file before spending turns on cosmetic polish. Comments only need to be concise and repair-oriented. A valid XML draft without a signed `.shortcut` is not a useful stopping point.

Recommended Reading Order

1. [BEST_PRACTICES.md](BEST_PRACTICES.md) for mandatory rules and validation expectations 2. [PLIST_FORMAT.md](PLIST_FORMAT.md) for plist structure and serialization details 3. [ACTIONS.md](ACTIONS.md), [APPINTENTS.md](APPINTENTS.md), [AUTOMATION_TRIGGERS.md](AUTOMATION_TRIGGERS.md), and [THIRD_PARTY_ACTIONS.md](THIRD_PARTY_ACTIONS.md) for action IDs, AppIntent parameters, and OS 27 trigger metadata 4. [HEALTHKIT.md](HEALTHKIT.md) when building or remixing Health actions 5. [VARIABLES.md](VARIABLES.md), [CONTROL_FLOW.md](CONTROL_FLOW.md), and [FILTERS.md](FILTERS.md) for wiring patterns 6. [ICONS_AND_COLORS.md](ICONS_AND_COLORS.md), [PARAMETER_TYPES.md](PARAMETER_TYPES.md), and [EXAMPLES.md](EXAMPLES.md) for implementation details

Quick Start

A shortcut is an XML plist that gets signed into a binary package. Generate the XML form:

<?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>WFWorkflowActions</key>
    <array>
        <!-- Actions go here -->
    </array>
    <key>WFWorkflowClientVersion</key>
    <string>2700.0.4</string>
    <key>WFWorkflowHasOutputFallback</key>
    <false/>
    <key>WFWorkflowIcon</key>
    <dict>
        <key>WFWorkflowIconGlyphNumber</key>
        <integer>61440</integer>
        <key>WFWorkflowIconStartColor</key>
        <integer>431817727</integer>
    </dict>
    <key>WFWorkflowImportQuestions</key>
    <array/>
    <key>WFWorkflowInputContentItemClasses</key>
    <array/>
    <key>WFWorkflowMinimumClientVersion</key>
    <integer>900</integer>
    <key>WFWorkflowMinimumClientVersionString</key>
    <string>900</string>
    <key>WFWorkflowName</key>
    <string>My Shortcut</string>
    <key>WFWorkflowOutputContentItemClasses</key>
    <array/>
    <key>WFWorkflowTypes</key>
    <array/>
</dict>
</plist>

Minimal Hello World

<dict>
    <key>WFWorkflowActionIdentifier</key>
    <string>is.workflow.actions.gettext</string>
    <key>WFWorkflowActionParameters</key>
    <dict>
        <key>UUID</key>
        <string>A1B2C3D4-E5F6-7890-ABCD-EF1234567890</string>
        <key>WFTextActionText</key>
        <string>Hello World!</string>
    </dict>
</dict>
<dict>
    <key>WFWorkflowActionIdentifier</key>
    <string>is.workflow.actions.showresult</string>
    <key>WFWorkflowActionParameters</key>
    <dict>
        <key>Text</key>
        <dict>
            <key>Value</key>
            <dict>
                <key>attachmentsByRange</key>
                <dict>
                    <ke