siri-shortcut-editing

Files (4)

• SKILL.md
• action-identifiers.md · references/
• dictionary-actions.md · references/
• decode_shortcut.py · scripts/

SKILL.md (first lines)

# Siri Shortcut Editing Skill

Edit signed macOS Siri Shortcuts (`.shortcut` files) by decoding them to XML, making changes, and re-signing.

## File Format

A `.shortcut` file is a **signed Apple Encrypted Archive (AEA1)** containing:

```
[0-3]     "AEA1" magic
[4-7]     zeros (reserved)
[8-11]    plist length (uint32 LE)
[12-...]  auth plist (bplist) — signing certificate chain
[after]   CMS signature + encrypted payload (Apple Archive)
```

The actual shortcut workflow is a bplist inside the Apple Archive, named `Shortcut.wflow`.

## Prerequisites

- macOS with `aea`, `aa`, `shortcuts` CLI tools (all built-in)
- `plutil` (built-in)
- Python 3 with `plistlib` (built-in)

Verify:
```bash
which aea aa shortcuts plutil python3
```

---

## Workflow: Decode .shortcut → XML

Use the bundled `scripts/decode_shortcut.py`:

```bash
python3 scripts/decode_shortcut.py INPUT.shortcut OUTPUT.xml
```

This script performs all three steps automatically:
1. Extracts the signing certificate's public key from the AEA1 auth plist
2. Decrypts the Apple Archive via `aea decrypt -profile 0`
3. Locates the embedded bplist inside the decoded archive and converts to XML

If doing it manually, the steps are:

### Step 1: Extract signing certificate public key

The first 12 bytes of a `.shortcut` file are the AEA1 header (magic + zeros + plist length as uint32 LE). The auth plist starts at byte 12. Parse it, grab the leaf certificate from `SigningCertificateChain`, derive the public key with `openssl x509`.

### Step 2: Decrypt the Apple Archive

```bash
aea decrypt -profile 0 -sign-pub /tmp/signing_pub.pem \
  -i INPUT.shortcut -o /tmp/decoded.bin
```

### Step 3: Extract bplist → XML

The decoded archive starts with `AA01` metadata; the actual workflow bplist is embedded further in. Find the `bplist` marker and parse from there with `plistlib`.

---

## Workflow: Edit & Re-sign XML → .shortcut

> **⚠️ `shortcuts sign` requires the input file to use a `.wflow` extension, otherwise it fails.**

### Step 1: Convert XML back to bplist

```bash
plutil -convert binary1 -o /tmp/workflow.wflow OUTPUT.xml
```

### Step 2: Sign the shortcut

```bash
shortcuts sign -m anyone \
  -i /tmp/workflow.wflow \
  -o OUTPUT.shortcut
```

`shortcuts sign` accepts a bare bplist (old-format shortcut) and automatically wraps it in the AEA1 Apple Archive format with a new CMS signature.

Signing modes:
- `-m anyone` — anyone can import the shortcut
- `-m people-who-know-me` — only your contacts (default)

---

## XML Structure Overview

Key keys in the shortcut plist:

| Key | Description |
|-----|-------------|
| `WFWorkflowActions` | Array of action dicts — the core logic |
| `WFWorkflowActionIdentifier` | Action type, e.g. `is.workflow.actions.gettext` |
| `WFWorkflowActionParameters` | Per-action parameters |
| `WFWorkflowTypes` | Where shortcut appears (e.g. `WFWorkflowTypeShowInSearch`) |
| `WFWorkflowInputContentItemClasses` | Accepted input types |
| `WFWorkflowOutputContentItemClasses` | Output types |
| `WFWorkflowMinimumClientVersion` | Minimum iOS/macOS version |
| `WFWorkflowIcon` | Icon glyph & color |

### Variable References

There are **two distinct ways** to reference a value from earlier in the workflow. They use different fields and are NOT interchangeable:

| Reference Type | `Type` value | Required fields | When to use |
|---|---|---|---|
| **Action Output** | `ActionOutput` | `OutputUUID` + `OutputName` | Source action has a named output (CustomOutputName + UUID) |
| **Named Variable** | `Variable` | `VariableName` | Source is a `SetVariable` action (which has NO UUID on its output) |

Both types use `WFSerializationType=WFTextTokenAttachment`. This applies both in `WFInput` fields and in inline `attachmentsByRange` within `WFTextTokenString` strings.

Literal strings use `WFTextTokenString` with `string` field.

---

From Jansen611/Agent-Skills, MIT.

More from Jansen611/Agent-Skills