Build, validate, sign, archive, and REMIX macOS/iOS Shortcuts 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, variable references, and control flow using bundled target-gated ToolKit snapshots.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Build, validate, sign, archive, and REMIX macOS/iOS Shortcuts 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, variable references, and control flow using bundled target-gated ToolKit snapshots.
effort
max
allowed-tools
Read, Write, Edit, Bash, Glob, Grep
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.
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:
Read golden-shortcuts/index.jsonl to find relevant examples by tags/purpose.
Load only the single XML file(s) needed for the current task.
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:
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. The plugin's PostToolUse hook runs this for you automatically after every Write/Edit, but you may also invoke it manually:
validate-shortcut /path/to/Shortcut.xml
Craig Loop Protocol
Run the validator. If it passes, proceed to signing.
Read ALL error messages. The validator prints every error it finds — fix as many as possible in one pass, not just the first one.
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.
Re-run the validator. Repeat from step 1.
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:
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:
Generates brand-new random shortcuts under $CLAUDE_PLUGIN_OPTION_OUTPUT_DIR/<YYYY-MM-DD>/random-mixed-actions-<runid>/ (or ~/Documents/Shortcuts Playground/<YYYY-MM-DD>/random-mixed-actions-<runid>/ if output_dir was not set when the plugin was enabled).
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.
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 plugin ships a sign-shortcut wrapper that combines archive + sign into a single command and respects ${user_config.output_dir}:
# Archives the unsigned XML under $output_dir/$(date +%F)/ and writes a signed .shortcut to $output_dir.
sign-shortcut /path/to/MyShortcut.xml --name "My Shortcut"
# Override the signing mode (default is the plugin's signing_mode config, falling back to 'anyone').
sign-shortcut /path/to/MyShortcut.xml --name "My Shortcut" --mode people-who-know-me
The underlying pipeline is still the macOS shortcuts CLI:
Write your plist as XML to a .shortcut file by default.
Run sign-shortcut (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.
Keep the signed output filename equal to the intended display name (no _signed suffix).
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 and plutil -lint pass, retry after plutil -convert binary1 on the final .shortcut copy before blaming the plist. sign-shortcut performs this retry automatically; if both attempts fail, retry from an unrestricted shell and check filesystem permissions 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. The plugin's sign-shortcut wrapper does this for you — but the rules below still apply when you invoke shortcuts sign directly.
Folder structure rule:
The archive root is ${user_config.output_dir} (falls back to ~/Documents/Shortcuts Playground/ when the plugin's output_dir userConfig is 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):
The archive copy must be the unsigned, raw XML (not the signed .shortcut).
Workflow for Creating Shortcuts
Research external APIs - For complex/unfamiliar APIs, read the latest official docs before drafting request code.
Define actions - List what the shortcut should do
Generate UUIDs - Each action that produces output needs a unique UUID
Build action array - Create each action dictionary with identifier and parameters
Wire variable references - Connect outputs to inputs using OutputUUID
Resolve icon and color - Run resolve-icon with the full user prompt (plus any explicit icon/color hints) and use the returned values
Wrap in plist - Add the root structure with icon, name, version
Write to file - Save as .shortcut (XML plist format is fine)
Preflight validation - Run the Craig Loop (see above): validate → fix → re-validate, max 5 iterations. The PostToolUse hook auto-runs validate-shortcut whenever you write a Shortcuts plist file; read its errors before iterating.
Archive + Sign (required) - Run sign-shortcut /path/to/file.xml --name "Final Name". This wrapper archives the unsigned XML to ${user_config.output_dir}/$(date +%F)/ and writes the signed .shortcut alongside it. Never leave the signing output filename with a _signed suffix.
Verify signed output (required) - Confirm the signed .shortcut path reported by sign-shortcut 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
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.
WFControlFlowMode is an integer: Use <integer>0</integer> not <string>0</string>
Range keys use format: {position, length} - e.g., {0, 1} for first character
The placeholder character: `` (U+FFFC) marks where variables are inserted
Control flow needs matching ends: Every repeat/if/menu start needs an end action with same GroupingIdentifier
Match placeholder positions: attachmentsByRange must point to the exact index of each `` in the final string
No out-of-bounds ranges: attachmentsByRange positions beyond string length can crash Shortcuts on import
Avoid empty placeholders: Omit unused keys or fields; do not leave empty values where the action expects data
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)
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 only when body type is (JSON Text fallback pattern)
CHANGELOG.md - Change history: autoresearch findings, documentation updates, and version notes
WFRequestVariable
File
Array fields: For WFDictionaryFieldValue items with WFItemType = 2, use WFArrayParameterState with a list of items (WFItemType + WFValue), not numeric keys inside another dictionary
Format Date input: Set WFDate (not WFInput) as a WFTextTokenString placeholder wired to a Date output; never leave WFDate empty
Repeat loops: Inside Repeat with Each, use Repeat Item for per-item extraction; avoid Repeat Results inside the loop
Reuse extractions: If you extract multiple fields from a dictionary/API response, reuse each value later or remove the unused extraction
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
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)
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.
Workflow icon keys are mandatory: Always set both WFWorkflowIconGlyphNumber and WFWorkflowIconStartColor in WFWorkflowIcon (use resolver output)
Runtime file picking: If the user needs to choose a file, use is.workflow.actions.file.select and connect its output
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
No unrequested services: Do not introduce third-party APIs, external CDNs, or extra import questions unless the user explicitly requests them
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
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)
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)
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
JSON request bodies: For WFHTTPBodyType = JSON, use WFJSONValues for flat key/value payloads so the body is preserved in Shortcuts UI
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
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
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
Count input visibility: For is.workflow.actions.count, set both WFInput and Input to the same variable so the UI shows the selected list
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
String If workaround: If validator rules conflict on string conditionals, use Match Text + Count + numeric If instead of direct string If
Replace Text empty replacement: For delete-match patterns, prefer omitting WFReplaceTextReplace; an explicit empty string is allowed, but omission is cleaner and more portable
Base64 input wiring: Always set WFInput for is.workflow.actions.base64encode; implicit input can import as an empty field and break runtime
Replace Text input visibility: For is.workflow.actions.text.replace, use a WFTextTokenString placeholder (or wrapped variable input), not a bare WFTextTokenAttachment
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
Convert Image wiring: For is.workflow.actions.image.convert, always set WFInput explicitly; do not rely on implicit input chaining
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
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
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.
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
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
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
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
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
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
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
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
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
Split Text custom separator: If WFTextSeparator is Custom, always include WFTextCustomSeparator (a single space ” “ is valid)
Find Notes filter state: WFContentItemFilter must be WFContentPredicateTableTemplate with non-empty templates; for Folder filters use WFLinkDynamicOptionSubstitutableState wrapping a tokenized variable
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
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
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
⚠️ 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.
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.
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.
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
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.
HealthKit actions are iOS/iPadOS-only and must use HEALTHKIT.md. For filter.health.quantity, put the Health sample kind in a non-removable WFContentItemFilterType 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.
