shortcuts-playground

name	shortcuts-playground
description	Build, validate, sign, archive, and remix macOS/iOS Shortcuts in Codex 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, HealthKit, variable references, and control flow using bundled target-gated ToolKit snapshots.

Shortcuts Playground

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

Codex Compatibility

Codex plugins do not expose the Claude Code slash commands, specialized agents, or PATH wrapper commands from the Claude package. In Codex, use this skill directly and call the bundled scripts by path.

The Codex package also bundles a PostToolUse auto-validation hook. It runs only when Codex plugin hooks are enabled with [features].plugin_hooks = true and the hook has been trusted in /hooks if Codex prompts for review. The hook validates changed .xml/.shortcut files that contain WFWorkflowActions.

Resolve the skill directory as the folder containing this SKILL.md. In examples below, SKILL_DIR means that directory.

Task	Codex command pattern
Resolve icon/color	python3 "$SKILL_DIR/scripts/select_shortcut_icon_color.py" --prompt "$USER_PROMPT"
Validate XML	python3 "$SKILL_DIR/scripts/validate_shortcut.py" /path/to/Shortcut.xml
Archive + sign	"$SKILL_DIR/scripts/sign_shortcut.sh" /path/to/Shortcut.xml --name "Shortcut Name"

sign_shortcut.sh defaults to SHORTCUTS_PLAYGROUND_OUTPUT_DIR or ~/Documents/Shortcuts Playground, and SHORTCUTS_PLAYGROUND_SIGNING_MODE or anyone. It requires macOS and Apple's shortcuts CLI. The validator only requires Python 3.10+.

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 scripts/sign_shortcut.sh 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 for mandatory rules and validation expectations
2. PLIST_FORMAT.md for plist structure and serialization details
3. ACTIONS.md, APPINTENTS.md, AUTOMATION_TRIGGERS.md, and THIRD_PARTY_ACTIONS.md for action IDs, AppIntent parameters, and OS 27 trigger metadata
4. HEALTHKIT.md when building or remixing Health actions
5. VARIABLES.md, CONTROL_FLOW.md, and FILTERS.md for wiring patterns
6. ICONS_AND_COLORS.md, PARAMETER_TYPES.md, and 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>
                    <key>{0, 1}</key>
                    <dict>
                        <key>OutputName</key>
                        <string>Text</string>
                        <key>OutputUUID</key>
                        <string>A1B2C3D4-E5F6-7890-ABCD-EF1234567890</string>
                        <key>Type</key>
                        <string>ActionOutput</string>
                    </dict>
                </dict>
                <key>string</key>
                <string></string>
            </dict>
            <key>WFSerializationType</key>
            <string>WFTextTokenString</string>
        </dict>
    </dict>
</dict>

Core Concepts

1. Actions

Every action has:

• Identifier: is.workflow.actions.<name> (e.g., is.workflow.actions.showresult)
• Parameters: Action-specific configuration in WFWorkflowActionParameters
• UUID: Unique identifier for referencing this action's output

2. Variable References

To use output from a previous action:

1. The source action needs a UUID parameter
2. Reference it using OutputUUID in an attachmentsByRange dictionary
3. Use `` (U+FFFC) as placeholder in the string where the variable goes
4. Set WFSerializationType to WFTextTokenString

3. Control Flow

Control flow actions (repeat, conditional, menu) use:

• GroupingIdentifier: UUID linking start/middle/end actions
• WFControlFlowMode: 0=start, 1=middle (else/case), 2=end

Common Actions Quick Reference

Action	Identifier	Key Parameters
Text	is.workflow.actions.gettext	WFTextActionText
Show Result	is.workflow.actions.showresult	Text
Ask for Input	is.workflow.actions.ask	WFAskActionPrompt, WFInputType
Use AI Model	is.workflow.actions.askllm	WFLLMPrompt, WFLLMModel, WFGenerativeResultType, WFAllowWebSearch, FollowUp (OS 27+)
Comment	is.workflow.actions.comment	WFCommentActionText
URL	is.workflow.actions.url	WFURLActionURL
Get Contents of URL	is.workflow.actions.downloadurl	WFURL, WFHTTPMethod
Get Weather	is.workflow.actions.weather.currentconditions	(none required)
Open App	is.workflow.actions.openapp	WFAppIdentifier
Open URL	is.workflow.actions.openurl	WFInput
Alert	is.workflow.actions.alert	WFAlertActionTitle, WFAlertActionMessage
Notification	is.workflow.actions.notification	WFNotificationActionTitle, WFNotificationActionBody
Set Variable	is.workflow.actions.setvariable	WFVariableName, WFInput
Get Variable	is.workflow.actions.getvariable	WFVariable
Number	is.workflow.actions.number	WFNumberActionNumber
List	is.workflow.actions.list	WFItems
Dictionary	is.workflow.actions.dictionary	WFItems
Repeat (count)	is.workflow.actions.repeat.count	WFRepeatCount, GroupingIdentifier, WFControlFlowMode
Repeat (each)	is.workflow.actions.repeat.each	WFInput, GroupingIdentifier, WFControlFlowMode
If/Otherwise	is.workflow.actions.conditional	WFInput, WFCondition, GroupingIdentifier, WFControlFlowMode
Choose from Menu	is.workflow.actions.choosefrommenu	WFMenuPrompt, WFMenuItems, GroupingIdentifier, WFControlFlowMode
Find Photos	is.workflow.actions.filter.photos	WFContentItemFilter (see FILTERS.md)
Delete Photos	is.workflow.actions.deletephotos	photos (NOT WFInput!)

Detailed Reference Files

For complete documentation, see:

• PLIST_FORMAT.md - Complete plist structure
• ICONS_AND_COLORS.md - Icon glyph + color selection (explicit and inferred)
• ACTIONS.md - WF*Action identifiers and parameters
• APPINTENTS.md - AppIntent actions (ToolKit + backups)
• AUTOMATION_TRIGGERS.md - OS 27 ToolKit automation trigger metadata for research and future automation support
• PARAMETER_TYPES.md - All parameter value types and serialization formats
• HEALTHKIT.md - iOS/iPadOS Health actions, bundled anonymized XML examples, and HealthKit value coverage
• URL_SCHEMES.md - Apple-documented Shortcuts URL schemes and x-callback-url patterns
• JAVASCRIPT_WEBPAGE.md - Run JavaScript on Webpage runtime requirements and script rules
• DATE_TIME.md - Apple-aligned date/time recipes, UNIX timestamps, ISO 8601, RFC 2822, and custom formats
• VARIABLES.md - Variable reference system
• CONTROL_FLOW.md - Repeat, Conditional, Menu patterns
• FILTERS.md - Content filters for Find/Filter actions (photos, files, etc.)
• EXAMPLES.md - Complete working examples
• BEST_PRACTICES.md - Mandatory build guidelines
• THIRD_PARTY_ACTIONS.md - Third-party actions (ToolKit + backups)
• TOOLKIT_SNAPSHOT.md - Bundled ToolKit action-ID allowlists
• CHANGELOG.md - Change history: autoresearch findings, documentation updates, and version notes

When you need to verify an unfamiliar action identifier, check the packaged data/toolkit-v*-tool-ids.json snapshots, then ACTIONS.md, APPINTENTS.md, and THIRD_PARTY_ACTIONS.md before inventing anything.

Golden Example Library (On-Demand)

A curated set of shortcut XMLs is available for on-demand reference. Use the index first; only load XML sources that match the current task.

• Index: golden-shortcuts/index.jsonl (token-efficient metadata: title, purpose, tags, xml path)
• XMLs: golden-shortcuts/xml/<shortcut_id>.xml
• Note: Golden XMLs are pattern references and may predate current validator/comment standards; treat them as wiring examples, not pass/fail baselines.

Workflow:

1. Read golden-shortcuts/index.jsonl to find relevant examples by tags/purpose.
2. Load only the single XML file(s) needed for the current task.
3. Do not bulk-load the entire library.

Icon and Color Resolver (Required)

For every generated shortcut, choose icon and color using the resolver unless the user gave explicit integer values already:

python3 "$SKILL_DIR/scripts/select_shortcut_icon_color.py" --prompt "${USER_PROMPT}"

Optional explicit overrides:

python3 "$SKILL_DIR/scripts/select_shortcut_icon_color.py" --prompt "${USER_PROMPT}" --icon "robot" --color "purple"

Then set:

• WFWorkflowIconGlyphNumber = icon.glyph_number
• WFWorkflowIconStartColor = color.value

The resolver supports natural-language icon requests (e.g. paper airplane icon, terminal icon, expense icon) and automatic icon selection when no icon is requested.

Preflight Validator — Craig Loop (Required)

After generating a shortcut, run the validator in a fix loop (Craig Loop). Each iteration: read the errors, make a targeted fix, re-validate. Do not re-run without changing something. If the Codex PostToolUse hook reports validator feedback after an edit, treat that as the current validator run and fix the reported errors before signing.

python3 "$SKILL_DIR/scripts/validate_shortcut.py" /path/to/Shortcut.xml

Craig Loop Protocol

1. Run the validator. If it passes, proceed to signing.
2. Read ALL error messages. The validator prints every error it finds — fix as many as possible in one pass, not just the first one.
3. Make targeted fixes in the plist XML based on the error messages. Each error includes the action index and identifier so you know exactly where to edit.
4. Re-run the validator. Repeat from step 1.
5. Exit conditions (stop looping and report to the user):
   • Max 5 iterations. If the validator still fails after 5 fix attempts, stop. Summarize the remaining errors and ask the user for guidance.
   • Same errors repeating. If the same error persists across 2 consecutive iterations despite attempted fixes, stop. The fix approach is wrong — do not keep trying the same thing.
   • Known validator gaps. Only waive validator failures if BEST_PRACTICES.md lists a current, runtime-verified false positive. Otherwise fix the shortcut or stop and report the exact remaining errors.

Anti-patterns (do NOT do these)

• Chatting the validator: Running the validator repeatedly without making meaningful code changes between runs. Every re-run must follow a real edit.
• Cosmetic fixes: Rearranging comments or renaming variables to "try something" when the error is about wiring or missing parameters.
• Regenerating from scratch when only 1-2 specific actions need fixing. Targeted edits preserve working wiring.

Data sources

The validator uses bundled ToolKit snapshot IDs from packaged data/toolkit-v*-tool-ids.json files, filtered by target OS version and target platform, then augments with ACTIONS.md, APPINTENTS.md, and THIRD_PARTY_ACTIONS.md. The default OS target is auto (sw_vers on macOS, macOS 26 when the host cannot be detected). The default platform target is macos. Use --target-macos 27 or SHORTCUTS_PLAYGROUND_TARGET_MACOS=27 only when building OS 27-era shortcuts that need target-gated macOS v78 identifiers or OS 27-only parameters such as WFAllowWebSearch / FollowUp on Use Model, interpretAsMarkdown, WFAvoidTolls, and Safari Tab Group contents. Use --target-platform ios / SHORTCUTS_PLAYGROUND_TARGET_PLATFORM=ios only for iPhone/iPad authoring, and --target-platform all only for intentional cross-platform metadata audits. For OS 27 targets, the validator also uses data/toolkit-v78-first-party-parameter-keys.json to reject unknown top-level keys on first-party com.apple.* AppIntent-style actions. It does not read the user's live ToolKit SQLite database during normal validation.

For reviewed Apple-derived macOS 27 schema grounding and automation trigger metadata, use the static catalogs only:

python3 "$SKILL_DIR/scripts/lookup_action_grounding.py" --identifier additemtolist --target-macos 27
python3 "$SKILL_DIR/scripts/lookup_action_grounding.py" --python-name when_app_opened --target-macos 27
python3 "$SKILL_DIR/scripts/lookup_action_grounding.py" --identifier com.apple.HearingApp.MuteVolumeIntent --target-macos 27 --target-platform ios

data/macos27-shortpy-grounding.json may improve parameter/schema confidence, data/toolkit-v78-first-party-enum-cases.json may improve picker-value selection, data/toolkit-v78-trigger-parameter-keys.json may improve automation-trigger discovery, and data/macos27-workflow-trigger-samples.json may show sanitized exported WFWorkflowTriggers shapes for observed OS 27 automation headers. None of them overrides validator target gating. The lookup helper reports target-platform availability notes for iOS-only/macOS-only ToolKit rows. Exported automation-bearing shortcuts are the authority for portable automation-header authoring; do not infer that carrier from ToolKit metadata alone.

Escape-hatch comments

If a request explicitly requires vCard/VCF formatting or file-based token loading, add a Comment containing ALLOW_VCARD or ALLOW_TOKEN_FILE so the validator can allow it. Other escape hatches: ALLOW_MANUAL_UNIT_CONVERSION, ALLOW_DATETIME_FORMAT.

Wiring Regression Suite (Recommended)

When changing wiring logic or validator rules for Weather/Location actions, run the bulk regression suite:

python3 "$SKILL_DIR/scripts/test_wiring_regressions.py" --write-fixtures /tmp/shortcuts-wiring-regressions

The suite generates and validates:

• 43 Weather Detail cases (21 valid + 22 invalid)
• 40 Location parameter cases (20 valid + 20 invalid)
• 16 Set Name/Rename File cases (8 valid + 8 invalid)

It exits non-zero if any case behavior regresses.

Random Mixed-Action Stress Suite (Recommended)

For broad randomized coverage (brand-new shortcuts, 10+ distinct actions each), run:

python3 "$SKILL_DIR/scripts/test_random_mixed_shortcuts.py" --count 50 --min-actions 10

Behavior:

• Generates brand-new random shortcuts under --output-dir when provided, otherwise SHORTCUTS_PLAYGROUND_OUTPUT_DIR/<YYYY-MM-DD>/random-mixed-actions-<runid>/ or ~/Documents/Shortcuts Playground/<YYYY-MM-DD>/random-mixed-actions-<runid>/.
• Enforces a minimum distinct action count per shortcut (--min-actions, default 10).
• Runs validate/retry loops per case (--max-attempts, default 20).
• Writes manifest.json, results.json, and summary.md for documentation.

Optional:

python3 "$SKILL_DIR/scripts/test_random_mixed_shortcuts.py" --count 50 --min-actions 10 --sign

For OS 27 coverage, opt in explicitly so older users and CI jobs do not validate Golden Gate-only actions by accident:

python3 "$SKILL_DIR/scripts/test_random_mixed_shortcuts.py" --count 50 --min-actions 10 --target-macos 27 --include-os27-actions --sign

The OS 27 module adds Stored Content, Add Item to List, Otherwise If, Get Selected Text, Get What's On Screen, and Get Current VPN to every generated shortcut.

Use this suite when you need randomized multi-action regression coverage beyond targeted wiring tests.

Signing Shortcuts

Shortcuts MUST be signed before they can be imported. The Codex skill ships scripts/sign_shortcut.sh, which combines archive + sign into a single command:

# Archives the unsigned XML under $output_dir/$(date +%F)/ and writes a signed .shortcut to $output_dir.
"$SKILL_DIR/scripts/sign_shortcut.sh" /path/to/MyShortcut.xml --name "My Shortcut"

# Override the signing mode (default is SHORTCUTS_PLAYGROUND_SIGNING_MODE, falling back to 'anyone').
"$SKILL_DIR/scripts/sign_shortcut.sh" /path/to/MyShortcut.xml --name "My Shortcut" --mode people-who-know-me

The underlying pipeline is still the macOS shortcuts CLI:

shortcuts sign --mode anyone --input MyShortcut.shortcut --output MyShortcut.shortcut

The signing process:

1. Write your plist as XML to a .shortcut file by default.
2. Run scripts/sign_shortcut.sh (or shortcuts sign directly) to add the cryptographic signature (~19KB added). The wrapper archives the XML, then retries a validator-clean format failure after binary plist conversion when Apple's XML signer chokes.
3. Keep the signed output filename equal to the intended display name (no _signed suffix).
4. The signed file can be opened/imported into Shortcuts.app.

Signing gotchas:

• If shortcuts sign reports Error: The file doesn't exist. but the file exists, copy the XML plist directly to a clean .shortcut path and retry (example: cp source.xml /tmp/MyShortcut.shortcut).
• If shortcuts sign reports Error: The file couldn't be opened because it isn't in the correct format. while validate_shortcut.py and plutil -lint pass, retry after plutil -convert binary1 on the final .shortcut copy before blaming the plist. scripts/sign_shortcut.sh performs this retry automatically; if both attempts fail, suspect Codex workspace-write sandbox restrictions before treating the XML as malformed.
• ERROR: Unrecognized attribute string flag '?' warnings are noisy but can be non-fatal if the output file is produced.
• The shortcuts CLI supports run, list, view, and sign; do not assume delete, rename, or import subcommands.

Archive Raw XML (Required)

Before signing, archive the unsigned XML in a date/time folder for inspection. scripts/sign_shortcut.sh does this for you, but the rules below still apply when you invoke shortcuts sign directly.

Folder structure rule:

• The archive root is SHORTCUTS_PLAYGROUND_OUTPUT_DIR (falls back to ~/Documents/Shortcuts Playground/ when unset).
• Inside the archive root, create a date folder for the current day (YYYY-MM-DD) if it doesn't exist.
• Copy the unsigned XML into that date folder with a time-stamped filename.

Example (output dir = ~/Documents/Shortcuts Playground):

• Archive folder: ~/Documents/Shortcuts Playground/2026-02-03/
• Archive file: My Shortcut-142355.xml

Command pattern (the one-liner scripts/sign_shortcut.sh wraps):

OUTPUT_DIR="${SHORTCUTS_PLAYGROUND_OUTPUT_DIR:-$HOME/Documents/Shortcuts Playground}"
ARCHIVE_ROOT="$OUTPUT_DIR/$(date +%F)"
mkdir -p "$ARCHIVE_ROOT"
cp "/path/to/My Shortcut.xml" "$ARCHIVE_ROOT/My Shortcut-$(date +%H%M%S).xml"

The archive copy must be the unsigned, raw XML (not the signed .shortcut).

Workflow for Creating Shortcuts

0. Research external APIs - For complex/unfamiliar APIs, read the latest official docs before drafting request code.
1. Define actions - List what the shortcut should do
2. Generate UUIDs - Each action that produces output needs a unique UUID
3. Build action array - Create each action dictionary with identifier and parameters
4. Wire variable references - Connect outputs to inputs using OutputUUID
5. Resolve icon and color - Run scripts/select_shortcut_icon_color.py with the full user prompt (plus any explicit icon/color hints) and use the returned values
6. Wrap in plist - Add the root structure with icon, name, version
7. Write to file - Save as .shortcut (XML plist format is fine)
8. Preflight validation - Run the Craig Loop (see above): validate → fix → re-validate, max 5 iterations.
9. Archive + Sign (required) - Run "$SKILL_DIR/scripts/sign_shortcut.sh" /path/to/file.xml --name "Final Name". This script archives the unsigned XML to SHORTCUTS_PLAYGROUND_OUTPUT_DIR/$(date +%F)/ or ~/Documents/Shortcuts Playground/$(date +%F)/ and writes the signed .shortcut alongside it. Never leave the signing output filename with a _signed suffix.
10. Verify signed output (required) - Confirm the signed .shortcut path reported by sign_shortcut.sh exists and has non-zero size before reporting done. Stopping at "validation passed" is a failed build.

After step 8 succeeds, go directly to step 9. Any edit after validation, including comment or wording polish, requires another validation and another signing pass.

Comment Blocks (Repair-Oriented)

Because variable wiring can require manual fixes, add a concise Comment before each major block with a bulleted list describing which variables must be connected. Keep it short, specific, and focused on wiring (e.g., “Use Repeat Item 2 inside inner loop”). Write comments with Shortcuts UI wording (for example, Input, Date, Provided Input, Repeat Item, Text) and readable action names (Ask for Input, Text, Save File). Do not use plist key jargon like WFInput / WFDate / WFImage in Comment text. NEVER include UUIDs, OutputUUID references, or technical plist details in Comment text — comments must be descriptive natural language only. Prefer wording like - Input uses the text output from the Text action above and • Date uses the user's answer from Ask for Input instead of WF* field names or UUID references.

Key Rules

1. UUIDs must be uppercase and generated via uuidgen, not hand-picked. Before emitting a shortcut, run a single Bash call to generate all the UUIDs you'll need:

   for i in $(seq 1 <N>); do uuidgen | tr '[:lower:]' '[:upper:]'; done
   

   Where <N> is the number of action UUIDs the shortcut requires (one per action that produces output or is referenced by downstream actions). Assign each output line to a specific action in your working map, then paste them into the plist. Never use sequential placeholders like 11111111-1111-1111-1111-111111111111, AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA, or any other pattern where every hex character is the same — the validator rejects repeating-hex UUIDs as a hard error. Valid example shape: 7F3A4E91-C2D8-4B56-BE5A-0242AC120002.
2. WFControlFlowMode is an integer: Use <integer>0</integer> not <string>0</string>
3. Range keys use format: {position, length} - e.g., {0, 1} for first character
4. The placeholder character: `` (U+FFFC) marks where variables are inserted
5. Control flow needs matching ends: Every repeat/if/menu start needs an end action with same GroupingIdentifier
6. Match placeholder positions: attachmentsByRange must point to the exact index of each `` in the final string
7. No out-of-bounds ranges: attachmentsByRange positions beyond string length can crash Shortcuts on import
8. Avoid empty placeholders: Omit unused keys or fields; do not leave empty values where the action expects data
9. WFURL serialization: For WFURL parameters (especially downloadurl), use WFTextTokenString with `` placeholders even when the URL is entirely a variable; reserve WFTextTokenAttachment for parameters that are explicitly variable-only (e.g., WFVariable, WFRequestVariable)
10. Form file fields and WFRequestVariable: For WFHTTPBodyType = Form, file fields (WFItemType = 5) must wrap the file reference in WFTokenAttachmentParameterState with an inner WFTextTokenAttachment so the UI shows the connected file variable. Set WFRequestVariable only when body type is File (JSON Text fallback pattern)
11. Array fields: For WFDictionaryFieldValue items with WFItemType = 2, use WFArrayParameterState with a list of items (WFItemType + WFValue), not numeric keys inside another dictionary
12. Format Date input: Set WFDate (not WFInput) as a WFTextTokenString placeholder wired to a Date output; never leave WFDate empty
13. Repeat loops: Inside Repeat with Each, use Repeat Item for per-item extraction; avoid Repeat Results inside the loop
14. Reuse extractions: If you extract multiple fields from a dictionary/API response, reuse each value later or remove the unused extraction
15. Variable placeholders: When composing strings or URLs with variables (Ask for Input, Track/Artist, etc.), insert a placeholder for every variable and align attachmentsByRange positions
16. Dictionary dot notation: Use dot notation (with 1-based indexes) in WFDictionaryKey to access nested keys (e.g., results.tracks.items, artists.1.name), but guard optional parents first (avoid direct error.message on raw API responses)
17. Conditional inputs (verified against Apple-built samples): For is.workflow.actions.conditional with WFControlFlowMode = 0, every condition code requires an explicit WFInput set as { Type: "Variable", Variable: { Value: <ActionOutput or Variable>, WFSerializationType: "WFTextTokenAttachment" } }. There is no implicit-input mode. Per-code literal field requirements: string codes 4/5/8/9/99/999 need WFConditionalActionString; numeric codes 0/1/2/3 need WFNumberValue; numeric 1003 (is between) needs both WFNumberValue (lower) and WFAnotherNumber (upper, attachment); existence codes 100/101 need neither literal field. Code 0 is is less than (NOT equals); codes 0–3 are inequalities. Multi-condition Ifs use WFConditions with WFContentPredicateTableTemplate serialization; do not mix WFConditions with top-level WFCondition. macOS 27 Otherwise If is the same conditional identifier with WFControlFlowMode = 1 plus condition fields. Plain Otherwise is mode 1 with no condition fields; End If is mode 2. For JSON booleans, compare numerically (1/0); treat JSON null as empty. See CONTROL_FLOW.md "Condition Codes" and "Multi-condition If" for the complete reference and templates.
18. Workflow icon keys are mandatory: Always set both WFWorkflowIconGlyphNumber and WFWorkflowIconStartColor in WFWorkflowIcon (use resolver output)
19. Runtime file picking: If the user needs to choose a file, use is.workflow.actions.file.select and connect its output
20. Text token validation: Run a final validation pass over every WFTextTokenString and refuse to output if any attachmentsByRange key does not map to a placeholder position or if counts mismatch
21. No unrequested services: Do not introduce third-party APIs, external CDNs, or extra import questions unless the user explicitly requests them
22. Notion image uploads: Default to Notion file_uploads + file_upload block type; avoid external image blocks unless the user supplies a URL or asks for external hosting
23. Notion title filters: Use the Notion title property name unless the user explicitly says their database uses a different title property name (e.g., Name)
24. API research and endpoint accuracy: For complex or unfamiliar external APIs, verify auth, endpoints, parameters, and payload formats against the latest official docs before assembling the shortcut. Validate endpoint strings exactly (underscore vs hyphen matters)
25. API string sanity checks: Before output, scan API strings for // (beyond protocol) and empty JSON fields where variables are expected (e.g., equals:””, id:””, url:””, filename:””), and fix them
26. JSON request bodies: For WFHTTPBodyType = JSON, use WFJSONValues for flat key/value payloads so the body is preserved in Shortcuts UI
27. Format Date custom style: When WFDateFormatStyle is Custom, set WFDateFormat=Custom and put the pattern in WFDateFormatString (e.g., MMMM d, yyyy, yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:ssXXXXX). See DATE_TIME.md for UNIX timestamp, ISO 8601, RFC 2822, and Unicode TR35 guidance
28. Complex JSON fallback: If the JSON body includes arrays of objects or deep nesting and the UI renders it as Number 0/empty rows, use a JSON Text action and set WFRequestVariable to that text with WFHTTPBodyType = File and Content-Type: application/json
29. Filename extensions: When using Get Name for file uploads, append the correct extension in the JSON payload (e.g., .png) and do not rely on the base name alone
30. Count input visibility: For is.workflow.actions.count, set both WFInput and Input to the same variable so the UI shows the selected list
31. Get Name web titles: For file names, set Get Web Page Title to Off in Get Name so the action returns the file name, not a URL title
32. String If workaround: If validator rules conflict on string conditionals, use Match Text + Count + numeric If instead of direct string If
33. Replace Text empty replacement: For delete-match patterns, prefer omitting WFReplaceTextReplace; an explicit empty string is allowed, but omission is cleaner and more portable
34. Base64 input wiring: Always set WFInput for is.workflow.actions.base64encode; implicit input can import as an empty field and break runtime
35. Replace Text input visibility: For is.workflow.actions.text.replace, use a WFTextTokenString placeholder (or wrapped variable input), not a bare WFTextTokenAttachment
36. Adjust Date reliability: Use WFDate + non-empty WFDuration for is.workflow.actions.adjustdate (optionally mirror with WFInput); include WFAdjustOperation when explicit Add/Subtract is required. Offset-picker-only payloads can import as Add 0 seconds on iOS
37. Convert Image wiring: For is.workflow.actions.image.convert, always set WFInput explicitly; do not rely on implicit input chaining
38. Weather detail wiring: For is.workflow.actions.properties.weather.conditions, set both WFInput and WFContentItemPropertyName, keep WFContentItemPropertyName concrete (never placeholder Detail), and wire WFInput directly to an ActionOutput from is.workflow.actions.weather.currentconditions / is.workflow.actions.weather.forecast (no named-variable hop). Supported detail names are Date, Location, Temperature, Low, High, Feels Like, Condition, Visibility, Dewpoint, Humidity, Pressure, Precipitation Amount, Precipitation Chance, Wind Speed, Wind Direction, UV Index, Sunrise Time, Sunset Time, Air Quality Index, Air Quality Category, Air Pollutants, and Name. Sunrise Time and Sunset Time from Daily forecasts are lists: insert Get Item from List before Format Date, using First Item for sunrise and Last Item for sunset
39. Time Between Dates input wiring: For is.workflow.actions.gettimebetweendates, set WFInput and exactly one non-empty date operand (WFDate or WFTimeUntilCustomDate or WFTimeUntilFromDate) as WFTextTokenString placeholders. To compare with now, first add a Date action set to Current Date and reference that action output; never put a direct CurrentDate magic token in the action. WFTimeUntilUnit may be omitted only when intentionally using the default unit. Never emit empty unused date keys
40. Extract from Image input wiring: For is.workflow.actions.extracttextfromimage, set exactly one non-empty image input key. On OS 27+, prefer imageFile; older exported shortcuts may use WFImage or, when intentionally required by an existing pattern, WFInput.
41. API error extraction safety: Do not read error.message directly from a raw response; extract error, guard it with If Has Any Value, then read message
42. Continuation JSON array closure: When appending to a JSON array via Replace Text on \]$, the replacement must end with ]; missing the closing bracket corrupts JSON and causes Detect Dictionary to return empty
43. No raw object/list tokens inside JSON text: Do not inject Dictionary/List outputs (for example, raw API content arrays) directly into JSON Text templates; Shortcuts may stringify them as newline-separated blocks rather than valid JSON
44. Continuation payload safe pattern: For multi-turn handoff payloads, append assistant text from a plain text variable (for example, Response Text) and keep messages_json as valid JSON before rerunning the shortcut
45. JSON string interpolation safety: Before inserting freeform text into JSON Text templates (”content”:””), sanitize it first (at minimum handle backslashes, double quotes, and control whitespace/newlines) or the next Detect Dictionary step will fail
46. Shortcuts URL schemes: Only use Apple-documented shortcuts:// routes from URL_SCHEMES.md. URL-encode every query value; do not invent import/install routes or extra parameters
47. Run JavaScript on Webpage: Use is.workflow.actions.runjavascriptonwebpage only for Safari webpage share-sheet shortcuts. Include ActionExtension, scope input to WFSafariWebPageContentItem, call completion(...) or completion(), return JSON-compatible values, and avoid synchronous dialogs/long timers
48. API response parse stability: For downloadurl JSON APIs, keep ShowHeaders off unless explicitly needed and run Detect Dictionary on Contents of URL before any Get Dictionary Value extraction
49. Action input keys matter: Replace Text uses WFInput, while Change Case and Split Text use text; wrong keys import but show empty inputs in the editor
50. Split Text custom separator: If WFTextSeparator is Custom, always include WFTextCustomSeparator (a single space ” “ is valid)
51. Find Notes filter state: WFContentItemFilter must be WFContentPredicateTableTemplate with non-empty templates; for Folder filters use WFLinkDynamicOptionSubstitutableState wrapping a tokenized variable
52. Direct variable wiring: Prefer inserting named variables directly into action input fields; avoid redundant Get Variable → next action hops unless there is a clear transformation need
53. Location parameter wiring: Never emit empty location parameters. For WFLocation, WFWeatherCustomLocation, and WFWeatherLocation, use WFTextTokenAttachment (not token strings) and reference a Get Current Location/Location output (directly or via a variable sourced from those outputs). is.workflow.actions.location must include a non-empty WFLocation attachment; missing/blank payloads import as empty “Location” fields
54. Set Name vs Rename File: Use Set Name as is.workflow.actions.setitemname with WFInput (source file/item) and WFName (target filename, for example Test.txt) when a workflow needs a renamed file object to save or share elsewhere. Its output is Renamed Item. Do not confuse this with Rename File (is.workflow.actions.file.rename with WFFile and WFNewFilename), which renames the original file in place at its existing path. For "rename, save/share elsewhere, then delete original" workflows, store the picked file as Original File, run Set Name on Original File, save/share Renamed Item, then delete Original File only after the save/share step if requested
55. ⚠️ WFMathOperation syntax (verified against Shortcuts app): For is.workflow.actions.math: (a) Addition: OMIT the WFMathOperation key entirely — no key means addition; (b) Subtraction: - (ASCII minus, U+002D); (c) Multiplication: × (U+00D7, ord 215, Unicode MULTIPLICATION SIGN) — NEVER *; (d) Division: ÷ (U+00F7, ord 247, Unicode DIVISION SIGN) — NEVER /; (e) Scientific ops (Modulus, Power, etc.): WFMathOperation='…' (U+2026 horizontal ellipsis) as placeholder, with real op in WFScientificMathOperation and operand in WFScientificMathOperand. Literal operands (WFMathOperand) must be plain strings like "10", not wrapped dicts. Shortcuts silently renders ASCII / as + in the UI with no error. See PARAMETER_TYPES.md "Math and Counting Operations" for verified examples.
56. Never inspect the user's local system for authoring discovery unless the user explicitly asks for that local evidence. If an action identifier is allowlisted in data/toolkit-v*-tool-ids.json but its parameter schema is not documented in the bundled reference files (ACTIONS.md, APPINTENTS.md, PARAMETER_TYPES.md, FILTERS.md, EXAMPLES.md, BEST_PRACTICES.md, HEALTHKIT.md, static data/macos27-shortpy-grounding.json, or the golden-shortcuts/ library), stop and ask the user - do not try to reverse-engineer the schema by reading local databases, inspecting system binaries, querying Shortcuts.app internals, or searching cloud-backup folders without explicit permission. Escalate to the user with three options: (a) best-effort guess + iterate after they import, (b) use a simpler alternative action you propose, or (c) they paste a working example for you to mirror. When the user explicitly supplies or requests local exported XML, prefer that evidence over web references.
57. Automation triggers are sample-gated. AUTOMATION_TRIGGERS.md, data/toolkit-v78-trigger-parameter-keys.json, and data/macos27-workflow-trigger-samples.json document OS 27 ToolKit trigger IDs, Python names, parameter keys, output types, and sanitized exported WFWorkflowTriggers payloads. Use exported automation-bearing shortcuts as the source of truth for portable authoring. Do not invent trigger plists from ToolKit metadata alone. Do not write live Shortcuts database rows; generate shortcut XML with a top-level WFWorkflowTriggers array, fresh WFTriggerUUID values, and --target-macos 27 validation.
58. Bottom-align in Combine Images via the flip trick: is.workflow.actions.image.combine in horizontal mode top-aligns images. To bottom-align without transparent canvas padding: (1) flip each input image upside-down before Combine, (2) run Combine (now "top" is the original bottom), (3) flip the combined result upside-down. ⚠️ is.workflow.actions.image.flip behaves OPPOSITELY on iOS vs macOS — this is a genuine Apple bug across platforms: on iOS/iPadOS, WFImageFlipDirection='Vertical' produces upside-down (direction-of-motion naming); on macOS, WFImageFlipDirection='Horizontal' produces upside-down (axis-of-reflection naming). The same plist value renders differently. Workaround: wrap the flip in an If block checking Device Model is Mac → Flip Horizontally / Otherwise → Flip Vertically. Do this for BOTH flips in the trick (per-image and combined result). Proven on Apple Frames 4 proportional scaling — worked on iOS but silently failed on macOS until the device check was added
59. Reminders: always use is.workflow.actions.setters.reminders for editing, never UpdateReminderAppIntent. For every property of an existing reminder (Due Date, Title, Notes, Priority, Is Completed, Is Flagged, List, Subtasks, URL, Tags, Images, Parent Reminder, When Messaging Person), use one setters.reminders action per property with Mode="Set", WFContentItemPropertyName=<property name>, and the matching WFReminderContentItem<CamelCaseProperty> value key. Chain multiple setters by pointing each one's WFInput at the previous setter's ActionOutput (OutputName="Edited Reminder") so the "Edited Reminder" variable propagates. The List property is the only one that takes a plain string (the list name), not a token attachment. For date filtering in filter.reminders, operator 1002 ("is today") takes empty Values, operator 1003 ("is between") takes Values.Date (literal ISO <date>) + Values.AnotherDate (token attachment, typically {Type: "CurrentDate"}). See PARAMETER_TYPES.md → Reminders — Filter & Setter Schemas for the complete verified schema, the per-property value-key table, and verbatim templates.
60. HealthKit actions are iOS/iPadOS-only and must use HEALTHKIT.md. For filter.health.quantity, put the Health sample kind in a non-removable WFContentItemFilter Type predicate row backed by Values.Enumeration / WFStringSubstitutableState; never use obsolete top-level WFHealthQuantityType, and never use Property = Value with a plain string such as Step Count. For summaries, use observed picker labels such as Sleep, Exercise Minutes, and Active Calories; do not emit Sleep Analysis, Active Energy, Active Energy Burned, Apple Exercise Time, or Exercise Time for HealthKit actions. Treat Sleep Duration math as seconds if coerced through Math: divide by 3600 for decimal hours, not 60. For properties.health.quantity, health.quantity.log, and health.workout.log, use the bundled anonymized iOS XML examples and data/healthkit-ios26.2-reference.json. Do not guess the Log Health Sample schema: use WFQuantitySampleType plus WFQuantitySampleQuantity (WFQuantityFieldValue), allow unit-only WFQuantitySampleAdditionalQuantity, and add WFCategorySampleEnumeration only when a category picker value is needed. Do not run Health-writing shortcuts just to test syntax.