Shortcuts Playground: Claude Code/Codex plugin for Apple Shortcuts

My notes

Summary

Shortcuts Playground is a Claude Code / Codex plugin that turns a plain-English description into a real, signed Apple .shortcut file. The agent generates the underlying XML, validates it through a self-correcting loop, and signs it via Apple’s native shortcuts CLI. Built by Federico Viticci (MacStories).

Key Insight

The architecture is the lesson, not the product. This is a reference design for “agent generates a structured artifact, then a hook validates and feeds errors back.”

• Craig Loop - a PostToolUse hook runs a validator on every XML write; errors feed back into the agent’s context so it self-corrects before signing. Adds latency, “dramatically improves output quality.” This is the generalizable pattern: agent + deterministic validator + feedback loop.
• Knowledge base does the heavy lifting - ~12,000 lines of reference, 56 best-practice rules, verified action identifiers from Apple’s ToolKit v63, and 19 golden example XMLs. The model isn’t expected to “know” Shortcuts; the skill teaches it.
• Surgical remix - the remix agent applies a diff to an unsigned .xml, preserving every untouched action, UUID, and icon. Original is never overwritten. Good model for safe AI edits to structured files.
• Honest reliability framing - “~90% of the way,” with a documented watch-list (empty variable connections, repeat-loop variable scope, always inspect before relying). Sets expectations instead of overpromising.
• Cross-runtime - ships both a Claude Code plugin (./claude) and a Codex plugin (./codex), each with its own marketplace.json. Codex needs [features].plugin_hooks = true for the validation hook.
• Python 3.10+ gotcha - bundled validator fails on macOS system Python 3.9; set SHORTCUTS_PLAYGROUND_PYTHON or brew install python3.