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 experien