| name | foundation-models-app-builder |
| description | Build or modify Apple Foundation Models features in Swift, SwiftUI, iOS, and macOS apps. Use when adding or reviewing LanguageModelSession flows, model availability checks, streaming, GenerationOptions, @Generable structured output, DynamicGenerationSchema, tool calling, RAG, voice input/output, HealthKit-backed AI, multilingual responses, App Intents, reusable capability boundaries, or production error handling. |
Foundation Models App Builder
Use this skill as a self-contained Foundation Models app-building playbook. The recipes live inside this skill so agents can apply the patterns in any Swift app without needing to inspect a particular app repository.
What This Skill Optimizes For
- Shipping app features, not reciting API docs.
- Turning Foundation Models into reusable app capabilities with clear Swift types.
- Keeping model orchestration separate from SwiftUI, App Intents, permissions, and persistence.
- Choosing the smallest useful pattern: text, structured output, dynamic schema, tool, RAG, voice, or domain-specific integration.
- Leaving every feature with availability handling, cancellation, recovery, and verification.
Workflow
- Identify the feature shape: availability, one-shot text, streaming, structured output, dynamic schema, tool calling, RAG, voice, HealthKit, multilingual, App Intent, or reusable capability extraction.
- Load only the reference file for that feature.
- Start from the packaged Swift recipe, then adapt naming, UI, permissions, and domain models to the target app.
- Keep reusable Foundation Models orchestration out of SwiftUI views when the feature will be shared by app screens, App Intents, CLI commands, widgets, or tests.
- Add graceful fallback behavior for unavailable Apple Intelligence, unsupported languages, denied permissions, context-window overflow, rate limits, decoding failures, and guardrail refusals.
- Verify with the narrowest build or test command that covers the changed surface.
Reference Routing
- Reusable app architecture, providers, use cases, SwiftUI adapters:
references/architecture.md
- Availability, sessions, instructions, generation options, streaming, prewarming:
references/availability-and-sessions.md
- Compile-time structured output with
@Generable and @Guide: references/structured-generation.md
- Runtime schemas with
DynamicGenerationSchema and GeneratedContent: references/dynamic-schemas.md
- Foundation Models tools and permission-aware app integrations:
references/tool-calling.md
- Retrieval-augmented generation and grounded prompts:
references/rag.md
- Speech recognition, text-to-speech, and voice state machines:
references/voice.md
- App Intents backed by shared Foundation Models capabilities:
references/app-intents.md
- HealthKit-backed AI features and safety wording:
references/healthkit.md
- Supported languages, language selection, and code switching:
references/multilingual.md
- Generation errors, guardrails, retries, and verification checks:
references/common-errors.md
Core Rules
- Use
@Generable when the output type is known at compile time.
- Use
DynamicGenerationSchema only when the schema is built at runtime.
- Create a fresh
LanguageModelSession for unrelated one-shot tasks; keep a session only when conversation memory matters.
- Put permissions and user confirmation at app boundaries, not inside model prompts.
- Keep streaming UI updates cancellable and main-actor safe.
- Avoid App Intent-only prompt logic. Shared tasks should be callable from the app UI too.
- Prefer compact, domain-specific instructions over giant prompts.
- Do not assume Foundation Models are available; check
SystemLanguageModel.default.availability.
Feature Contract
When adding a Foundation Models feature, aim to leave behind these pieces:
- a Swift type that names the task input
- a Swift type that names the task output
- a small generation provider or use case
- a UI, App Intent, or service adapter that calls the use case
- a model-unavailable path
- a cancellation path for streaming or long-running work
- a user-facing recovery path for generation errors
- a narrow verification command or manual check
