SuperAPI AI Directory

app-intents

General & other

View repository

Updated 10-16 05:52

About this skill

App Intents

Expose app actions and entities to Siri, Shortcuts, Spotlight search, interactive widgets, Control Center, and Apple Intelligence using the AppIntents framework. Targets Swift 6.3 / iOS 26+.

Contents

  • Triage Workflow
  • System Surface Integration Matrix
  • AppEntity and EntityQuery
  • AppShortcuts and Voice Phrases
  • Route by Task
  • Common Mistakes
  • Review Checklist
  • References

Triage Workflow

  1. Select core actions: Expose 1–3 high-value user tasks that make sense outside the app.
  2. Define AppEntity models: Create identifiable shadow models (AppEntity) for domain data referenced by the intent.
  3. Implement AppIntent: Define parameters with @Parameter, implement perform() async throws -> some IntentResult.
  4. Register voice phrases: Provide natural voice invocations with AppShortcutsProvider.
  5. Verify system surface: Test discovery in Shortcuts, Spotlight search, and widget configuration.

System Surface Integration Matrix

System Surface Protocol / Attribute Purpose
Siri & Shortcuts AppIntent Direct voice and shortcut automation
Configurable Widgets WidgetConfigurationIntent Supplies parameters to widget timelines
Control Center ControlConfigurationIntent Powers Control Center buttons and toggles
Spotlight Search IndexedEntity Indexes domain items into on-device Spotlight
Apple Intelligence @AppIntent(schema:) Assistant semantic reasoning and tooling
Interactive Snippets SnippetIntent In-line system confirmation views (iOS 26+)

AppEntity and EntityQuery

Expose domain data to intents using AppEntity:

struct OrderEntity: AppEntity {
    static var defaultQuery = OrderQuery()
    static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Order")

    var id: UUID
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(orderNumber)")
    }
}

Implement EntityQuery to resolve identifiers (entities(for:)) and provide suggested choices (suggestedEntities()).

AppShortcuts and Voice Phrases

Expose voice triggers without requiring user setup via AppShortcutsProvider:

  • Register app shortcut phrases using \(.applicationName) token.
  • Provide clean fallback phrases for Siri matching.

Route by Task

Common Mistakes

  • Performing UI navigation or view presentation directly inside perform() without returning an OpenURLIntent or navigation result.
  • Forgetting to provide an EntityQuery for custom @Parameter entity types, breaking Shortcuts parameter selection.
  • Hardcoding the app name in AppShortcut phrases instead of using \(.applicationName).
  • Running long network calls in perform() without checking Task.isCancelled or providing progress dialogs.
  • Omitting typeDisplayRepresentation on AppEntity conformances.

Review Checklist

  • Intent conforms to AppIntent or specialized surface protocol
  • Parameters have clear titles and valid default/suggested values
  • Entities implement EntityQuery with entities(for:) and suggestedEntities()
  • perform() returns an appropriate IntentResult (e.g. .result(), .result(dialog:))
  • Shortcuts phrases use \(.applicationName) macro
  • Destructive actions declare requestConfirmation() before executing
  • Sensitive actions require device authentication where appropriate

References