app-intents

App Intents — Siri, Shortcuts, Spotlight & Apple Intelligence

The App Intents framework exposes your app's actions and content to the system: Siri, Apple Intelligence, the Shortcuts app, Spotlight, Visual Intelligence, the Action Button (iPhone 15 Pro+/16+), the Apple Pencil Pro squeeze, Control Center / Lock Screen, and interactive widgets / Live Activities — all from plain Swift structs, no .intentdefinition files, no code generation.

• Platforms: iOS 26+, iPadOS 26+, macOS 26+, visionOS 26+, watchOS, tvOS (surface availability varies; Siri/Spotlight/Action-Button are iPhone/iPad/Mac).
• Import: import AppIntents.
• Three core types: AppIntent (an action), AppEntity (a dynamic value), AppEnum (a fixed set). Discoverability comes from AppShortcutsProvider and/or the @AppIntent(schema:) assistant-schema macro.

The one mental model that explains everything: build-time metadata

App Intents uses build-time metadata extraction. At compile time your Swift source is read into an .appintentsmetadata bundle inside your app. The system reads that bundle without running your app — which is why your intents, entities, and shortcuts are available the instant the app is installed, and why half the framework's constraints exist:

• Titles / type-display-representations / case-display-representations MUST be compile-time constants (static let, string literals). A computed property or function call fails to build with "Expression is not a string literal".
• Renaming an AppIntent/AppEntity struct is a BREAKING CHANGE. The struct name is the stable identity — renaming invalidates every Shortcut a user already built, and every donated Spotlight entry. Treat the name like a public API.
• Each target is processed independently. Share intent types across app + extension + Swift Package via AppIntentsPackage (see references/architecture-and-targets.md).

Carry this model first; it pre-empts most build errors.

When to use this skill

• Creating or modifying any AppIntent, AppEntity, AppEnum, or EntityQuery.
• Adding Siri, Shortcuts, Spotlight, or Apple Intelligence support.
• Building AppShortcutsProvider / App Shortcuts and Siri phrases.
• Implementing interactive snippets (SnippetIntent), Control Center controls, Action-Button capture, or Visual Intelligence image search.
• Deciding whether an intent should foreground the app (IntentModes).
• Migrating from SiriKit (INIntent / .intentdefinition).
• Debugging build errors, "intent not in Shortcuts", "entity not found", snippet crashes, dependency-nil crashes.

A minimum-viable intent (the shape of everything)

import AppIntents

struct AddToFavoritesIntent: AppIntent {
    static let title: LocalizedStringResource = "Add to Favorites"   // MUST be constant

    @Parameter(title: "Landmark", requestValueDialog: "Which landmark?")
    var landmark: LandmarkEntity

    @Dependency var store: FavoritesStore                            // injected, see below

    static var parameterSummary: some ParameterSummary {
        Summary("Add \(\.$landmark) to favorites")
    }

    func perform() async throws -> some IntentResult & ProvidesDialog {
        try await store.addFavorite(landmark.id)                     // thin bridge — logic lives in the store
        return .result(dialog: "Added \(landmark.name) to favorites.")
    }
}

Register dependencies as early as possible — in App.init(), never onAppear:

@main struct MyApp: App {
    init() { AppDependencyManager.shared.add { FavoritesStore() } }
}

If you register too late, any intent that runs before that point crashes with a nil dependency. This is one of the most common production crashes — see references/troubleshooting.md.

Five rules that prevent the most common bugs

1. perform() is the ONLY place for side effects. Never mutate state in init; entities are constructed constantly (in queries + parameter resolution).
2. Entity IDs must be persistent and stable. var id: UUID { UUID() } is a bug — it mints a new id every read, so the system can never re-resolve a stored reference ("Entity not found"). Use a durable id (landmark.databaseID).
3. Let cancellation throw. When the user cancels requestConfirmation / requestChoice, the call throws — let it propagate. Catching it and returning .result(dialog: "Cancelled") is a documented bug that swallows the system's cancel semantics.
4. Every App Shortcut phrase must include \(.applicationName), with at most one @Parameter per phrase. (Full phrase rules: references/shortcuts-and-siri.md.)
5. Don't mutate state in a SnippetIntent.perform() — it runs multiple times per lifecycle. Snippet performs must be read-only. (Full update-cycle: references/interactive-snippets.md.)

Decision compass

Which protocol should my intent conform to?

Need	Protocol
A basic action	AppIntent
Open the app to show content	OpenIntent (+ TargetContentProvidingIntent for declarative nav)
Render an interactive view inline	SnippetIntent
Support the system undo gesture	UndoableIntent (iOS 26)
Control Center / Lock-Screen control	ControlConfigurationIntent (needs a Widget Extension)
Action-Button locked-camera capture	CameraCaptureIntent (needs a Locked Camera Capture Extension)
Audio capture	AudioRecordingIntent
Match an Apple-Intelligence domain	@AppIntent(schema:) macro (NOT protocol inheritance)

Which entity type? Fixed compile-time set → AppEnum. Dynamic set → AppEntity. Spotlight-searchable → AppEntity + IndexedEntity. A single global instance → UniqueAppEntity. A file → FileEntity. Image-searchable → AppEntity + Transferable + OpenIntent.

Which query type? All values fit in memory → EnumerableEntityQuery. Text search → EntityStringQuery. Property filtering (auto-enables Shortcuts' Find/Filter) → EntityPropertyQuery. ID-lookup only → EntityQuery (base). Visual-Intelligence image search → IntentValueQuery.

@Property vs @ComputedProperty vs @DeferredProperty?

Property type	When	Overhead
@Property	Value stored on the entity struct	Low
@ComputedProperty (iOS 26)	Derived from a source of truth (model, UserDefaults) — prefer this, no duplication	Low
@DeferredProperty (iOS 26)	Expensive (network / heavy I/O) — async getter, called only when the system asks	Lowest (lazy)

Load-bearing performance rule: entities must be cheap to create. Never do network work in init — push it into a @DeferredProperty. (Details: references/entities-and-queries.md.)

Does this intent need to open the app? → pick an IntentModes value (supportedModes). OpenIntent foregrounds automatically — do not set supportedModes on it. (Full mode table + continueInForeground: references/intent-fundamentals.md.)

iOS 26 currency flags (use these, not the deprecated forms)

• static let supportedModes: IntentModes replaces the old static var openAppWhenRun: Bool for foreground control. .background / .foreground / [.background, .dynamic] / [.background, .deferred].
• @AppIntent / @AppEntity / @AppEnum macros replace the deprecated @AssistantIntent / @AssistantEntity / @AssistantEnum.
• App Intents can live in Swift Packages and static libraries (no longer main-app-only).
• @ComputedProperty / @DeferredProperty are new iOS-26 entity property kinds.
• SnippetIntent (interactive), UndoableIntent, requestChoice, structured IntentDialog(full:supporting:), TargetContentProvidingIntent + .onAppIntentExecution, macOS-Spotlight inline execution — all iOS 26.

References

• references/intent-fundamentals.md — AppIntent, @Parameter, parameterSummary, return-type composition, dialog, IntentModes/supportedModes + continueInForeground, @Dependency, OpenIntent, UndoableIntent, requestChoice, requestConfirmation (+ conditions), requestValue, authenticationPolicy, custom errors, AppIntentError.
• references/entities-and-queries.md — AppEntity, AppEnum, the property-kind decision, the full EntityQuery family (Enumerable/String/Property), suggestedEntities(), Transferable, @UnionValue, FileEntity, UniqueAppEntity, URLRepresentableIntent/Entity.
• references/shortcuts-and-siri.md — AppShortcutsProvider, phrase rules, parameterized vs generic shortcuts, NegativeAppShortcutPhrases, updateAppShortcutParameters(), SiriTipView, ShortcutsLink, ShortcutTileColor, dialog/confirmation, surfaces (Action Button / Pencil Pro).
• references/spotlight-indexing.md — IndexedEntity, indexing-key tables, the two donation APIs, the donation lifecycle, OpenIntent-tap handling, auto-generated Find/Filter, macOS-Spotlight inline execution.
• references/interactive-snippets.md — SnippetIntent, the 6-step update cycle, Button(intent:)/Toggle(isOn:intent:), confirmation snippets, snippet chaining, reload(), the "model entities not values" + "read-only perform" rules.
• references/apple-intelligence-and-visual.md — the @AppIntent(schema:) macro, the full app-intent-domain catalog (Mail/Photos/Browser/… with action/entity/enum lists), Visual Intelligence image search (IntentValueQuery / SemanticContentDescriptor), on-screen entities for Siri/ChatGPT, PredictableIntent, AttributedString rich-text gotcha.
• references/system-integrations.md — ControlConfigurationIntent, CameraCaptureIntent, AudioRecordingIntent and their extension-target requirements.
• references/architecture-and-targets.md — intent-driven architecture (thin-bridge intents), TargetContentProvidingIntent + onAppIntentExecution declarative navigation, scene handling, AppDependencyManager, AppIntentsPackage cross-target sharing.
• references/migration-from-sirikit.md — INIntent / .intentdefinition / INObject / INShortcut → App Intents mapping, before/after Swift, coexistence.
• references/testing.md — unit-testing intents/queries as plain structs, mocking via AppDependencyManager, what can only be tested on device.
• references/troubleshooting.md — error→cause→fix for every build/runtime issue, the find …/*.appintentsmetadata + subsystem:com.apple.appintents Console workflow, and the diagnostics table.

WWDC: 2025-244 (Explore the App Intents framework), plus the assistant-schema and Visual-Intelligence sessions. Apple docs: /AppIntents, /AppIntents/app-intent-domains.