app-intents

name	app-intents
description	Expert guidance for the App Intents framework on Apple platforms. Use when developers mention: (1) Siri or Shortcuts integration, (2) AppIntent, AppEntity, AppEnum, or AppShortcutsProvider, (3) Spotlight actions or indexed entities, (4) exposing app features to Apple Intelligence, (5) parameters, parameter summaries, or intent donation, (6) widget/control configuration intents. Not for widget timeline design itself (see widgetkit-live-activities skill).
license	MIT
metadata	{"author":"ulk","version":"1.0","source":"ulk (interne) — extrait des sections natives d'isaac (27), agents/mobile/27-isaac.md","source-version":"ios-26","maintainer":"izo"}

App Intents

Scope: the App Intents framework (iOS 16+, unified surface for Siri, Shortcuts, Spotlight, widgets configuration, interactive widgets, Control Center, Action button, Apple Intelligence). Intent design, entities, queries, App Shortcuts, donation-free discovery. Out of scope: the legacy SiriKit INIntent domains (messaging/CarPlay retain SiriKit), widget timeline mechanics (→ swift-widgetkit-live-activities).

Mental Model

• AppIntent = a verb ("Start timer", "Add expense"). One focused action, performs in-process.
• AppEntity = a noun your app exposes (a project, an order). Identifiable, queryable, displayable.
• EntityQuery = how the system resolves entities (by ID, by string, suggested list).
• AppShortcutsProvider = zero-setup Siri phrases; available the moment the app is installed — no donation needed.
• Everything the system shows (titles, parameter summaries, entity representations) is static metadata read at build time — no network, no user state.

Core Rules (non-negotiable)

1. One intent = one outcome. No mode-switch boolean parameters that change what the intent fundamentally does; ship two intents instead.
2. perform() must be fast and resumable. Target < 10 s (the system cancels laggards). Long work → kick off, return .result(dialog:) describing what started; never block on user-invisible network retries.
3. Declare thread affinity, don't guess it. UI-touching intents: @MainActor func perform(). Everything else stays off the main actor.
4. Titles and summaries are static. static let title / static var parameterSummary cannot depend on runtime state — write them so they read naturally in the Shortcuts editor ("Add ⟨amount⟩ to ⟨budget⟩").
5. Every user-facing entity gets a DisplayRepresentation (title + optional subtitle/image). The raw id must never leak into UI.
6. Queries must handle deleted/stale IDs gracefully — return [], never throw for a missing entity (Shortcuts persist entity IDs for years).
7. Use @Parameter(requestValueDialog:) + needsValueError for missing input instead of failing; Siri then asks a follow-up.
8. App Shortcuts: ≤ 10 per app, every phrase contains \(.applicationName). Phrases are compiled statically — no string interpolation of runtime values (entity parameters use \(\.$param)).
9. openAppWhenRun = true only when the outcome is inherently visual. Background execution is the default and the point of the framework.
10. Never fabricate availability. Interactive widgets need iOS 17; ControlWidget intents iOS 18; Apple Intelligence entity surfacing iOS 18+; interactive snippets iOS 26. Tag versions in code comments when guarding.

Canonical Patterns

Intent + entity + query

struct Project: AppEntity, Sendable {
    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Project"
    static let defaultQuery = ProjectQuery()

    let id: UUID
    let name: String
    var displayRepresentation: DisplayRepresentation { .init(title: "\(name)") }
}

struct ProjectQuery: EntityQuery {
    func entities(for identifiers: [UUID]) async throws -> [Project] {
        await ProjectStore.shared.projects(ids: identifiers)     // missing IDs are simply absent
    }
    func suggestedEntities() async throws -> [Project] {
        await ProjectStore.shared.recentProjects(limit: 5)
    }
}

struct StartTimerIntent: AppIntent {
    static let title: LocalizedStringResource = "Start Timer"
    static var parameterSummary: some ParameterSummary {
        Summary("Start a timer for \(\.$project)")
    }

    @Parameter(title: "Project") var project: Project

    func perform() async throws -> some IntentResult & ProvidesDialog {
        try await TimerService.shared.start(projectID: project.id)
        return .result(dialog: "Timer started for \(project.name).")
    }
}

App Shortcuts (installed = discoverable, zero donation)

struct AppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: StartTimerIntent(),
            phrases: ["Start a timer in \(.applicationName)",
                      "Track \(\.$project) in \(.applicationName)"],
            shortTitle: "Start Timer",
            systemImageName: "timer"
        )
    }
}

String-searchable entities (Spotlight / Siri "find")

Conform the query to EntityStringQuery (entities(matching:)) and, for indexed content, IndexedEntity (iOS 18+) so Spotlight and Apple Intelligence can surface instances without the app running.

Widget configuration intent

WidgetConfigurationIntent is just an AppIntent subprotocol — same parameters/queries; the widget receives it in AppIntentTimelineProvider (see swift-widgetkit-live-activities).

Common AI Mistakes

❌ Generated pattern	Why it fails	✅ Correct
INIntent / Intents extension for new features	Legacy SiriKit; App Intents replaced it (iOS 16+)	AppIntent in the app target
"Donate" calls everywhere (donate(), INInteraction)	App Shortcuts need no donation	AppShortcutsProvider static phrases
Runtime values in phrases	Phrases compile statically → silently unregistered	\(.applicationName) + \(\.$parameter) only
Throwing from entities(for:) on unknown ID	Breaks users' saved Shortcuts	Return the subset that still exists
perform() doing UI work off-main	Crash / undefined	@MainActor on the method
One giant "DoThing" intent with a mode enum	Unusable in Shortcuts editor, un-summarizable	One intent per verb
Dialog text built from unlocalized string concat	Siri reads it aloud, unlocalized	LocalizedStringResource + interpolation

Checklist before shipping

• Each intent has title, parameterSummary, and reads naturally in the Shortcuts editor
• Entities: DisplayRepresentation everywhere, queries survive deleted IDs
• suggestedEntities() returns a helpful, bounded list
• App Shortcut phrases all contain \(.applicationName); ≤ 10 shortcuts
• Background-run by default; openAppWhenRun justified case by case
• Tested from: Shortcuts app, Siri voice, Spotlight — not only in-app
• Version guards for 17+/18+/26-only surfaces (interactive widgets, controls, indexed entities, snippets)