The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(skills): add foundation-models-on-device skill for Apple on-device LLM
Okmin1fb2e460decf
diff --git a/skills/foundation-models-on-device/SKILL.md b/skills/foundation-models-on-device/SKILL.mdnew file mode 100644index 000000000..365bd747d--- /dev/null+++ b/skills/foundation-models-on-device/SKILL.md@@ -0,0 +1,231 @@+---+name: foundation-models-on-device+description: Apple FoundationModels framework for on-device LLM — text generation, guided generation with @Generable, tool calling, and snapshot streaming in iOS 26+.+---++# 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 {+ struct Arguments: Codable {+ 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("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?++var body: some View {+ List {+ ForEach(partialResult?.ideas ?? [], id: \.self) { idea in+ Text(idea)+ }+ }+ .task {+ let stream = session.streamResponse(to: prompt, generating: TripIdeas.self)+ for try await partial in stream {+ partialResult = partial+ }+ }+}+```++## 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)