Skip to content

CamilleScholtz/swmpc / .agents/skills/app-intents-specialist

app-intents-specialist

Verified

Authoritative App Intents best practices from Apple: execution model, entities, queries, parameters, enums, dependencies, and donations.

references/factoring.md

View on GitHub
# Factoring: Choosing Types and Intent Granularity

Two modeling decisions get made *before* any `perform()` is written, and both are hard to reverse once a shortcut is saved against them: what kind of type backs each value a user supplies, and where the boundaries between intents fall. Neither is enforced by the compiler — an `AppEnum` stuffed with runtime data compiles exactly like a well-chosen one, and a single intent that branches on an `action` parameter type-checks as cleanly as ten focused intents. The cost shows up later, as stale option lists, bloated build-time metadata, or an action Siri can't phrase. The two sections below cover each decision; the per-symbol traps for each type live in their own files, cross-referenced rather than repeated here.

## Match the value's *nature* to the type — `AppEnum` for fixed sets, `AppEntity` for queryable data, plain `@Parameter` for free-form input

Three type families back a value a user supplies, and the choice is dictated by *where the set of valid values comes from*, not by how you want it to look in the picker:

- **`AppEnum`** — a set that is FIXED and KNOWN AT COMPILE TIME. The protocol is literally built on `CaseIterable` (`StaticDisplayRepresentable` refines `CaseDisplayRepresentable: CaseIterable`), and the framework's options provider just returns `Array(Enum.allCases)`. Sizes, priorities, sort orders, on/off states.
- **`AppEntity` + an `EntityQuery`** — DYNAMIC, queryable data: rows from a database, results from the network, anything the user created. The valid set is discovered at runtime by the query, not baked into the binary.
- **A plain `@Parameter` of a standard type** (`String`, `Int`, `Bool`, `Date`, a `Measurement`) — FREE-FORM input the user types or dictates, with no enumerable "set of choices" at all.

The common mistake is reaching for `AppEnum` because it is the quickest way to get a selectable list, then filling it with data that varies at runtime.

```swift
// AVOID: an AppEnum standing in for dynamic data. Playlists are user data — they
// change constantly. But AppEnum is CaseIterable, so this list is frozen into the
// binary at build time: the metadata processor extracts every case into the
// app's .actionsdata. New playlists never appear; deleted ones linger as stale
// options; the whole set bloats the shipped metadata. It compiles fine — that's
// the trap.
enum Playlist: String, AppEnum {
    case chillVibes
    case workout
    case roadTrip
    // …regenerated by hand every time the user makes a playlist?  ❌

    static let caseDisplayRepresentations: [Playlist: DisplayRepresentation] = [
        .chillVibes: "Chill Vibes", .workout: "Workout", .roadTrip: "Road Trip",
    ]
}
```

```swift
// PREFER: an AppEntity backed by a query for anything queryable. The valid set is
// fetched live, so it is always current, and only the *type shape* — not the data
// — goes into the metadata. Use AppEnum only for genuinely fixed sets like this
// RepeatMode, whose cases are a closed vocabulary the compiler already knows.
struct Playlist: AppEntity {
    static let defaultQuery = PlaylistQuery()   // discovers valid values at runtime
    var id: UUID
    @Property(title: "Name") var name: String
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(name)") }
}

enum RepeatMode: String, AppEnum {              // genuinely fixed → AppEnum is right
    case off, one, all
    static let caseDisplayRepresentations: [RepeatMode: DisplayRepresentation] = [
        .off: "Off", .one: "Repeat One", .all: "Repeat All",
    ]
}
```

The opposite mistake also happens: modeling free-form input as an entity (a `SearchTermEntity`, a `DurationEntity`) when the user is really just typing text or a number. If there is no meaningful "set of instances to pick from," it is a plain `@Parameter var query: String` or `@Parameter var minutes: Int`, not an entity. Reserve `AppEntity` for things the user could *browse and select*. The per-symbol traps — how `AppEnum` raw values persist, how an `AppEntity`'s `id` must be stable, how the two `EntityQuery` entry points differ — are in `app-enum.md` and `entities-and-queries.md`; parameter-resolution mechanics are in `parameters.md`.

## One intent per atomic user task — not a mega-intent that branches on an `action` parameter

The whole system reasons at the *intent* level. Siri phrases, App Shortcut trigger phrases, Shortcuts' action library, and prediction all key off the individual `AppIntent` type and its `title`. A single intent that takes an `action` enum and switches on it inside `perform()` collapses several user-facing actions into one opaque box the system can only offer as one entry with one title — so "create a note" and "delete a note" become indistinguishable to everything upstream of your code.

```swift
// AVOID: a mega-intent multiplexing distinct tasks through an enum. The system
// sees ONE action titled "Manage Note." It cannot surface "Delete Note" as its
// own Shortcuts action, cannot predict it independently, and cannot map a spoken
// "delete my note" phrase to it — because at the intent level there is only the
// umbrella. The `note` parameter is also meaningless for `.create`, so the
// parameter summary can't read cleanly for every branch.
struct ManageNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Manage Note"

    enum Action: String, AppEnum {
        case create, delete
        static let caseDisplayRepresentations: [Action: DisplayRepresentation] = [
            .create: "Create", .delete: "Delete",
        ]
    }

    @Parameter var action: Action
    @Parameter var note: NoteEntity?      // unused when action == .create

    func perform() async throws -> some IntentResult {
        switch action {                    // branching hides two tasks in one intent
        case .create: /* … */ break
        case .delete: /* … */ break
        }
        return .result()
    }
}
```

```swift
// PREFER: one intent per atomic task. Each has its own title the system can name,
// phrase, predict, and list independently, and each carries only the parameters
// that task actually needs — so every parameter summary reads correctly.
struct CreateNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Create Note"
    @Parameter(title: "Title") var title: String
    func perform() async throws -> some IntentResult { /* … */ .result() }
}

struct DeleteNoteIntent: AppIntent {
    static let title: LocalizedStringResource = "Delete Note"
    @Parameter var note: NoteEntity
    func perform() async throws -> some IntentResult { /* … */ .result() }
}
```

Split on the *verb the user would say*, not on incidental code sharing. If two intents share logic, factor that into a helper the app owns and call it from both `perform()` bodies — do not merge the intents to avoid duplication. An intent whose title needs "and/or" or whose parameter set is only partly relevant depending on another parameter is usually two intents wearing one.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall