CamilleScholtz/swmpc / .agents/skills/app-intents-specialist
app-intents-specialist
VerifiedAuthoritative App Intents best practices from Apple: execution model, entities, queries, parameters, enums, dependencies, and donations.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.8 KB |
| references/app-enum.md | markdown | 4.9 KB |
| references/app-shortcut-phrases.md | markdown | 9.2 KB |
| references/configuration-intents.md | markdown | 5.2 KB |
| references/dependencies.md | markdown | 8.2 KB |
| references/donation.md | markdown | 3.5 KB |
| references/entities-and-queries.md | markdown | 10.5 KB |
| references/entity-property-queries.md | markdown | 9.4 KB |
| references/execution-model.md | markdown | 8.6 KB |
| references/factoring.md | markdown | 6.9 KB |
| references/localization.md | markdown | 6.4 KB |
| references/parameter-summaries.md | markdown | 8.1 KB |
| references/parameters.md | markdown | 8.5 KB |
| references/results-and-errors.md | markdown | 5.1 KB |
| references/url-representation.md | markdown | 9.5 KB |
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |