axiom-app-shortcuts-ref

App Shortcuts Reference

Overview

Comprehensive guide to App Shortcuts framework for making your app's actions instantly available in Siri, Spotlight, Action Button, Control Center, and other system experiences. App Shortcuts are pre-configured App Intents that work immediately after app install—no user setup required.

Key distinction App Intents are the actions; App Shortcuts are the pre-configured "surface" that makes those actions instantly discoverable system-wide.

---

When to Use This Skill

Use this skill when:

• Implementing AppShortcutsProvider for your app
• Adding suggested phrases for Siri invocation
• Configuring instant Spotlight availability
• Creating parameterized shortcuts (skip Siri clarification)
• Using NegativeAppShortcutPhrase to prevent false positives (iOS 17+)
• Promoting shortcuts with SiriTipView
• Updating shortcuts dynamically with updateAppShortcutParameters()
• Debugging shortcuts not appearing in Shortcuts app or Spotlight
• Choosing between App Intents and App Shortcuts

Do NOT use this skill for:

• General App Intents implementation (use app-intents-ref)
• Core Spotlight indexing (use core-spotlight-ref)
• Overall discoverability strategy (use app-discoverability)

---

Related Skills

• app-intents-ref — Complete App Intents implementation reference
• app-discoverability — Strategic guide for making apps discoverable
• core-spotlight-ref — Core Spotlight and NSUserActivity integration

---

App Shortcuts vs App Intents

Aspect	App Intent	App Shortcut
Discovery	Must be found in Shortcuts app	Instantly available after install
Configuration	User configures in Shortcuts	Pre-configured by developer
Siri activation	Requires custom phrase setup	Works immediately with provided phrases
Spotlight	Requires donation or IndexedEntity	Appears automatically
Action button	Not directly accessible	Can be assigned immediately
Setup time	Minutes per user	Zero

When to use App Shortcuts Every app should provide App Shortcuts for core functionality. They dramatically improve discoverability with zero user effort.

---

Core Concepts

AppShortcutsProvider Protocol

Required conformance Your app must have exactly one type conforming to AppShortcutsProvider.

struct MyAppShortcuts: AppShortcutsProvider {
    // Required: Define your shortcuts
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] { get }

    // Optional: Branding color
    static var shortcutTileColor: ShortcutTileColor { get }

    // Optional: Dynamic updates
    static func updateAppShortcutParameters()

    // Optional: Negative phrases (iOS 17+)
    static var negativePhrases: [NegativeAppShortcutPhrase] { get }
}

Platform support iOS 16+, iPadOS 16+, macOS 13+, tvOS 16+, watchOS 9+

---

AppShortcut Structure

Associates an AppIntent with spoken phrases and metadata.

AppShortcut(
    intent: StartMeditationIntent(),
    phrases: [
        "Start meditation in \(.applicationName)",
        "Begin mindfulness with \(.applicationName)"
    ],
    shortTitle: "Meditate",
    systemImageName: "figure.mind.and.body"
)

Components:

• intent — The App Intent to execute
• phrases — Spoken/typed phrases for Siri/Spotlight
• shortTitle — Short label for Shortcuts app tiles
• systemImageName — SF Symbol for visual representation

---

AppShortcutPhrase (Suggested Phrases)

String interpolation Phrases use \(.applicationName) to dynamically include your app's name.

phrases: [
    "Start meditation in \(.applicationName)",
    "Meditate with \(.applicationName)"
]

User sees in Siri/Spotlight:

• "Start meditation in Calm"
• "Meditate with Calm"

Why this matters The system uses these exact phrases to trigger your intent via Siri and show suggestions in Spotlight.

---

@AppShortcutsBuilder

Result builder for defining shortcuts array.

@AppShortcutsBuilder
static var appShortcuts: [AppShortcut] {
    AppShortcut(intent: OrderIntent(), /* ... */)
    AppShortcut(intent: ReorderIntent(), /* ... */)

    if UserDefaults.standard.bool(forKey: "premiumUser") {
        AppShortcut(intent: CustomizeIntent(), /* ... */)
    }
}

Result builder features:

• Conditional shortcuts (if/else)
• Loop-generated shortcuts (for-in)
• Inline array construction

---

Phrase Template Patterns

Basic Phrases (No Parameters)

AppShortcut(
    intent: StartWorkoutIntent(),
    phrases: [
        "Start workout in \(.applicationName)",
        "Begin exercise with \(.applicationName)",
        "Work out in \(.applicationName)"
    ],
    shortTitle: "Start Workout",
    systemImageName: "figure.run"
)

Benefits:

• Simple, discoverable
• Works for all users
• No parameter ambiguity

Use when Intent has no required parameters or parameters have defaults.

---

Parameterized Phrases (Skip Clarification)

Pre-configure intents with specific parameter values to skip Siri's clarification step.

// Intent with parameters
struct StartMeditationIntent: AppIntent {
    static var title: LocalizedStringResource = "Start Meditation"

    @Parameter(title: "Type")
    var meditationType: MeditationType?

    @Parameter(title: "Duration")
    var duration: Int?
}

// Shortcuts with different parameter combinations
@AppShortcutsBuilder
static var appShortcuts: [AppShortcut] {
    // Generic version (will ask for parameters)
    AppShortcut(
        intent: StartMeditationIntent(),
        phrases: ["Start meditation in \(.applicationName)"],
        shortTitle: "Meditate",
        systemImageName: "figure.mind.and.body"
    )

    // Specific versions (skip parameter step)
    AppShortcut(
        intent: StartMeditationIntent(
            meditationType: .mindfulness,
            duration: 10
        ),
        phrases: [
            "Start quick mindfulness in \(.applicationName)",
            "10 minute mindfulness in \(.applicationName)"
        ],
        shortTitle: "Quick Mindfulness",
        systemImageName: "brain.head.profile"
    )

    AppShortcut(
        intent: StartMeditationIntent(
            meditationType: .sleep,
            duration: 20
        ),
        phrases: [
            "Start sleep meditation in \(.applicationName)"
        ],
        shortTitle: "Sleep Meditation",
        systemImageName: "moon.stars.fill"
    )
}

Benefits:

• One-phrase completion (no follow-up questions)
• Better user experience for common use cases
• Spotlight shows specific shortcuts

Trade-off More shortcuts = more visual clutter in Shortcuts app. Balance common cases (3-5 shortcuts) vs flexibility (generic shortcut with parameters).

---

NegativeAppShortcutPhrase (iOS 17+)

Train the system to NOT invoke your app for certain phrases.

struct MeditationAppShortcuts: AppShortcutsProvider {
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: StartMeditationIntent(),
            phrases: ["Start meditation in \(.applicationName)"],
            shortTitle: "Meditate",
            systemImageName: "figure.mind.and.body"
        )
    }

    // Prevent false positives
    static var negativePhrases: [NegativeAppShortcutPhrase] {
        NegativeAppShortcutPhrases {
            "Stop meditation"
            "Cancel meditation"
            "End session"
        }
    }
}

When to use:

• Phrases that sound similar to your shortcuts but mean the opposite
• Common phrases users might say that shouldn't trigger your app
• Disambiguation when multiple apps have similar capabilities

Platform iOS 17.0+, iPadOS 17.0+, macOS 14.0+, tvOS 17.0+, watchOS 10.0+

---

Discovery UI Components

SiriTipView — Promote Shortcuts In-App

Display the spoken phrase for a shortcut directly in your app's UI.

import AppIntents
import SwiftUI

struct OrderConfirmationView: View {
    @State private var showSiriTip = true

    var body: some View {
        VStack {
            Text("Order confirmed!")

            // Show Siri tip after successful order
            SiriTipView(intent: ReorderIntent(), isVisible: $showSiriTip)
                .siriTipViewStyle(.dark)
        }
    }
}

Requirements:

• Intent must be used in an AppShortcut (otherwise shows empty view)
• isVisible binding controls display state

Styles:

• .automatic — Adapts to environment
• .light — Light background
• .dark — Dark background

Best practice Show after users complete actions, suggesting easier ways next time.

---

ShortcutsLink — Link to Shortcuts App

Opens your app's page in the Shortcuts app, listing all available shortcuts.

import AppIntents
import SwiftUI

struct SettingsView: View {
    var body: some View {
        List {
            Section("Siri & Shortcuts") {
                ShortcutsLink()
                // Displays "Shortcuts" with standard link styling
            }
        }
    }
}

When to use:

• Settings screen
• Help/Support section
• Onboarding flow

Benefits Single tap takes users to see all your app's shortcuts, with suggested phrases visible.

---

ShortcutTileColor — Branding

Set the color for your shortcuts in the Shortcuts app.

struct CoffeeAppShortcuts: AppShortcutsProvider {
    static var shortcutTileColor: ShortcutTileColor = .tangerine

    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        // ...
    }
}

Available colors:

Color	Use Case
.blue	Default, professional
.tangerine	Energy, food/beverage
.purple	Creative, meditation
.teal	Health, wellness
.red	Urgent, important
.pink	Lifestyle, social
.navy	Business, finance
.yellow	Productivity, notes
.lime	Fitness, outdoor

Full

---

Content truncated.