Skip to content

← All tools

Free tool for Apple developers

App Intents and App Shortcuts builder

To make an action available in Shortcuts, Siri and Spotlight, you write a struct that adopts AppIntent (a title, @Parameter properties and perform()), and to give it spoken phrases you list it in an AppShortcutsProvider. Apple's rules for phrases: each one contains \(.applicationName), holds at most one parameter, and that parameter must be an AppEnum or AppEntity; an app may have up to 10 App Shortcuts and 1,000 phrases. Fill in the form below to get the Swift code with every phrase checked, plus where the file goes and how to test it in the Shortcuts app.

Describe your action

Everything runs in this page; nothing is uploaded.

The intent

Left empty, the name is made from the title.

Parameters

Values the action needs. Shortcuts asks for required ones before it runs.

Fixed list (AppEnum)

The sentence Shortcuts shows in the editor. Write {name} where a parameter goes, for example: Start {kind} timer.

App Shortcut

Write {app} where your app's name goes and {name} for a parameter. \(.applicationName) and \(\.$name) work too.

Phrase check

  1. FixPhrase 3Start a timer for {minutes} minutes in {app}

    minutes is a Int parameter. Phrases can only hold a parameter with a known set of values: a fixed list (AppEnum) or your own items (AppEntity). Open-ended values such as text or numbers are not supported in phrases; Siri asks for them after the phrase instead.

    Source: WWDC23: Spotlight your app with App Shortcuts · WWDC22: Implement App Shortcuts with App Intents

  2. FixPhrase 4Time my work

    Every phrase must contain your app's name. Add {app}; Siri then also accepts the app name synonyms you set up.

    Source: WWDC23: Spotlight your app with App Shortcuts · Human Interface Guidelines: App Shortcuts · App Intents: AppShortcutPhrase

Swift code

One file with everything. Copy it into a new Swift file in your app target, then replace the comment in perform() with your own code.

import AppIntents

enum TimerKind: String, AppEnum {
    case pomodoro
    case deepWork
    case shortBreak

    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Timer Kind"
    static let caseDisplayRepresentations: [TimerKind: DisplayRepresentation] = [
        .pomodoro: "Pomodoro",
        .deepWork: "Deep Work",
        .shortBreak: "Short Break",
    ]
}

struct StartTimerIntent: AppIntent {
    static let title: LocalizedStringResource = "Start Timer"
    static let description = IntentDescription("Starts a focus timer.")
    static let openAppWhenRun: Bool = true

    @Parameter(title: "Kind")
    var kind: TimerKind

    @Parameter(title: "Minutes")
    var minutes: Int?

    static var parameterSummary: some ParameterSummary {
        Summary("Start \(\.$kind) timer for \(\.$minutes) minutes")
    }

    func perform() async throws -> some IntentResult {
        // Run the action here, using your app's own code.
        return .result()
    }
}

struct TimerShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: StartTimerIntent(),
            phrases: [
                "Start a timer in \(.applicationName)",
                "Start a \(\.$kind) timer in \(.applicationName)",
                "Start a timer for \(\.$minutes) minutes in \(.applicationName)",
                "Time my work",
            ],
            shortTitle: "Start Timer",
            systemImageName: "timer"
        )
    }
}

Where the code goes

  • •Add a new Swift file to your app target (File > New > File from Template > Swift File) and paste the code. Apple says intents can also live in an app extension, a framework or a Swift package.
  • •Keep the App Shortcuts provider with the intents it uses. An app has one AppShortcutsProvider; put every App Shortcut in its appShortcuts list, most useful first.
  • •Nothing needs registering. The build step reads your intents and App Shortcuts, and they are available once the app is installed.
  • •openAppWhenRun set to true is an error when the intent runs in an app extension, and it is deprecated from iOS 26. Use supportedModes when your app supports iOS 26 or later.
  • •For an AppEntity, keep its id stable: Shortcuts saves it inside people's shortcuts.

Source: App Intents: App Shortcuts · App Intents: Creating your first app intent · App Intents: openAppWhenRun · App Intents: AppEntity

How to test it in the Shortcuts app

  1. Build and run the app on a device or Simulator, and wait for it to launch.
  2. Open Shortcuts and tap + to make a new shortcut.
  3. Choose Apps in the action list, tap your app's icon and pick the action.
  4. Set the parameters in the summary sentence, then tap Run. A breakpoint at the top of perform() stops there when it runs.
  5. Your App Shortcuts also appear under your app in Shortcuts and in Spotlight. Type the start of a phrase in Spotlight to see them, or say the phrase to Siri.

Source: App Intents: Verifying your App Intents implementation

Apple's rules for phrases

Sources

Apple's pages, read on 1 November 2026:

How it works

  • •The form builds one AppIntent: title, description, parameters (text, numbers, on/off, dates, links, a fixed list as an AppEnum, or your own items as an AppEntity), an optional parameter summary, and whether running it opens the app.
  • •For opening the app it writes openAppWhenRun when your app supports iOS 17 to 25, and supportedModes (iOS 26 and later, the replacement Apple recommends) otherwise.
  • •Phrases are checked as you type: the app name token, which parameters may appear, one parameter per phrase, repeats, and the 10 App Shortcut and 1,000 phrase limits, where a phrase with a fixed list counts once per choice.
  • •Generated files from three different setups were type-checked with swiftc against the iOS 27.1 SDK in Swift 6 mode: two for iOS 17, one using supportedModes for iOS 26.
  • •The rules come from the Apple pages listed under Sources, read on 1 November 2026. The phrase rules are stated in Apple's design guidelines and WWDC sessions, not on the API pages.

What it does and does not do

  • •It writes one intent and one App Shortcut at a time. To add more, copy the AppShortcut(...) block into the appShortcuts list of the provider you already have.
  • •It does not write your action's code. perform() returns an empty result, and the AppEntity query returns no items until you connect them to your data.
  • •Phrases are checked against Apple's written rules only. Whether Siri understands a phrase well can only be tested on a device.
  • •It does not cover App Intent domains for Apple Intelligence, widgets, controls, Focus filters, results with dialogs or snippet views, or Mac-only details (App Shortcuts are not supported on macOS; intents are).
  • •Localized phrases belong in a String Catalog in Xcode; this page writes English (or whatever you type) only.

Frequently asked questions

Why must every App Shortcut phrase include \(.applicationName)?
Apple's rule is that every phrase contains the app name or one of its synonyms, so Siri knows which app should answer. Using the \(.applicationName) token instead of typing the name means Siri also accepts the app name synonyms you set up.
Can I put a String or Int parameter in a phrase?
No. Apple says phrase parameters must have a known set of values: an AppEnum, whose cases are fixed, or an AppEntity, whose values come from suggestedEntities() in its query. Open-ended values such as "search for X" are not supported. Keep the String parameter on the intent and let Siri ask for it after the phrase.
How many App Shortcuts and phrases can an app have?
Up to 10 App Shortcuts and up to 1,000 phrases for the whole app. The phrase count includes every parameter value, so one phrase with a 20-choice AppEnum counts as 20. Keep parameter lists short.
Should I use openAppWhenRun or supportedModes?
supportedModes is the newer property and needs iOS 26 or later; Apple marks openAppWhenRun as deprecated and says to use supportedModes instead. If your app still supports iOS 17 to 25, openAppWhenRun = true works for intents that run inside the app, but it is an error in an app extension.
Do I need to register my App Shortcuts anywhere?
No. The build reads the AppShortcutsProvider and the shortcuts are available as soon as the app is installed, before it is first opened. If an AppEntity's list of suggested items changes, call updateAppShortcutParameters() on your provider so the phrases with that parameter are refreshed.
How do I test my intent before release?
Run the app once, open Shortcuts, tap + to make a new shortcut, choose Apps, tap your app and pick the action, set the parameters and tap Run. Set a breakpoint in perform() to step through it. Then type the start of a phrase in Spotlight, or say it to Siri, to check your App Shortcuts.

Guides that use this tool

Related