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/parameters.md
View on GitHub# Parameters and Resolution
`@Parameter` looks like a plain stored property, but its resolution is a small state machine the framework drives before and during `perform()` — and four of its behaviors contradict the property-wrapper mental model. A missing value can be resolved *inline* or by *restarting* `perform()`, and the two spellings are not interchangeable. A non-optional parameter does not always throw when unfilled — sometimes the framework silently asks the user to pick. Options that depend on another parameter cannot read that parameter directly. And a parameter you never name in your `Summary` simply does not appear in the Shortcuts editor. Each has a distinct trap; the sections below cover all four. (Restart semantics and flow-control-vs-failure are `execution-model.md`'s domain — this file assumes them.)
## Resolve a missing value inline with `requestValue`, or restart with `needsValueError` — they are not the same
Both `$param.requestValue(_:)` and `$param.needsValueError(_:)` prompt the user for a value, but they run at opposite ends of a spectrum. `requestValue(_:)` is `async` — you `await` it and it returns the resolved value *inline*, so the code after it keeps running in the same `perform()` invocation. `needsValueError(_:)` returns an `AppIntentError` you `throw` — it aborts the current pass and re-runs `perform()` from the top with the value now filled. Reach for the wrong one and you either can't get a value where you need it, or you silently opt into a restart (and its replay hazard).
```swift
// AVOID: throwing needsValueError to get a value you need *right here*. This
// doesn't return the value — it aborts and restarts perform() from the top, so
// the two lines below never run on this pass. Worse, any side effect already
// committed this pass replays on the restart.
func perform() async throws -> some IntentResult {
try await log.append("starting split") // committed…
guard let payer else {
throw $payer.needsValueError("Who paid?") // …restart replays the append
}
let share = try await splitService.compute(for: payer)
return .result(value: share)
}
```
```swift
// PREFER: requestValue when you need the value inline. It's async — await it and
// the resolved value flows into the same invocation; nothing restarts, nothing
// replays. Reserve needsValueError for when a restart is what you actually want.
func perform() async throws -> some IntentResult {
let payer = try await $payer.requestValue("Who paid?") // returns inline
try await log.append("starting split")
let share = try await splitService.compute(for: payer)
return .result(value: share)
}
```
Do not reach for the old `requestValue(_:) -> Error` spelling that returns an `Error` to throw — it is `@available(*, deprecated)` and its message points you at exactly these two replacements. If a `requestValue` call returns something you `throw` rather than a value you `await`, you are on the deprecated overload.
## A non-optional `AppEnum` parameter auto-disambiguates — it does not throw a needs-value error
The rule "an unfilled non-optional `@Parameter` throws a needs-value error" is only half true. When such a parameter's type is an `AppEnum`, the framework instead gathers the enum's options and *auto-disambiguates*: with more than one option it asks the user to pick; with exactly one option it silently assigns that option and moves on. Only non-enum non-optional parameters fall through to a plain needs-value error. So a summary/dialog you write assuming "the user will be asked to type a value" is wrong for enums — they get a picker, driven by your `requestDisambiguationDialog`, not your `requestValueDialog`.
```swift
// AVOID: relying on a needs-value prompt for a non-optional AppEnum, and leaving
// the disambiguation dialog unset. The framework auto-disambiguates a multi-case
// enum with a *picker*, and falls back to a generic dialog — the user sees no
// useful prompt. (And a single-case enum is auto-assigned with no prompt at all.)
struct SetPriorityIntent: AppIntent {
static let title: LocalizedStringResource = "Set Priority"
@Parameter(title: "Priority")
var priority: TaskPriority // AppEnum: .low, .medium, .high
// ...
}
```
```swift
// PREFER: provide requestDisambiguationDialog — that's the prompt the auto-
// disambiguation actually uses for a multi-case AppEnum. requestValueDialog is
// the wrong slot for an enum; it's the fallback for non-enum types.
struct SetPriorityIntent: AppIntent {
static let title: LocalizedStringResource = "Set Priority"
@Parameter(
title: "Priority",
requestDisambiguationDialog: "Which priority level?"
)
var priority: TaskPriority
// ...
}
```
The single-case corollary matters for review: an `AppEnum` (or dynamic options list) that resolves to exactly one option is assigned with no user interaction, so any UI you expected around "the user chose the priority" never happens.
## Options that depend on another parameter need `@IntentParameterDependency` — you cannot read the sibling `@Parameter`
Inside a `DynamicOptionsProvider` or `EntityQuery`, the enclosing intent's other `@Parameter`s are not yet filled — reading them gives you nothing usable, because option-fetching runs *before* full resolution. To base one parameter's options on another's chosen value, declare an `@IntentParameterDependency<TheIntent>(\.$otherParam)` inside the provider/query and read the depended-on value through its projection. This is the only supported channel for cross-parameter option logic.
```swift
// AVOID: trying to read a sibling parameter's value from inside the query. There
// is no instance of the intent to read here, and the value isn't resolved yet at
// options-fetch time — so this can't compile against the intent's parameters and
// has nothing to read even conceptually.
struct RoomQuery: EntityStringQuery {
func entities(matching string: String) async throws -> [RoomEntity] {
let building = /* ??? no access to BookRoomIntent.$building here */
return try await RoomStore.rooms(in: building, matching: string)
}
}
```
```swift
// PREFER: declare the dependency; read the other parameter through its projection.
struct RoomQuery: EntityStringQuery {
@IntentParameterDependency<BookRoomIntent>(\.$building)
var bookRoom
func entities(matching string: String) async throws -> [RoomEntity] {
guard let bookRoom else { return [] } // building not yet chosen
return try await RoomStore.rooms(in: bookRoom.building, matching: string)
}
}
```
Guard the optional projection (`guard let bookRoom else { return [] }`) as shown — if the depended-on parameter is unset, the projection is unavailable and returning empty options is the graceful path. Do not force-unwrap the projected member: the wrapper `fatalError`s if you read a key path you did not list in the `@IntentParameterDependency`, so list every parameter you intend to read.
## Only parameters named in `Summary` show in the Shortcuts editor
`ParameterSummary` is not cosmetic — it is the allowlist for which parameters the Shortcuts editor surfaces. A parameter interpolated into the `ParameterSummaryString` (the `"…\(\.$param)…"` form) is shown; one added through the trailing `@ParameterKeyPathsBuilder` block of `Summary(_:)` is shown; every other `@Parameter` is silently omitted from the editor UI, even though it still exists and still resolves. So a parameter that "isn't editable in Shortcuts" is usually a parameter you forgot to mention in the summary — not a bug.
```swift
// AVOID: a summary that mentions only some parameters. `note` is interpolated so
// it shows; `folder` and `isPinned` are never named anywhere in the summary, so
// they simply don't appear in the Shortcuts editor — users can't set them.
static var parameterSummary: some ParameterSummary {
Summary("Save \(\.$note)")
}
@Parameter(title: "Note") var note: String
@Parameter(title: "Folder") var folder: FolderEntity
@Parameter(title: "Pinned") var isPinned: Bool
```
```swift
// PREFER: interpolate the parameters that belong in the sentence, and list the
// rest in the trailing key-path block so they still surface as editable rows.
static var parameterSummary: some ParameterSummary {
Summary("Save \(\.$note) to \(\.$folder)") {
\.$isPinned
}
}
```
If a parameter should be user-configurable in Shortcuts, it must appear in the summary one way or the other. Omission is a valid choice for parameters that are only ever filled programmatically (e.g. from a preceding intent's output) — but make it a deliberate 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: 194k | 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: 194k | 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: 194k | Updated | Claude CodeCodex | Verified | Install |