app-intents

dpearson2699/swift-ios-skillsConversational AIAudit passedSnapshot 86b68083fe8a

Installs: 0

Summary

Implement App Intents for Siri, Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence on iOS. Covers AppIntent actions, AppEntity and EntityQuery models, AppShortcutsProvider phrases, IndexedEntity Spotlight indexing, WidgetConfigurationIntent, SnippetIntent, and assistant schemas. Use when exposing app actions or entities to system surfaces.

SKILL.md

App Intents (iOS 26+)

Implement, review, and extend App Intents to expose app functionality to Siri, Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence.

Triage Workflow
AppIntent Protocol
@Parameter
AppEntity
EntityQuery (4 Variants)
AppEnum
AppShortcutsProvider
System Surface Integration
iOS 26 Additions
Common Mistakes
Review Checklist
References

Triage Workflow

Step 1: Choose the action, boundary, and surface

Start from 1-3 valuable actions people want outside the app, not from its screen hierarchy. Record one design row per action: user goal; inline result or app destination; shared domain operation; parameters and entity query; confirmation/authentication; target surface and protocol. Use one explicit runtime route for app handoff instead of scattering navigation side effects through intents.

Then choose the system feature and protocol that fit that action:

Surface	Protocol	Since
Siri / Shortcuts	`AppIntent`	iOS 16
Configurable widget

struct OrderSoupIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Soup"
    static var description = IntentDescription("Place a soup order.")

    @Parameter(title: "Soup") var soup: SoupEntity
    @Parameter(title: "Quantity", default: 1) var quantity: Int

    static var parameterSummary: some ParameterSummary {
        Summary("Order \(\.$soup)") { \.$quantity }
    }

    func perform() async throws -> some IntentResult {
        try await OrderService.shared.place(soup: soup.id, quantity: quantity)
        return .result(dialog: "Ordered \(quantity) \(soup.name).")
    }
}

// Required; the system asks for a value when needed
@Parameter(title: "Count")
var count: Int

// Required and pre-filled
@Parameter(title: "Count", default: 1)
var count: Int

// Optional; request it yourself if it becomes necessary
@Parameter(title: "Count")
var count: Int?

// Basic
@Parameter(title: "Name")
var name: String

// With default
@Parameter(title: "Count", default: 5)
var count: Int

// Numeric slider
@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0, 100))
var volume: Int

// Options provider (dynamic list)
@Parameter(title: "Category", optionsProvider: CategoryOptionsProvider())
var category: Category

// File with content types
@Parameter(title: "Document", supportedContentTypes: [.pdf, .plainText])
var document: IntentFile

// Measurement with unit
@Parameter(title: "Distance", defaultUnit: .miles, supportsNegativeNumbers: false)
var distance: Measurement<UnitLength>

struct SoupEntity: AppEntity {
    static let defaultQuery = SoupEntityQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Soup"
    var id: String

    @Property(title: "Name") var name: String
    @Property(title: "Price") var price: Double

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)", subtitle: "$\(String(format: "%.2f", price))")
    }

    init(from soup: Soup) {
        self.id = soup.id; self.name = soup.name; self.price = soup.price
    }
}

struct SoupEntityQuery: EntityQuery {
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
    func suggestedEntities() async throws -> [SoupEntity] {
        SoupStore.shared.featured.map { SoupEntity(from: $0) }
    }
}

struct SoupStringQuery: EntityStringQuery {
    func entities(matching string: String) async throws -> [SoupEntity] {
        SoupStore.shared.search(string).map { SoupEntity(from: $0) }
    }
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
}

struct AllSoupsQuery: EnumerableEntityQuery {
    func allEntities() async throws -> [SoupEntity] {
        SoupStore.shared.allSoups.map { SoupEntity(from: $0) }
    }
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
}

struct AppSettingsEntity: UniqueAppEntity {
    static let defaultQuery = AppSettingsQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Settings"
    var displayRepresentation: DisplayRepresentation { "App Settings" }

    var id: String { "app-settings" }
}

struct AppSettingsQuery: UniqueAppEntityQuery {
    func uniqueEntity() async throws -> AppSettingsEntity {
        AppSettingsEntity()
    }
}

enum SoupSize: String, AppEnum {
    case small, medium, large

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Size"

    static var caseDisplayRepresentations: [SoupSize: DisplayRepresentation] = [
        .small: "Small",
        .medium: "Medium",
        .large: "Large"
    ]
}

// Valid, but less readable in saved shortcuts and URL representations
enum Priority: Int, AppEnum {
    case low = 1, medium = 2, high = 3
}

// Preferred
enum Priority: String, AppEnum {
    case low, medium, high
    // ...
}

struct MyAppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OrderSoupIntent(),
            phrases: [
                "Order \(\.$soup) in \(.applicationName)",
                "Get soup from \(.applicationName)"
            ],
            shortTitle: "Order Soup",
            systemImageName: "cup.and.saucer"
        )
    }

    static var shortcutTileColor: ShortcutTileColor = .navy
}

struct OrderStatusSnippet: SnippetIntent {
    static var title: LocalizedStringResource = "Order Status"
    func perform() async throws -> some IntentResult & ShowsSnippetView {
        let status = await OrderTracker.currentStatus()
        return .result(view: OrderStatusSnippetView(status: status))
    }
}

struct CheckOrderStatusIntent: AppIntent {
    static var title: LocalizedStringResource = "Check Order Status"
    func perform() async throws -> some IntentResult & ShowsSnippetIntent {
        .result(snippetIntent: OrderStatusSnippet())
    }
}

@available(iOS 26, *)
@UnionValue
enum ShoppingVisualResult {
    case product(ProductEntity)
    case store(StoreEntity)
}

@available(iOS 26, *)
struct ShoppingVisualQuery: IntentValueQuery {
    func values(for input: SemanticContentDescriptor) async throws -> [ShoppingVisualResult] {
        try Task.checkCancellation()
        async let productMatches = ProductStore.shared.matches(
            labels: input.labels,
            pixelBuffer: input.pixelBuffer,
            limit: 5
        )
        async let storeMatches = StoreStore.shared.matches(
            labels: input.labels,
            pixelBuffer: input.pixelBuffer,
            limit: 3
        )
        let ranked = await rank(productMatches, storeMatches)
        return Array(ranked.prefix(8))
    }
}

Exposing too much app model state through AppEntity. Prefer dedicated shadow models with stable persistent IDs and only system-facing properties.
Missing \(.applicationName) in phrases. Every AppShortcut phrase MUST include the application name token. Siri uses it for disambiguation.
Treating optional @Parameter as required. Optional parameters are not requested automatically; call requestValue / needsValueError when the intent cannot proceed without one.
```
// Optional, so request it yourself if needed
@Parameter(title: "Count")
var count: Int?
```
Using unstable AppEnum raw values. Int is valid, but String raw values are usually clearer for persistence and URL representations.
Forgetting suggestedEntities(). Without it, the Shortcuts picker shows no defaults.
Throwing for missing entities in entities(for:). Omit missing entities instead.
Stale Spotlight index. Re-index entities with a named CSSearchableIndex.
Missing typeDisplayRepresentation. Both AppEntity and AppEnum require it.
Using deprecated @Assistant* schema macros. Use @AppIntent(schema:), @AppEntity(schema:), and @AppEnum(schema:).
Blocking or side-effecting perform(). Use await for I/O; keep SnippetIntent.perform() side-effect-free because the system may rerun it.
Mutating sensitive state from system surfaces without a guard. Use confirmation and/or authentication for actions such as door locks, lights, purchases, and deletes.

app-intents

Summary

SKILL.md

App Intents (iOS 26+)

Contents

Triage Workflow

Step 1: Choose the action, boundary, and surface

Step 2: Define the data model

Step 3: Implement the intent

Step 4: Verify

AppIntent Protocol

`@Parameter`

Supported value types

Common initializer patterns

AppEntity

EntityQuery (4 Variants)

1. EntityQuery (base -- resolve by ID)

2. EntityStringQuery (free-text search)

3. EnumerableEntityQuery (finite set)

4. UniqueAppEntityQuery (singleton, iOS 18+)

AppEnum

AppShortcutsProvider

Phrase rules

System Surface Integration

iOS 26 Additions

SnippetIntent

IntentValueQuery (Visual Intelligence)

Common Mistakes

Review Checklist

References

Related skills