Skip to main content
Agent skill

Foundation Models On Device

Apple FoundationModels framework for on-device LLM — text generation, guided generation with @Generable, tool calling, and snapshot streaming in iOS 26+. Use when adding on-device LLM features with Apple FoundationModels on iOS 26+.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Foundation Models On Device when an AI agent needs a reusable SKILL.md workflow for this job: Apple FoundationModels framework for on-device LLM — text generation, guided generation with @Generable, tool calling, and snapshot streaming in iOS 26+. Use when adding on-device LLM features with Apple FoundationModels on iOS 26+.

When not to use it

Skip Foundation Models On Device when the task is outside the creativity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/foundation-models-on-device
# Save SKILL.md to ~/.claude/skills/foundation-models-on-device/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/foundation-models-on-device/SKILL.md. For a shared project, commit the folder at .claude/skills/foundation-models-on-device/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Foundation Models On Device skill for this task: On-device text generation for privacy-sensitive apps. Confirm any required inputs or files before making changes.

What supports this recommendation?

88/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
100/100
Practical detail
100/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# FoundationModels: On-Device LLM (iOS 26)

Patterns for integrating Apple's on-device language model into apps using the FoundationModels framework. Covers text generation, structured output with `@Generable`, custom tool calling, and snapshot streaming — all running on-device for privacy and offline support.

## When to Activate

- Building AI-powered features using Apple Intelligence on-device - Generating or summarizing text without cloud dependency - Extracting structured data from natural language input - Implementing custom tool calling for domain-specific AI actions - Streaming structured responses for real-time UI updates - Need privacy-preserving AI (no data leaves the device)

## Core Pattern — Availability Check

Always check model availability before creating a session:

```swift struct GenerativeView: View { private var model = SystemLanguageModel.default

var body: some View { switch model.availability { case .available: ContentView() case .unavailable(.deviceNotEligible): Text("Device not eligible for Apple Intelligence") case .unavailable(.appleIntelligenceNotEnabled): Text("Please enable Apple Intelligence in Settings") case .unavailable(.modelNotReady): Text("Model is downloading or not ready") case .unavailable(let other): Text("Model unavailable: \(other)") } } } ```

## Core Pattern — Basic Session

```swift // Single-turn: create a new session each time let session = LanguageModelSession() let response = try await session.respond(to: "What's a good month to visit Paris?") print(response.content)

// Multi-turn: reuse session for conversation context let session = LanguageModelSession(instructions: """ You are a cooking assistant. Provide recipe suggestions based on ingredients. Keep suggestions brief and practical. """)

let first = try await session.respond(to: "I have chicken and rice") let followUp = try await session.respond(to: "What about a vegetarian option?") ```

Key points for instructions: - Define the model's role ("You are a mentor") - Specify what to do ("Help extract calendar events") - Set style preferences ("Respond as briefly as possible") - Add safety measures ("Respond with 'I can't help with that' for dangerous requests")

## Core Pattern — Guided Generation with @Generable

Generate structured Swift types instead of raw strings:

### 1. Define a Generable Type

```swift @Generable(description: "Basic profile information about a cat") struct CatProfile { var name: String

@Guide(description: "The age of the cat", .range(0...20)) var age: Int

@Guide(description: "A one sentence profile about the cat's personality") var profile: String } ```

### 2. Request Structured Output

```swift let response = try await session.respond( to: "Generate a cute rescue cat", generating: CatProfile.self )

// Access structured fields directly print("Name: \(response.content.name)") print("Age: \(response.content.age)") print("Profile: \(response.content.profile)") ```

### Supported @Guide Constraints

- `.range(0...20)` — numeric range - `.count(3)` — array element count - `description:` — semantic guidance for generation

## Core Pattern — Tool Calling

Let the model invoke custom code for domain-specific tasks:

### 1. Define a Tool

```swift struct RecipeSearchTool: Tool { let name = "recipe_search" let description = "Search for recipes matching a given term and return a list of results."

@Generable struct Arguments { var searchTerm: String var numberOfResults: Int }

func call(arguments: Arguments) async throws -> ToolOutput { let recipes = await searchRecipes( term: arguments.searchTerm, limit: arguments.numberOfResults ) return .string(recipes.map { "- \($0.name): \($0.description)" }.joined(separator: "\n")) } } ```

### 2. Create Session with Tools

```swift let session = LanguageModelSession(tools: [RecipeSearchTool()]) let response = try await session.respond(to: "Find me some pasta recipes") ```

### 3. Handle Tool Errors

```swift do { let answer = try await session.respond(to: "Find a recipe for tomato soup.") } catch let error as LanguageModelSession.ToolCallError { print(error.tool.name) if case .databaseIsEmpty = error.underlyingError as? RecipeSearchToolError { // Handle specific tool error } } ```

## Core Pattern — Snapshot Streaming

Stream structured responses for real-time UI with `PartiallyGenerated` types:

```swift @Generable struct TripIdeas { @Guide(description: "Ideas for upcoming trips") var ideas: [String] }

let stream = session.streamResponse( to: "What are some exciting trip ideas?", generating: TripIdeas.self )

for try await partial in stream { // partial: TripIdeas.PartiallyGenerated (all properties Optional) print(partial) } ```

### SwiftUI Integration

```swift @State private var partialResult: TripIdeas.PartiallyGenerated? @State private var errorMessage: String?

var body: some View { List { ForEach(partialResult?.ideas ?? [], id: \.self) { idea in Text(idea) } } .overlay { if let errorMessage { Text(errorMessage).foregroundStyle(.red) } } .task { do { let stream = session.streamResponse(to: prompt, generating: TripIdeas.self) for try await partial in stream { partialResult = partial } } catch { errorMessage = error.localizedDescription } } } ```

## Key Design Decisions

| Decision | Rationale | |----------|-----------| | On-device execution | Privacy — no data leaves the device; works offline | | 4,096 token limit | On-device model constraint; chunk large data across sessions | | Snapshot streaming (not deltas) | Structured output friendly; each snapshot is a complete partial state | | `@Generable` macro | Compile-time safety for structured generation; auto-generates `PartiallyGenerated` type | | Single request per session | `isResponding` prevents concurrent requests; create multiple sessions if needed | | `response.content` (not `.output`) | Correct API — always access results via `.content` property |

## Best Practices

- **Always check `model.availability`** before creating a session — handle all unavailability cases - **Use `instructions`** to guide model behavior — they take priority over prompts - **Check `isResponding`** before sending a new request — sessions handle one request at a time - **Access `response.content`** for results — not `.output` - **Break large inputs into chunks** — 4,096 token limit applies to instructions + prompt + output combined - **Use `@Generable`** for structured output — stronger guarantees than parsing raw strings - **Use `GenerationOptions(temperature:)`** to tune creativity (higher = more creative) - **Monitor with Instruments** — use Xcode Instruments to profile request performance

## Anti-Patterns to Avoid

- Creating sessions without checking `model.availability` first - Sending inputs exceeding the 4,096 token context window - Attempting concurrent requests on a single session - Using `.output` instead of `.content` to access response data - Parsing raw string responses when `@Generable` structured output would work - Building complex multi-step logic in a single prompt — break into multiple focused prompts - Assuming the model is always available — device eligibility and settings vary

## When to Use

- On-device text generation for privacy-sensitive apps - Structured data extraction from user input (forms, natural language commands) - AI-assisted features that must work offline - Streaming UI that progressively shows generated content - Domain-specific AI actions via tool calling (search, compute, lookup)

Intended uses

  • On-device text generation for privacy-sensitive apps
  • Structured data extraction from user input (forms, natural language commands)
  • AI-assisted features that must work offline
  • Streaming UI that progressively shows generated content
  • Domain-specific AI actions via tool calling (search, compute, lookup)

Implementation notes

  • Always check model.availability before creating a session — handle all unavailability cases
  • Use instructions to guide model behavior — they take priority over prompts
  • Check isResponding before sending a new request — sessions handle one request at a time
  • Access response.content for results — not .output
  • Break large inputs into chunks — 4,096 token limit applies to instructions + prompt + output combined
  • Use @Generable for structured output — stronger guarantees than parsing raw strings
  • Use GenerationOptions(temperature:) to tune creativity (higher = more creative)
  • Monitor with Instruments — use Xcode Instruments to profile request performance

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.