iOS App Intents
Overview
Expose the smallest useful action and entity surface to the system. Start with the verbs and objects people would actually want outside the app, then implement a narrow App Intents layer that can deep-link or hand off cleanly into the main app when needed.
Treat App Intents as system integration infrastructure, not only as a Shortcuts feature. A good first pass often includes one open-app intent, one action intent, one or two entity types, and a small AppShortcutsProvider.
When to Use
Use this skill when you need to:
- Expose app actions to Shortcuts, Siri, Spotlight, widgets, or iOS controls.
- Define
AppEntity types so the system can understand or route app content.
- Add
AppShortcutsProvider entries for discoverable, phrase-driven shortcuts.
- Wire runtime handoff so an intent opens or routes into a specific in-app workflow.
- Power widget configuration or controls from the same entity surface.
Trigger keywords: App Intents, AppEntity, AppShortcutsProvider, EntityQuery, AppEnum, Shortcuts, Siri, Spotlight, widgets, controls, openAppWhenRun, intents target.
Prerequisites
- A Swift / SwiftUI iOS app project (Xcode 15+ recommended).
- Familiarity with the App Intents framework (
import AppIntents).
- Apple developer documentation as primary reference:
https://developer.apple.com/documentation/appintents/making-actions-and-discoverable-and-widely-available
https://developer.apple.com/documentation/appintents/creating-your-first-app-intent
https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences
- Use web search to consult current Apple Developer documentation when App Intents APIs or platform behavior may have changed.
Reference files
Load these from the skill folder as needed:
references/first-pass-checklist.md — load when choosing the first intent and entity surface.
references/example-patterns.md — load when you need concrete example shapes to copy and adapt.
references/code-templates.md — load when writing generalized App Intents code from templates.
references/system-surfaces.md — load when deciding how Shortcuts, Siri, Spotlight, widgets, and other system entry points should consume your intents.
Procedure
1) Start with actions, not screens
- Identify the 1–3 highest-value actions that should work outside the app UI.
- Prefer verbs like compose, open, find, filter, continue, inspect, or start.
- Do not mirror the entire app navigation tree as intents. Every intent must have real user value outside the app.
2) Define a small entity surface
- Add
AppEntity types only for objects the system needs to understand or route.
- Keep the entity shape narrower than the app's persistence model. Entities should be small and display-friendly.
- Add
EntityQuery (or other query types) only where disambiguation or suggestions are genuinely useful.
- Use
AppEnum for fixed app choices such as tabs, modes, or visibility levels before reaching for a full entity type.
3) Decide whether the action completes in place or opens the app
- Use non-opening intents for actions that can complete directly from the system surface.
- Use
openAppWhenRun or open-style intents when the user should land in a specific in-app workflow.
- When the app must react inside the main scene, add one clear runtime handoff path instead of scattering ad hoc routing logic.
- If the action can work in both modes, consider shipping both an inline version and an open-app version rather than forcing one compromise.
4) Make the actions discoverable
- Add
AppShortcutsProvider entries for the first set of high-value intents.
- Choose titles, phrases, and symbols that make sense in Shortcuts, Siri, and Spotlight.
- Keep shortcut phrases direct and task-oriented. Avoid vague phrases or generic titles.
- Reuse the same action model for widgets and controls when a widget configuration or intent-driven control already needs the same parameters.
5) Keep intent types thin
- Prefer a dedicated intents target or module for the system-facing layer.
- Keep intent types thin; business logic should stay in app services or domain models.
- Prefer one predictable app-intent routing surface in the main app scene or root router.
6) Validate the runtime handoff
- Build the app and confirm the intents target compiles cleanly.
- Verify the app opens or routes to the expected place when an intent runs.
- Summarize which actions are now exposed, which entities back them, and how the app handles invocation.
Examples
Good example families to cover in a first pass:
- Open a destination or editor in the app (open-app intent).
- Perform a lightweight action inline without opening the app (non-opening intent).
- Choose from a fixed enum such as a tab or mode (
AppEnum).
- Resolve one or more entities through
EntityQuery.
- Power widget configuration or controls from the same entity surface.
Pitfalls
- Exposing every screen or tab as its own intent without real user value. Each intent must justify itself outside the app.
- Mirroring the entire model graph as
AppEntity types. Keep entities narrow and display-friendly.
- Hiding runtime handoff in global side effects with no clear app entry path. Use one predictable routing surface.
- Adding App Shortcuts with vague phrases or generic titles. Phrases should be direct and task-oriented.
- Treating the first App Intents pass as a broad taxonomy project instead of a small useful release. Ship 1–3 high-value actions first.
- Putting business logic inside intent types. Keep intents thin; logic belongs in app services or domain models.
- Forgetting
AppEnum for fixed choices. Use AppEnum before reaching for a full entity type when the values are a small fixed set.
Verification
Compile check: Build the app target and the intents target. Confirm there are no compile errors.
xcodebuild -scheme "YourApp" -destination 'platform=iOS Simulator,name=iPhone 15' build
Expected: ** BUILD SUCCEEDED **
Shortcut discovery: On a simulator or device, open the Shortcuts app and confirm your AppShortcutsProvider entries appear under the app's section.
Runtime handoff: Run an intent from Shortcuts or Siri. Confirm the app either completes the action inline or opens and routes to the expected in-app workflow.
Entity resolution: If using EntityQuery, run an intent that requires entity disambiguation. Confirm the system presents the correct entities and that selecting one routes correctly.
Summary output: Produce a short summary listing:
- Which actions are now exposed.
- Which entities back them.
- How the app handles invocation (inline vs. open-app, routing path).
Related skills
ios-widgets — widget configuration powered by App Intents.
ios-siri-integration — Siri phrase tuning and donation patterns.
swift-deep-linking — universal links and deep-link routing into app scenes.
1---
2name: ios-app-intents
3description: "Implements App Intents, AppEntity, EntityQuery, AppEnum, and AppShortcutsProvider so Shortcuts, Siri, Spotlight, widgets, and controls can invoke a thin intents target. Use when exposing app actions or entities to those system surfaces. Do not use for HIG layout, 44pt targets, or Dynamic Type (ios-design-guidelines)."
4version: 1.0.1
5metadata:
6 source: https://skillmd.com/skills/kayforkind/ios-app-intents
7---
8
9# iOS App Intents
10
11## Overview
12
13Expose the smallest useful action and entity surface to the system. Start with the verbs and objects people would actually want outside the app, then implement a narrow App Intents layer that can deep-link or hand off cleanly into the main app when needed.
14
15Treat App Intents as system integration infrastructure, not only as a Shortcuts feature. A good first pass often includes one open-app intent, one action intent, one or two entity types, and a small `AppShortcutsProvider`.
16
17## When to Use
18
19Use this skill when you need to:
20
21- Expose app actions to Shortcuts, Siri, Spotlight, widgets, or iOS controls.
22- Define `AppEntity` types so the system can understand or route app content.
23- Add `AppShortcutsProvider` entries for discoverable, phrase-driven shortcuts.
24- Wire runtime handoff so an intent opens or routes into a specific in-app workflow.
25- Power widget configuration or controls from the same entity surface.
26
27Trigger keywords: App Intents, AppEntity, AppShortcutsProvider, EntityQuery, AppEnum, Shortcuts, Siri, Spotlight, widgets, controls, openAppWhenRun, intents target.
28
29## Prerequisites
30
31- A Swift / SwiftUI iOS app project (Xcode 15+ recommended).
32- Familiarity with the App Intents framework (`import AppIntents`).
33- Apple developer documentation as primary reference:
34 - `https://developer.apple.com/documentation/appintents/making-actions-and-discoverable-and-widely-available`
35 - `https://developer.apple.com/documentation/appintents/creating-your-first-app-intent`
36 - `https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences`
37- Use web search to consult current Apple Developer documentation when App Intents APIs or platform behavior may have changed.
38
39### Reference files
40
41Load these from the skill folder as needed:
42
43- `references/first-pass-checklist.md` — load when choosing the first intent and entity surface.
44- `references/example-patterns.md` — load when you need concrete example shapes to copy and adapt.
45- `references/code-templates.md` — load when writing generalized App Intents code from templates.
46- `references/system-surfaces.md` — load when deciding how Shortcuts, Siri, Spotlight, widgets, and other system entry points should consume your intents.
47
48## Procedure
49
50### 1) Start with actions, not screens
51
521. Identify the 1–3 highest-value actions that should work outside the app UI.
532. Prefer verbs like compose, open, find, filter, continue, inspect, or start.
543. Do not mirror the entire app navigation tree as intents. Every intent must have real user value outside the app.
55
56### 2) Define a small entity surface
57
581. Add `AppEntity` types only for objects the system needs to understand or route.
592. Keep the entity shape narrower than the app's persistence model. Entities should be small and display-friendly.
603. Add `EntityQuery` (or other query types) only where disambiguation or suggestions are genuinely useful.
614. Use `AppEnum` for fixed app choices such as tabs, modes, or visibility levels before reaching for a full entity type.
62
63### 3) Decide whether the action completes in place or opens the app
64
651. Use non-opening intents for actions that can complete directly from the system surface.
662. Use `openAppWhenRun` or open-style intents when the user should land in a specific in-app workflow.
673. When the app must react inside the main scene, add one clear runtime handoff path instead of scattering ad hoc routing logic.
684. If the action can work in both modes, consider shipping both an inline version and an open-app version rather than forcing one compromise.
69
70### 4) Make the actions discoverable
71
721. Add `AppShortcutsProvider` entries for the first set of high-value intents.
732. Choose titles, phrases, and symbols that make sense in Shortcuts, Siri, and Spotlight.
743. Keep shortcut phrases direct and task-oriented. Avoid vague phrases or generic titles.
754. Reuse the same action model for widgets and controls when a widget configuration or intent-driven control already needs the same parameters.
76
77### 5) Keep intent types thin
78
791. Prefer a dedicated intents target or module for the system-facing layer.
802. Keep intent types thin; business logic should stay in app services or domain models.
813. Prefer one predictable app-intent routing surface in the main app scene or root router.
82
83### 6) Validate the runtime handoff
84
851. Build the app and confirm the intents target compiles cleanly.
862. Verify the app opens or routes to the expected place when an intent runs.
873. Summarize which actions are now exposed, which entities back them, and how the app handles invocation.
88
89## Examples
90
91Good example families to cover in a first pass:
92
93- Open a destination or editor in the app (open-app intent).
94- Perform a lightweight action inline without opening the app (non-opening intent).
95- Choose from a fixed enum such as a tab or mode (`AppEnum`).
96- Resolve one or more entities through `EntityQuery`.
97- Power widget configuration or controls from the same entity surface.
98
99## Pitfalls
100
101- **Exposing every screen or tab as its own intent** without real user value. Each intent must justify itself outside the app.
102- **Mirroring the entire model graph as `AppEntity` types.** Keep entities narrow and display-friendly.
103- **Hiding runtime handoff in global side effects** with no clear app entry path. Use one predictable routing surface.
104- **Adding App Shortcuts with vague phrases or generic titles.** Phrases should be direct and task-oriented.
105- **Treating the first App Intents pass as a broad taxonomy project** instead of a small useful release. Ship 1–3 high-value actions first.
106- **Putting business logic inside intent types.** Keep intents thin; logic belongs in app services or domain models.
107- **Forgetting `AppEnum` for fixed choices.** Use `AppEnum` before reaching for a full entity type when the values are a small fixed set.
108
109## Verification
110
1111. **Compile check:** Build the app target and the intents target. Confirm there are no compile errors.
112
113 ```bash
114 xcodebuild -scheme "YourApp" -destination 'platform=iOS Simulator,name=iPhone 15' build
115 ```
116
117 Expected: `** BUILD SUCCEEDED **`
118
1192. **Shortcut discovery:** On a simulator or device, open the Shortcuts app and confirm your `AppShortcutsProvider` entries appear under the app's section.
120
1213. **Runtime handoff:** Run an intent from Shortcuts or Siri. Confirm the app either completes the action inline or opens and routes to the expected in-app workflow.
122
1234. **Entity resolution:** If using `EntityQuery`, run an intent that requires entity disambiguation. Confirm the system presents the correct entities and that selecting one routes correctly.
124
1255. **Summary output:** Produce a short summary listing:
126 - Which actions are now exposed.
127 - Which entities back them.
128 - How the app handles invocation (inline vs. open-app, routing path).
129
130## Related skills
131
132- `ios-widgets` — widget configuration powered by App Intents.
133- `ios-siri-integration` — Siri phrase tuning and donation patterns.
134- `swift-deep-linking` — universal links and deep-link routing into app scenes.