shortcuts-playground

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 for every shortcut. If guidance here conflicts with 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.