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 {
@AppShortcutsBuilder
static var appShortcuts: [AppShortcut] { get }
static var shortcutTileColor: ShortcutTileColor { get }
static func updateAppShortcutParameters()
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 executephrases — Spoken/typed phrases for Siri/SpotlightshortTitle — Short label for Shortcuts app tilessystemImageName — 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.
struct StartMeditationIntent: AppIntent {
static var title: LocalizedStringResource = "Start Meditation"
@Parameter(title: "Type")
var meditationType: MeditationType?
@Parameter(title: "Duration")
var duration: Int?
}
@AppShortcutsBuilder
static var appShortcuts: [AppShortcut] {
AppShortcut(
intent: StartMeditationIntent(),
phrases: ["Start meditation in \(.applicationName)"],
shortTitle: "Meditate",
systemImageName: "figure.mind.and.body"
)
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
