use-cases/ios-app-intents.md +141 −7
11# Add iOS app intents | Codex use cases---
2name: Add iOS app intents
3tagline: Use Codex to make your app's actions and content available to
4 Shortcuts, Siri, Spotlight, and newer assistant-driven system experiences.
5summary: Use Codex and the Build iOS Apps plugin to identify the actions and
6 entities your app should expose through App Intents, wire them into system
7 surfaces like Shortcuts and Spotlight, and prepare your app for more
8 assistant-driven workflows over time.
9skills:
10 - token: build-ios-apps
11 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
12 description: Use the iOS build and SwiftUI skills to add App Intents, app
13 entities, and App Shortcuts, then validate that the app still builds and
14 routes intent-driven entry points correctly.
15bestFor:
16 - iOS apps that already have useful actions or content but are still invisible
17 to Shortcuts, Siri, Spotlight, or the wider system
18 - Teams that want to expose a few high-value actions now and build toward more
19 assistant-friendly workflows over time
20 - Apps with clear objects like accounts, lists, filters, destinations, drafts,
21 or media that can become app entities instead of staying locked inside the
22 UI
23starterPrompt:
24 title: Add App Intents for System and Assistant Surfaces
25 body: >-
26 Use the Build iOS Apps plugin to audit this iOS app and add App Intents for
27 the actions and entities that should be exposed to the system.
2 28
3Need
4 29
530Validation loop Constraints:
6 31
732Default options - Start by identifying the app's highest-value user actions and core objects
33 that should be available outside the app in Shortcuts, Siri, Spotlight,
34 widgets, controls, or newer assistant-driven system surfaces.
8 35
936`xcodebuild`, simulator checks, and focused runtime routing verification - Keep the first pass focused. Pick a small set of intents that are
37 genuinely useful without opening the full app, plus any open-app intents
38 that should deep-link into a specific screen or workflow.
10 39
1140Why it's needed - Define app entities only for the data the system actually needs to
41 understand and route those actions. Do not mirror the entire internal model
42 layer if a smaller entity surface is enough.
12 43
1344The hard part is not just compiling the intents target, but proving that the app opens or routes to the right place when the system invokes an intent. - Add App Shortcuts where they make the experience more discoverable, and
45 choose titles, phrases, and display representations that would make sense in
46 Siri, Spotlight, and Shortcuts.
47
48 - If the app needs to handle the intent inside the main UI, route the result
49 back into the app cleanly and explain how the app scene reacts to that
50 handoff.
51
52 - Build and validate the app after the first pass, then summarize which
53 actions, entities, and system surfaces are now supported.
54
55
56 Deliver:
57
58 - the recommended intent and entity surface for a first release
59
60 - the implemented intents, entities, and App Shortcuts
61
62 - how the app routes or handles those intents at runtime
63
64 - which Apple system experiences this unlocks now and which ones are logical
65 next steps
66relatedLinks:
67 - label: App Intents overview
68 url: https://developer.apple.com/documentation/appintents/making-actions-and-content-discoverable-and-widely-available
69 - label: Apple system experiences sample
70 url: https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences
71techStack:
72 - need: Action exposure
73 goodDefault: "[App
74 Intents](https://developer.apple.com/documentation/appintents/making-acti\
75 ons-and-content-discoverable-and-widely-available)"
76 why: App Intents are the system contract that lets your app’s actions show up in
77 Shortcuts, Siri, Spotlight, widgets, controls, and newer assistant-facing
78 surfaces.
79 - need: App data surface
80 goodDefault: "`AppEntity`, `EntityQuery`, and display representations"
81 why: A small, well-shaped entity layer makes it possible for the system to
82 understand your app’s objects without exposing your entire model layer.
83 - need: Discoverability layer
84 goodDefault: "`AppShortcutsProvider` with clear phrases, titles, and symbols"
85 why: App Shortcuts make the first set of exposed actions easier to find and run
86 without asking users to build everything from scratch.
87 - need: Validation loop
88 goodDefault: "`xcodebuild`, simulator checks, and focused runtime routing verification"
89 why: The hard part is not just compiling the intents target, but proving that
90 the app opens or routes to the right place when the system invokes an
91 intent.
92---
93
94## Make the right parts of your app visible to the system
95
96App Intents are one of the clearest ways to make an iOS app more useful outside its own UI. Instead of treating your app as a sealed destination that only works after someone launches it and taps around, use Codex to expose the actions and objects that should be available to Shortcuts, Siri, Spotlight, widgets, controls, and newer assistant-driven system experiences.
97
98That is useful today for discoverability and automation, and it is a strong preparation step for a more assistant-driven future. If your app already knows how to compose, open, filter, route, or summarize something valuable, App Intents give the system a structured way to ask for that capability.
99
100## Start with actions and entities, not with every screen
101
102The best first App Intents pass is usually not “mirror the whole app.” Ask Codex to identify:
103
104- the few actions a user would want to trigger without navigating the full interface
105- the app objects the system needs to understand to route those actions correctly
106- the workflows that should open the app in a specific state versus the ones that should complete directly from a system surface
107
108Apple’s App Intents guidance is a good frame here: define the action, define the entity surface the system needs, then make those actions discoverable and reusable across system experiences. The most useful references are [Making actions and content discoverable and widely available](https://developer.apple.com/documentation/appintents/making-actions-and-content-discoverable-and-widely-available), [Creating your first app intent](https://developer.apple.com/documentation/appintents/creating-your-first-app-intent), and the system-experience sample [Adopting App Intents to support system experiences](https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences).
109
110## Think in system surfaces, not just in shortcuts
111
112The opportunity is broader than “add one shortcut.” A good App Intents surface can make your app useful in several places:
113
114- Shortcuts, where users can run actions directly or compose them into larger automations
115- Siri, where the app can expose meaningful verbs and deep links instead of only opening generically
116- Spotlight, where app entities and app shortcuts become discoverable system entry points
117- widgets, Live Activities, controls, and other intent-driven UI surfaces
118- newer assistant-facing experiences, where structured actions and entities are much easier for the system to understand than arbitrary UI flows
119
120## Follow a real app pattern
121
122This usually works best when the app adopts a structure like this:
123
124- a dedicated App Intents target instead of scattering intent types across unrelated app files
125- `AppShortcutsProvider` entries for high-value user actions like composing a post or opening the app on a specific tab
126- small `AppEntity` types for things the system needs to reason about, such as accounts, lists, and timeline filters
127- intent handling that routes back into the main app scene cleanly, so an invoked intent can open the right compose flow or switch the app to the right tab
128
129That is the pattern I would ask Codex to follow for most apps: start with a small system-facing action layer, keep the entity surface narrow, and wire a predictable runtime handoff back into the app when the intent needs the main UI.
130
131## Ask Codex to design the first intent surface
132
133The strongest prompt here is one that gives Codex your app’s core objects and top user actions, then asks it to choose the smallest useful first App Intents surface instead of blindly exposing everything.
134
135## Practical tips
136
137### Expose verbs users actually want outside the app
138
139Good first intents are usually things like compose, open, find, filter, start, continue, or inspect. If an action is only useful after a long in-app setup flow, it may not belong in the first App Intents pass.
140
141### Keep entities smaller than your model layer
142
143The system usually does not need your full persistence model. Ask Codex to define the smallest app entity surface that still gives Siri, Shortcuts, and Spotlight enough context to route and display the action correctly.
144
145### Treat this as assistant infrastructure, not only a shortcuts feature
146
147Even if your first release only visibly improves Shortcuts or Siri, the deeper win is that your app starts speaking in structured actions and entities. That makes it easier to participate in future system and AI-driven entry points than an app whose capabilities are only encoded in taps and view hierarchies.