{"id":24719,"plugin_id":"plugins~Plugin_f1b845ac33888191ac156169c58733c2","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:18:36.121Z","digest":"9aec186e34a066e213c4b00d00dfeef87ba796e9a435c93036b393c314fabb18","against":null,"payload":{"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.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":113},{"relative_path":"references/code-templates.md","size_in_bytes":7575},{"relative_path":"references/example-patterns.md","size_in_bytes":3712},{"relative_path":"references/first-pass-checklist.md","size_in_bytes":1411},{"relative_path":"references/system-surfaces.md","size_in_bytes":1059}],"name":"ios-app-intents","skill_md_contents":"---\nname: ios-app-intents\ndescription: 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.\n---\n\n# iOS App Intents\n\n## Overview\nExpose 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.\n\nRead these references as needed:\n\n- `references/first-pass-checklist.md` for choosing the first intent and entity surface\n- `references/example-patterns.md` for concrete example shapes to copy and adapt\n- `references/code-templates.md` for generalized App Intents code templates\n- `references/system-surfaces.md` for how to think about Shortcuts, Siri, Spotlight, widgets, and other system entry points\n\n## Core workflow\n\n### 1) Start with actions, not screens\n- Identify the 1-3 highest-value actions that should work outside the app UI.\n- Prefer verbs like compose, open, find, filter, continue, inspect, or start.\n- Do not mirror the entire app navigation tree as intents.\n\n### 2) Define a small entity surface\n- Add `AppEntity` types only for the objects the system needs to understand or route.\n- Keep the entity shape narrower than the app's persistence model.\n- Add `EntityQuery` or other query types only where disambiguation or suggestions are genuinely useful.\n\n### 3) Decide whether the action completes in place or opens the app\n- Use non-opening intents for actions that can complete directly from the system surface.\n- Use `openAppWhenRun` or open-style intents when the user should land in a specific in-app workflow.\n- When the app must react inside the main scene, add one clear runtime handoff path instead of scattering ad hoc routing logic.\n- If the action can work in both modes, consider shipping both an inline version and an open-app version rather than forcing one compromise.\n\n### 4) Make the actions discoverable\n- Add `AppShortcutsProvider` entries for the first set of high-value intents.\n- Choose titles, phrases, and symbols that make sense in Shortcuts, Siri, and Spotlight.\n- Keep shortcut phrases direct and task-oriented.\n- Reuse the same action model for widgets and controls when a widget configuration or intent-driven control already needs the same parameters.\n\n### 5) Validate the runtime handoff\n- Build the app and confirm the intents target compiles cleanly.\n- Verify the app opens or routes to the expected place when an intent runs.\n- Summarize which actions are now exposed, which entities back them, and how the app handles invocation.\n\n## Strong defaults\n\n- Prefer a dedicated intents target or module for the system-facing layer.\n- Keep intent types thin; business logic should stay in app services or domain models.\n- Keep app entities small and display-friendly.\n- Use `AppEnum` for fixed app choices such as tabs, modes, or visibility levels before reaching for a full entity type.\n- Prefer one predictable app-intent routing surface in the main app scene or root router.\n- Treat App Intents as system integration infrastructure, not only as a Shortcuts feature.\n\n## Anti-patterns\n\n- Exposing every screen or tab as its own intent without a real user value.\n- Mirroring the entire model graph as `AppEntity` types.\n- Hiding runtime handoff in global side effects with no clear app entry path.\n- Adding App Shortcuts with vague phrases or generic titles.\n- Treating the first App Intents pass as a broad taxonomy project instead of a small useful release.\n\n## Notes\n\n- Apple documentation to use as primary references:\n  - `https://developer.apple.com/documentation/appintents/making-actions-and-content-discoverable-and-widely-available`\n  - `https://developer.apple.com/documentation/appintents/creating-your-first-app-intent`\n  - `https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences`\n- 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.\n- A good first pass often includes one open-app intent, one action intent, one or two entity types, and a small `AppShortcutsProvider`.\n- Good example families to cover are:\n  - open a destination or editor in the app\n  - perform a lightweight action inline without opening the app\n  - choose from a fixed enum such as a tab or mode\n  - resolve one or more entities through `EntityQuery`\n  - power widget configuration or controls from the same entity surface\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}