ios-app-intents
Design App Intents, app entities, and App Shortcuts for iOS system surfaces. Use when exposing app actions or content to Shortcuts, Siri, Spotlight, widgets, or controls.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ios-app-intents
- description
- Design App Intents, app entities, and App Shortcuts for iOS system surfaces. Use when exposing app actions or content to Shortcuts, Siri, Spotlight, widgets, or controls.
02 资源文件 5
- 参考文档agents/openai.yaml113 B
- 参考文档references/code-templates.md7.4 KB
- 参考文档references/example-patterns.md3.6 KB
- 参考文档references/first-pass-checklist.md1.4 KB
- 参考文档references/system-surfaces.md1.0 KB
03 SKILL.md 正文
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.mdfor choosing the first intent and entity surfacereferences/example-patterns.mdfor concrete example shapes to copy and adaptreferences/code-templates.mdfor generalized App Intents code templatesreferences/system-surfaces.mdfor 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
AppEntitytypes only for the objects the system needs to understand or route. - Keep the entity shape narrower than the app's persistence model.
- Add
EntityQueryor 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
openAppWhenRunor 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
AppShortcutsProviderentries 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
AppEnumfor 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
AppEntitytypes. - 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-availablehttps://developer.apple.com/documentation/appintents/creating-your-first-app-intenthttps://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
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
review-agent
Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.