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.

Read these references as needed:

• references/first-pass-checklist.md for choosing the first intent and entity surface
• references/example-patterns.md for concrete example shapes to copy and adapt
• references/code-templates.md for generalized App Intents code templates
• references/system-surfaces.md for how to think about Shortcuts, Siri, Spotlight, widgets, and other system entry points

Core workflow

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.

2) Define a small entity surface

• Add AppEntity types only for the objects the system needs to understand or route.
• Keep the entity shape narrower than the app's persistence model.
• Add EntityQuery or other query types only where disambiguation or suggestions are genuinely useful.

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.
• Reuse the same action model for widgets and controls when a widget configuration or intent-driven control already needs the same parameters.

5) 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.

Strong defaults

• 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.
• Keep app entities small and display-friendly.
• Use AppEnum for fixed app choices such as tabs, modes, or visibility levels before reaching for a full entity type.
• Prefer one predictable app-intent routing surface in the main app scene or root router.
• Treat App Intents as system integration infrastructure, not only as a Shortcuts feature.

Anti-patterns

• Exposing every screen or tab as its own intent without a real user value.
• Mirroring the entire model graph as AppEntity types.
• Hiding runtime handoff in global side effects with no clear app entry path.
• Adding App Shortcuts with vague phrases or generic titles.
• Treating the first App Intents pass as a broad taxonomy project instead of a small useful release.

Notes

• Apple documentation to use as primary references:
  • https://developer.apple.com/documentation/appintents/making-actions-and-content-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
• In addition to the links above, use web search to consult current Apple Developer documentation when App Intents APIs or platform behavior may have changed.
• A good first pass often includes one open-app intent, one action intent, one or two entity types, and a small AppShortcutsProvider.
• Good example families to cover are:
  • open a destination or editor in the app
  • perform a lightweight action inline without opening the app
  • choose from a fixed enum such as a tab or mode
  • resolve one or more entities through EntityQuery
  • power widget configuration or controls from the same entity surface