Shortcuts Playground: Building Apple Shortcuts from a Sentence

The problem: Shortcuts files are signed XML that nobody wants to hand-edit

Apple's Shortcuts app stores workflows as XML that is then signed and encrypted into a `.shortcut` container the operating system accepts. The README states this plainly: shortcuts "have always been XML files that get signed and encrypted into a special, Apple-only `.shortcut` format." That gap between readable XML and an importable file is where most automation projects stall. You can generate a plausible action graph, but the Shortcuts app will reject it if a parameter key is misspelled, an enum case is wrong, or a boolean is passed where the schema expects something else.

The plugin targets people who already use an agentic coding tool and want shortcut authoring inside it. The README says you install it in either Claude Code or Codex, and it notes that the Claude Code version currently offers a richer experience because of dedicated commands and agents. If you are the kind of person who writes scripts to generate scripts, this is aimed at you. If you build shortcuts by dragging actions in the Shortcuts editor and rarely touch the underlying file, the plugin adds a toolchain you may not need.

How the build, validate and sign loop actually works

The mechanism is a knowledge base plus a correction loop. The repository ships documentation that teaches the agent how Shortcuts actions are shaped, what syntax they use, and how actions connect to one another. The agent writes XML, a validator checks it, and errors are fed back into the agent's context so it can revise before signing. The README calls this a Craig Loop and says it adds a few seconds of latency while improving output quality.

Validation is wired in through hooks rather than a manual step. In Claude Code, a `PostToolUse` hook runs on every file write. Codex can do the same once plugin hooks are enabled. Signing itself is delegated to Apple's built-in `shortcuts` CLI, which is why macOS is a hard requirement rather than a preference.

The knowledge base is broader than a syntax cheat sheet. For OS 27-era Shortcuts, the plugin ships what the README describes as target-gated ToolKit v78 action coverage, plus parameter-key, enum-case, automation-trigger and exported `WFWorkflowTriggers` catalogs. Those catalogs are packaged as JSON, so the README's claim is that existing users do not need macOS 27 or private Apple frameworks installed to benefit from them.

The remix path is a separate mode. Point the agent at an unsigned `.xml` shortcut and describe a change; the README says it applies a surgical diff that preserves every action, UUID and icon you did not ask to touch. That constraint matters more than it sounds. Shortcut XML is full of cross-references, and a diff that rewrites identifiers can silently break variable wiring.

Installing the plugin in Claude Code and building your first shortcut

Requirements come first. You need macOS, because signing uses the built-in `shortcuts` CLI. You need Claude Code or Codex, installed from claude.com/claude-code or openai.com/codex. You need Python 3.10 or later, because the bundled validator requires it; the README warns that the system Python on older macOS versions ships 3.9 and will fail. Homebrew or the `SHORTCUTS_PLAYGROUND_PYTHON` environment variable are the two fixes the README names.

Installation in Claude Code is two commands, run from any directory:

claude plugin marketplace add https://github.com/viticci/shortcuts-playground-plugin
claude plugin install shortcuts-playground@shortcuts-playground

The first registers the marketplace, the second installs the plugin. Claude Code clones the repository into its plugin cache on first install. If that clone fails with a GitHub auth error, the README suggests confirming that `git clone https://github.com/viticci/shortcuts-playground-plugin.git` works in your terminal before retrying. Start a new session afterward so the plugin loads.

Building is a single command followed by a description:

/shortcuts-playground:build

According to the README, the agent designs the action list, wires variables, picks an icon, runs the XML through the self-correcting validation loop, and signs the result. You should end up with a `.shortcut` file you can import into the Shortcuts app. The README does not describe what the command prints at each stage, so treat the first run as a way to see the loop in action rather than as a predictable transcript.

Codex takes a slightly different route. You register the marketplace, then install from inside the app or CLI:

codex plugin marketplace add https://github.com/viticci/shortcuts-playground-plugin
codex

Inside Codex, the README says to type `/plugins`, choose the Shortcuts Playground marketplace, open the plugin and select `Install plugin`. Automatic validation is off by default there. To turn it on, add the following to `~/.codex/config.toml` and review the hook from `/hooks` if Codex prompts you:

[features]
plugin_hooks = true

For local development, the README shows registering a checkout instead of the GitHub URL, using `codex plugin marketplace add /absolute/path/to/shortcuts-playground-plugin`.

The macOS 26 default versus the opt-in OS 27 surface

Version 1.2.1 is where the target gating becomes visible. The release notes say it extends early, opt-in macOS and iOS 27 support while keeping macOS 26 users on the existing validation surface by default. That default is deliberate: identifiers and parameters that only exist in OS 27 require `target_macos = "27"` or the `SHORTCUTS_PLAYGROUND_TARGET_MACOS=27` environment variable. Without one of those, validation stays conservative.

The OS 27 authoring coverage listed in the release notes includes Stored Content, Add Item to List, Otherwise If, Get Selected Text, Get What's On Screen, VPN actions, Notes markdown, Safari tab groups, route options, and several AppIntent parameter and enum updates. The 1.2.1 notes also describe a validator that catches more blank fields, wrong input keys, bad enum values, invalid boolean parameters, AppIntent schema typos, conditional wiring errors, and signing or import pitfalls across both hosts.

The weakest part of the release notes is the automation header catalog. Display and Stage Manager samples are described as copyable, but current Mac drive, file and folder exports are documented as lossy and require manual picker configuration in Shortcuts. That is an honest disclosure, and it is also a real boundary: if your shortcut depends on External Drive, File Modified or Folder Changed triggers, expect to finish the configuration by hand. Nothing in the README or the release notes suggests the plugin can round-trip those triggers cleanly today.

Where Shortcuts Playground is the wrong tool

The signing step pins this to macOS. There is no documented path for generating a signed `.shortcut` on Linux or Windows, and the README does not hint at one. A team that wants to generate shortcut files in CI on a Linux runner has no supported route here, even though the validator is Python and the XML is text.

Python version is a second trap. The validator needs 3.10 or later, and the README explicitly calls out the 3.9 system Python on older macOS releases as a failure case. If you install the plugin and skip the interpreter check, you will hit the failure after the agent has already done its work.

There is also a dependency on the host agent behaving well. Validation runs through hooks, and in Codex those hooks are off until you add `[features].plugin_hooks = true` and trust the hook. Without that, the self-correcting loop does not close, and you are back to accepting whatever the model produced on the first pass.

Finally, the README does not document rollback. If a signed shortcut imports but misbehaves, there is no described mechanism for reverting to a prior version of the workflow beyond keeping your own copies of the XML. That is an omission, not a hidden feature, and it matters for anything you intend to maintain over time.

How it differs from hand-authoring or plain XML generation

The obvious alternative is asking Claude or Codex to write shortcut XML without a plugin. The practical difference is the knowledge base and the validation loop. A general-purpose agent has no shipped catalog of parameter keys, enum cases, automation triggers or exported `WFWorkflowTriggers` samples, and no hook that re-runs a validator on every write. You would be relying on whatever the model memorized about Shortcuts, then discovering schema errors at import time.

The second alternative is the Shortcuts app itself. Dragging actions gives you immediate visual feedback and no Python dependency, but it does not scale to repetitive or parameterized workflows, and it does not give you a diff-based remix of an existing file. The plugin's remix mode is explicitly about preserving actions, UUIDs and icons you did not ask to change, which is a different job from editing by hand.

A third option is writing your own generator against Apple's metadata. That is essentially what this project has done, and the release notes describe the catalogs as generated from Apple's local ToolKit, ToolRenderer and WorkflowKit metadata plus maintainer-exported shortcut XML. Rebuilding that pipeline is possible but it is the bulk of the work, and it is the part that has to be redone as Apple ships new action versions.

Maintenance, licensing and what the release cadence tells you

The repository is not archived, and the last push was on 2026-06-15, which is the same day version 1.2.1 was released. Version 1.2.0 landed on 2026-06-14 and 1.1.0 on 2026-06-07, so the three most recent releases arrived within about a week of each other. That is a burst rather than a long trend, and the release history does not show what happens between bursts.

The upgrade cost is mostly in the OS 27 gating. New identifiers and parameters require `target_macos = "27"` or `SHORTCUTS_PLAYGROUND_TARGET_MACOS=27`, so moving a project forward means deciding per project which surface you validate against. The release notes frame the default as conservative for existing macOS 26 users, which implies that jumping to the 27 surface is a deliberate choice rather than an automatic upgrade. If you maintain shortcuts that must run on older systems, staying on the default is the safer setting.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is a permissive arrangement, but it is not legal advice; check how the MIT terms interact with your own distribution model, particularly if you ship generated shortcuts inside a product. The plugin also depends on Apple's `shortcuts` CLI and on Claude Code or Codex, each governed by its own terms.

Editorial conclusion

Adopt it if you already work in Claude Code or Codex on a Mac and want repeatable shortcut authoring instead of dragging actions around by hand. Skip it if your team is on Linux or Windows, if you depend on the system Python on an older macOS release, or if you need a documented rollback path, since the README does not describe one. Before trusting it, run the validator once on a shortcut you already own and check that the signed output imports cleanly, then confirm whether your project needs the macOS 26 default or the opt-in target_macos = "27" surface.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. viticci/shortcuts-playground-plugin on GitHub