Guide · Agent skill
How to use the Swift Actor Persistence agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The swift-actor-persistence skill is a set of written guidelines that teaches an AI agent to build a local data storage layer for Swift apps on iOS or macOS. Once it is installed, the agent suggests and writes code that uses Swift actors to keep shared data safe when several parts of an app read and write at once, and it saves data to a JSON file on the device using atomic writes. This guide explains what the skill does, how to install it, how to ask for it, and what to watch for.
Swift Actor Persistenceaffaan-m/ECC · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page and unzip it to get the swift-actor-persistence folder with SKILL.md.
- 2Choose where to install. Copy the folder to ~/.claude/skills/ for all projects, or to a project's .claude/skills/ folder for one project. In the Claude apps, upload it under Settings → Capabilities → Skills.
- 3Check your project. Confirm you use Swift 5.9 or later and target iOS 17+ or macOS 14+, and that your models are Codable and Identifiable with String IDs.
- 4Describe your task. Ask for a thread-safe local store in plain language, naming your model and mentioning Swift, actors, or local storage.
- 5Review the generated code. Check the actor's public API, the atomic write, and that callers use await. Confirm the data is not sensitive.
- 6Test with your app. Run the store in your app, save and delete items, restart it, and confirm the data loads back from the JSON file.
What is an agent skill, and what does this one do?
An agent skill is a folder of instructions that an AI agent loads when a task matches it. This skill is a single file, SKILL.md, and it contains no executable scripts. It only changes the code and advice the agent produces.
When active, the agent aims for an in-memory cache backed by a file. The pattern is a generic actor-based repository that stores items keyed by their string ID, loads its data from a JSON file at startup, and writes the full contents back with the .atomic write option after each save or delete.
- Actor-based repository: the actor serializes access, so the compiler enforces that reads and writes do not race.
- In-memory cache: reads come from a dictionary, so lookups by ID are fast.
- File-backed storage: changes are written to a JSON file, and .atomic writes help prevent partial files if the app crashes mid-write.
- ViewModel pattern: the skill shows how to connect the repository to an @Observable view model for UI updates.
Install the swift-actor-persistence skill
Download the ZIP from this page and unzip it. You can install the skill in one of two ways, depending on how you use your agent.
For Claude Code, copy the unzipped skill folder into ~/.claude/skills/ to make it available in all your projects, or into a project's .claude/skills/ folder to limit it to that project.
In the Claude apps, you can upload the skill under Settings → Capabilities → Skills instead.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with a request?
You do not need a special command. Describe the task in plain language that mentions Swift, local storage, or thread safety. The skill is meant to activate when you are building a persistence layer in Swift 5.9+ with iOS 17+ or macOS 14+, need thread-safe access to shared mutable state, want to remove manual locks or DispatchQueues, or are building offline-first apps.
Be specific about your model type and where the data should live. The skill's generic repository works with any type that is Codable and Identifiable with a String ID.
- "Create a thread-safe local store for my Swift Question model using an actor and a JSON file."
- "Replace the NSLock-protected cache in my iOS app with an actor-based repository."
- "Add offline storage to my macOS app with an @Observable view model that loads and saves items."
Example: what the agent produces
Given a request for a local store, the agent typically writes a public actor generic over T: Codable & Identifiable where T.ID == String. It holds a private cache dictionary and a file URL, loads the file synchronously in init, and exposes save, delete, find(by:), and loadAll. Callers use await because actor methods are asynchronous from outside the actor.
The skill also covers how to connect this to UI. A view model marked @Observable calls await repository.loadAll() in a load function and refreshes its published questions list after each add.
let repository = LocalRepository<Question>()
let question = await repository.find(by: "q-001")
try await repository.save(newQuestion)What do you need before you start?
The skill assumes a Swift project that targets Swift 5.9 or later and Apple platforms, specifically iOS 17+ or macOS 14+ as stated in the skill. Your models must conform to Codable and Identifiable with a String ID, because the repository depends on those types.
The skill runs no scripts and uses no network access, so it does not need any tools beyond your agent and your Swift toolchain.
- Swift 5.9 or later
- iOS 17+ or macOS 14+ targets
- Models that are Codable and Identifiable with String IDs
Safety notes and limits
The skill does not mention encryption, and the storage file is plain JSON on the device. Do not use this pattern for passwords, health records, or other sensitive data unless you add your own protection. The whole dataset is loaded into memory as one file, so it is not suited to large or relational data. For that, look at Core Data, SwiftData, or SQLite.
The guidance also warns against using nonisolated to bypass actor isolation and against exposing the internal cache dictionary, so review the agent's code for those patterns.
- Not for sensitive data: the file is unencrypted JSON.
- Not for large or relational datasets: everything is loaded into memory.
- Not for non-Swift projects: the guidance covers only Swift and Apple platforms.
Tips for better results
Give the agent your existing code when you migrate, so it can map DispatchQueue or NSLock sections to actor methods. Ask it to keep the actor's public API limited to domain operations, as the skill recommends.
Check that every type crossing the actor boundary is Sendable, and that callers handle the await calls.
- Share the current model type and any lock or queue code you want replaced.
- Ask for the public API to stay minimal, with no exposed cache.
- Ask the agent to explain any use of nonisolated before accepting it.
What people use it for
- An offline-first iOS note or task app that keeps user items in a local JSON file.
- A macOS app that caches settings or user content in one file and updates a SwiftUI list through an @Observable view model.
- Migrating an older app that guards a dictionary with NSLock or DispatchQueue to an actor-based repository.
- A small iOS app that needs a consistent starting pattern for an in-memory cache backed by a file.
Frequently asked questions
How do I install the swift-actor-persistence skill?
Download the ZIP from this page and unzip it. Copy the folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills.
Does the swift-actor-persistence skill run code or need the internet?
No. According to the source, the skill runs no scripts and uses no network. It only shapes the code and advice the agent writes.
What are the requirements for this skill?
You need Swift 5.9 or later and Apple platform targets of iOS 17+ or macOS 14+, as stated in the skill. Your models should be Codable and Identifiable with String IDs.
Is the swift-actor-persistence skill free?
The skill is published under the MIT licence. Check the licence file in the source repository for the full terms.
Can I use this skill to store passwords or health records?
Not as written. The skill does not mention encryption and the storage file is plain JSON, so sensitive data needs extra protection that the skill does not provide.
When should I use Core Data or SwiftData instead?
Use a database such as Core Data, SwiftData, or SQLite for large or relational data. This pattern loads everything into memory as one JSON file, which does not scale well to large datasets.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if you build offline-first iOS or macOS apps in Swift and want an actor-based, file-backed store that replaces manual locks or DispatchQueues. Pick a database framework such as Core Data, SwiftData, or SQLite for large or relational data, and do not use this pattern for sensitive information without adding encryption yourself.
Download the skill