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/configuration-intents.md
View on GitHub# Configuration Intents: Describing a Widget or Control, Not Running One
`WidgetConfigurationIntent` (iOS 17) and `ControlConfigurationIntent` (iOS 18 / macOS 26) look like ordinary `AppIntent`s — they conform to `AppIntent`, they carry `@Parameter`s, they have a `title` — but they are *not* actions. They exist so WidgetKit can render a configuration screen: each `@Parameter` becomes one editable field in the widget-editing sheet or the Control Center picker, and the chosen values are handed back to your `TimelineProvider` / control provider to build the view. Nothing "runs." The framework supplies a default `perform()` for both protocols that immediately throws (returning `Never`), precisely so you never write one — the compiler will happily let you add your own, which is the whole trap. The sections below cover the mistakes that follow from treating a configuration intent as if it executed.
## The `@Parameter`s ARE the whole intent — don't add a `perform()` to "make it work"
A configuration intent's job is finished the moment its parameters are declared. The protocol already carries a default `perform()` (its result type is `Never`), so the type compiles and drives the configuration UI with an empty body. Writing your own `perform()` is not required and does not "activate" anything — at best it is dead code the system won't call as an action, at worst it hides real logic somewhere it will never run for a widget.
```swift
// AVOID: adding a perform() because the type "felt incomplete" without one, then
// putting the widget's data-loading in it. This body never runs to render the
// widget — WidgetKit reads the @Parameter values and calls your TimelineProvider;
// it does NOT execute the configuration intent as an action. The fetch here is
// dead on the widget path, and the .result() return type even fights the
// protocol's own Never-returning default. It compiles, so nothing warns you.
struct FavoriteBookConfig: WidgetConfigurationIntent {
static let title: LocalizedStringResource = "Favorite Book"
@Parameter(title: "Book") var book: BookEntity?
func perform() async throws -> some IntentResult { // ❌ never invoked for the widget
let cover = try await CoverLoader.load(for: book) // dead code on the render path
return .result()
}
}
```
```swift
// PREFER: parameters only. The @Parameters are the configuration surface; the
// framework's default perform() (returning Never) stands in, and WidgetKit passes
// the resolved values to your TimelineProvider, which does the actual data loading.
// Nothing to run, nothing to return.
struct FavoriteBookConfig: WidgetConfigurationIntent {
static let title: LocalizedStringResource = "Favorite Book"
static let description = IntentDescription("Shows your favorite book.")
@Parameter(title: "Book") var book: BookEntity?
// no perform() — the timeline provider reads `book` and builds the view
}
```
The one legitimate reason to write `perform()` is to *reuse the same type* as a real, runnable action elsewhere. If you are not doing that, leave it off.
## A control that toggles a value is a `SetValueIntent` action — separate from the control's `ControlConfigurationIntent`
Control Center controls have two intents with two different jobs, and conflating them is common. `ControlConfigurationIntent` *describes* the control (which thing it points at — a specific Focus, a particular device); it has no `perform()`. The action the control fires when tapped — flipping a toggle, setting a level — is a real, runnable intent, and for the on/off case that is `SetValueIntent`, which very much *does* implement `perform()`.
```swift
// AVOID: trying to make the configuration intent do the toggling. A
// ControlConfigurationIntent has no perform() the system will run on tap, so the
// side effect below is orphaned — the control configures fine but never toggles.
struct SilentModeControl: ControlConfigurationIntent {
static let title: LocalizedStringResource = "Silent Mode"
@Parameter(title: "On") var isOn: Bool
func perform() async throws -> some IntentResult { // ❌ not the control's tap action
SilentMode.shared.set(isOn); return .result()
}
}
```
```swift
// PREFER: keep the two roles in two types. The SetValueIntent is the runnable
// action WidgetKit ties to the control's value; its perform() carries the real
// logic. If the control needs to point at a specific target, THAT selection is
// what a ControlConfigurationIntent's @Parameters describe.
struct ToggleSilentMode: SetValueIntent {
static let title: LocalizedStringResource = "Silent Mode"
@Parameter(title: "Silent") var value: Bool
func perform() async throws -> some IntentResult { // ✅ runs on tap
SilentMode.shared.set(value); return .result()
}
}
```
`SetValueIntent` is a normal action intent and follows the ordinary execution rules in `execution-model.md`; only the *configuration* half is the no-`perform()` case. Which parameters belong on the configuration intent — optional vs. defaulted so the system can preview the control before setup — is a parameter-design question covered in `parameters.md`, and whether a distinct configuration surface even warrants its own type is the granularity question in `factoring.md`.
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 |