# Shortcuts Playground: Claude Code/Codex plugin for Apple Shortcuts

> A Claude Code / Codex plugin that turns plain-English descriptions into real, signed Apple .shortcut files via a self-correcting validation loop.

Published: 2026-05-22
URL: https://daniliants.com/insights/github-viticci-shortcuts-playground-plugin/
Tags: claude-code, codex, apple-shortcuts, agent-plugins, automation, validation-loops, macos

---

## 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`.