agentleFS
agenticlukeagenticluke/apple-on-device-ai-plus/skill/SKILL.md

foundation-models-on-device

Skill0 starsChanged 2 months agoMITView on GitHub

Build private, offline AI features with Apple's FoundationModels framework. Use it for text, typed output, tools, and live updates.

15 other projects use a version of this, 15 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use ralphinho-rfc-pipeline, claude-devfleet and 7 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • junimnjwSkill

    ralphinho-rfc-pipeline

    RFC-driven multi-agent DAG execution pattern with quality gates, merge queues, and work unit orchestration.

    Also in 3 projects that use this

  • junimnjwSkill

    claude-devfleet

    Orchestrate multi-agent coding tasks via Claude DevFleet — plan projects, dispatch parallel agents in isolated worktrees, monitor progress, and read structured reports.

    Also in 3 projects that use this

  • CodeWithBehnamSkill

    x-api

    X/Twitter API integration for posting tweets, threads, reading timelines, search, and analytics. Covers OAuth auth patterns, rate limits, and platform-native content posting. Use when the user wants to interact with X programmatically.

    Also in 3 projects that use this

  • ClineSkill

    exa-search

    Deep research powered by Exa. Use for lead generation, literature reviews, deep dives, competitive analysis, or any query where one search falls short, including phrases like 'research this', 'find everything about', 'find me all', or 'deep dive on'.

    Also in 3 projects that use this

  • +5 more from junimnjw

The file

Show its rules and text

We split this skill into the rules it gives an agent

33 rules. 0 are common, 28 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 14 edited versions we read keep these.

  • 28

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use Apple's FoundationModels framework to run language tasks on the device.

    line 8
  2. Distinctive:

    Use this skill when an app needs to:

    line 21
  3. Distinctive:

    Write or sum up text

    line 23
  4. Distinctive:

    Keep user data on the device

    line 28
  5. Distinctive:

    Do not use it when:

    line 30
  6. Distinctive:

    Only use FoundationModels on supported OS and device versions.

    line 45
  7. Distinctive:

    Check the model before you make a session:

    line 49
  8. Distinctive:

    Do not hide the whole app when the model is not ready.

    line 78
  9. Distinctive:

    Use a new session for a one-time task:

    line 82
  10. Distinctive:

    Do not place secrets in instructions or prompts.

    line 128
  11. Very specific:

    Use @Generable when your app needs fields, not free text.

    line 132
  12. Very specific:

    Read results from response.content.

    line 166
  13. Distinctive:

    Keep each field clear and small.

    line 176
  14. Distinctive:

    Check typed output before you save it or use it for an important action.

    line 178
  15. Distinctive:

    Ask the user before a tool does a risky action, such as:

    line 257
  16. Distinctive:

    Do not add each snapshot to the old one.

    line 291
  17. Distinctive:

    Update view state on the main actor when the code runs outside SwiftUI's task context.

    line 340
  18. Distinctive:

    Do not turn “Maya may visit next week” into a task.

    line 406
  19. Distinctive:

    Before sending work, check:

    line 412
  20. Distinctive:

    Keep instructions, prompts, tool results, chat history, and output small.

    line 422
  21. Distinctive:

    Start a new session if old chat is no longer needed.

    line 427
  22. Distinctive:

    Do not split in the middle of a sentence or data record.

    line 429
  23. Distinctive:

    Check model availability before use.

    line 451
  24. Very specific:

    Use @Generable for data fields.

    line 453
  25. Very specific:

    Read results from response.content.

    line 454
  26. Distinctive:

    Check model and tool output before important use.

    line 456
  27. Distinctive:

    Keep prompts and tool results small.

    line 457
  28. Distinctive:

    Use a new session when chat history is not needed.

    line 458
  29. Distinctive:

    Test on real supported devices.

    line 461
  30. Distinctive:

    Use Xcode Instruments to check speed, memory, and power use.

    line 462
  31. Very specific:

    Use .output instead of .content.

    line 470
  32. Distinctive:

    Put many steps into one large prompt.

    line 473
  33. Distinctive:

    Keep old chat history forever.

    line 474

“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

FoundationModels: On-Device LLM for iOS 26

Use Apple's FoundationModels framework to run language tasks on the device.

This skill covers:

  • Text generation
  • Typed output with @Generable
  • Custom tools
  • Live result streams
  • Safe error handling
  • Private and offline use

When to Use This Skill

Use this skill when an app needs to:

  • Write or sum up text
  • Turn plain text into Swift data
  • Show an answer as it is made
  • Let the model call app code
  • Work without the cloud
  • Keep user data on the device

Do not use it when:

  • The device cannot run Apple Intelligence
  • The task needs live web data and no local tool can provide it
  • The input is too large for the model
  • The task needs facts the on-device model may not know

Required Setup

Import the framework:

import FoundationModels

Only use FoundationModels on supported OS and device versions. Add a fallback UI for older or unsupported devices.

Check Model Availability First

Check the model before you make a session:

struct GenerativeView: View {
    private let model = SystemLanguageModel.default

    var body: some View {
        switch model.availability {
        case .available:
            ContentView()

        case .unavailable(.deviceNotEligible):
            Text("This device cannot use Apple Intelligence.")

        case .unavailable(.appleIntelligenceNotEnabled):
            Text("Turn on Apple Intelligence in Settings.")

        case .unavailable(.modelNotReady):
            Text("The language model is not ready yet.")

        case .unavailable(let reason):
            Text("The language model is not available: \(reason)")
        }
    }
}

Availability can change. Check it again when the app returns to the front or before an important task.

Do not hide the whole app when the model is not ready. Keep other features working and show a clear fallback.

Basic Text Generation

Use a new session for a one-time task:

let session = LanguageModelSession()

do {
    let response = try await session.respond(
        to: "What is a good month to visit Paris?"
    )
    print(response.content)
} catch {
    print("The request failed: \(error.localizedDescription)")
}

Reuse one session when later prompts need the earlier chat:

let session = LanguageModelSession(instructions: """
You are a cooking helper.
Suggest meals from the food the user has.
Keep each answer short.
Do not claim that food is safe if you are not sure.
""")

let first = try await session.respond(
    to: "I have chicken and rice."
)

let second = try await session.respond(
    to: "Give me a meat-free choice instead."
)

print(first.content)
print(second.content)

Good instructions should say:

  • Who the model should act as
  • What task it should do
  • What shape the answer should have
  • How long the answer should be
  • What it must not do
  • What to say when key facts are missing

Do not place secrets in instructions or prompts. On-device work helps privacy, but logs, crash reports, and tool code may still leak data.

Typed Output with @Generable

Use @Generable when your app needs fields, not free text.

Define a Type

@Generable(description: "Basic facts about a cat")
struct CatProfile {
    var name: String

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

    @Guide(description: "One short sentence about the cat's nature")
    var profile: String
}

Ask for That Type

let session = LanguageModelSession()

let response = try await session.respond(
    to: "Make a profile for a cute rescue cat.",
    generating: CatProfile.self
)

let cat = response.content

print("Name: \(cat.name)")
print("Age: \(cat.age)")
print("Profile: \(cat.profile)")

Read results from response.content. Do not use response.output.

Guide Rules

Common guide rules include:

  • .range(0...20) for a number range
  • .count(3) for an exact list size
  • description: for plain rules about a field

Keep each field clear and small. If a field may not be known, make it optional. Do not force the model to invent missing facts.

Check typed output before you save it or use it for an important action. A valid Swift value can still be wrong.

Custom Tool Calls

A tool lets the model ask your app to do a set task.

Define a Tool

struct RecipeSearchTool: Tool {
    let name = "recipe_search"
    let description = """
    Find recipes that match a search term.
    Return no more than the requested count.
    """

    @Generable
    struct Arguments {
        var searchTerm: String

        @Guide(description: "Number of recipes", .range(1...5))
        var numberOfResults: Int
    }

    func call(arguments: Arguments) async throws -> ToolOutput {
        let recipes = try await searchRecipes(
            term: arguments.searchTerm,
            limit: arguments.numberOfResults
        )

        let text = recipes
            .map { "- \($0.name): \($0.description)" }
            .joined(separator: "\n")

        return .string(text.isEmpty ? "No recipes found." : text)
    }
}

Add the Tool to a Session

let session = LanguageModelSession(
    tools: [RecipeSearchTool()]
)

let response = try await session.respond(
    to: "Find three pasta recipes."
)

print(response.content)

Handle Tool Errors

do {
    let response = try await session.respond(
        to: "Find a tomato soup recipe."
    )
    print(response.content)
} catch let error as LanguageModelSession.ToolCallError {
    print("Tool failed: \(error.tool.name)")

    if let recipeError = error.underlyingError as? RecipeSearchToolError {
        switch recipeError {
        case .databaseIsEmpty:
            print("No recipes are stored.")
        default:
            print("Recipe search failed.")
        }
    }
} catch {
    print("The request failed: \(error.localizedDescription)")
}

Tool code must check all input. Treat model-made tool input like user input.

Ask the user before a tool does a risky action, such as:

  • Deleting data
  • Buying an item
  • Sending a message
  • Sharing private data
  • Changing an account

Set time limits for slow tools. Support task canceling. Return short tool results so the session does not fill up.

Live Snapshot Streaming

A stream sends full partial values. It does not send text changes.

@Generable
struct TripIdeas {
    @Guide(description: "Three short trip ideas", .count(3))
    var ideas: [String]
}

let session = LanguageModelSession()

let stream = session.streamResponse(
    to: "Give me three fun trip ideas.",
    generating: TripIdeas.self
)

for try await partial in stream {
    // Each field in PartiallyGenerated may be missing.
    print(partial)
}

Do not add each snapshot to the old one. Replace the old snapshot with the new snapshot.

SwiftUI Example

struct TripIdeasView: View {
    let prompt: String
    let session: LanguageModelSession

    @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)
                    .padding()
            }
        }
        .task(id: prompt) {
            partialResult = nil
            errorMessage = nil

            do {
                let stream = session.streamResponse(
                    to: prompt,
                    generating: TripIdeas.self
                )

                for try await partial in stream {
                    try Task.checkCancellation()
                    partialResult = partial
                }
            } catch is CancellationError {
                // The view closed or the prompt changed.
            } catch {
                errorMessage = "Could not make trip ideas."
            }
        }
    }
}

Update view state on the main actor when the code runs outside SwiftUI's task context.

One Full Example

This example turns a note into a small task list:

import FoundationModels

@Generable(description: "A task found in a user's note")
struct TaskItem {
    var title: String

    @Guide(description: "True only when the note gives a due date")
    var hasDueDate: Bool

    var dueDateText: String?
}

@Generable(description: "Tasks found in a user's note")
struct TaskList {
    @Guide(description: "No more than five tasks")
    var tasks: [TaskItem]
}

func readTasks(from note: String) async throws -> [TaskItem] {
    let model = SystemLanguageModel.default

    guard case .available = model.availability else {
        return []
    }

    let cleanNote = note.trimmingCharacters(in: .whitespacesAndNewlines)
    guard !cleanNote.isEmpty else {
        return []
    }

    let session = LanguageModelSession(instructions: """
Find only tasks that the user clearly asked to do.
Do not make up dates.
Keep each title short.
Return no more than five tasks.
""")

    let response = try await session.respond(
        to: cleanNote,
        generating: TaskList.self
    )

    return Array(response.content.tasks.prefix(5))
}

Example input:

Call Sam tomorrow. Buy milk. Maya may visit next week.

Expected kind of result:

Call Sam, due tomorrow
Buy milk, no due date

Do not turn “Maya may visit next week” into a task. It is not a clear action for the user.

Session Limits

A session handles one request at a time. Do not start two requests on the same session.

Before sending work, check:

guard !session.isResponding else {
    return
}

For work that may run at the same time, use separate sessions.

Keep instructions, prompts, tool results, chat history, and output small. They share the model's context space. If a request is too large:

  1. Split the input into small parts.
  2. Process one part at a time.
  3. Join the short results.
  4. Start a new session if old chat is no longer needed.

Do not split in the middle of a sentence or data record.

Error and State Rules

Handle these cases:

  • The model is not available.
  • The user turns off Apple Intelligence.
  • The model is still being set up.
  • The prompt is empty.
  • The task is canceled.
  • The app moves to the back.
  • A tool fails or takes too long.
  • The session is already busy.
  • The input is too large.
  • The model refuses the request.
  • Typed output is valid but has bad facts.

Show simple error text to the user. Log only safe details. Never log a full private prompt by default.

Best Practices

  • Check model availability before use.
  • Give short and clear instructions.
  • Use @Generable for data fields.
  • Read results from response.content.
  • Replace old stream snapshots with new ones.
  • Check model and tool output before important use.
  • Keep prompts and tool results small.
  • Use a new session when chat history is not needed.
  • Cancel work when its screen closes.
  • Give the user a useful fallback.
  • Test on real supported devices.
  • Use Xcode Instruments to check speed, memory, and power use.

Common Mistakes

Do not:

  • Assume every device can use the model.
  • send two requests through one session at once.
  • Use .output instead of .content.
  • Parse free text when a typed result fits.
  • Trust made-up facts just because the type is valid.
  • Put many steps into one large prompt.
  • Keep old chat history forever.
  • Append streamed snapshots as if they were changes.
  • Let a tool act without checking its input.
  • Let the model make risky changes without user approval.
  • Claim that no data leaves the device if your tools, logs, or app code send it out.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.