Skip to main content
Agent skill

Swift Actor Persistence

Thread-safe data persistence in Swift using actors — in-memory cache with file-backed storage, eliminating data races by design. Use when persisting data in Swift and a data race or thread-safety problem needs designing out.

Get started

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

·

When to use this skill

Use Swift Actor Persistence when an AI agent needs a reusable SKILL.md workflow for this job: Thread-safe data persistence in Swift using actors — in-memory cache with file-backed storage, eliminating data races by design. Use when persisting data in Swift and a data race or thread-safety problem needs designing out.

When not to use it

Skip Swift Actor Persistence when the task is outside the coding 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/swift-actor-persistence
# Save SKILL.md to ~/.claude/skills/swift-actor-persistence/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/swift-actor-persistence/SKILL.md. For a shared project, commit the folder at .claude/skills/swift-actor-persistence/ 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 Swift Actor Persistence skill for this task: Local data storage in iOS/macOS apps (user data, settings, cached content). 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
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

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

What this skill does

# Swift Actors for Thread-Safe Persistence

Patterns for building thread-safe data persistence layers using Swift actors. Combines in-memory caching with file-backed storage, leveraging the actor model to eliminate data races at compile time.

## When to Activate

- Building a data persistence layer in Swift 5.5+ - Need thread-safe access to shared mutable state - Want to eliminate manual synchronization (locks, DispatchQueues) - Building offline-first apps with local storage

## Core Pattern

### Actor-Based Repository

The actor model guarantees serialized access — no data races, enforced by the compiler.

```swift public actor LocalRepository<T: Codable & Identifiable> where T.ID == String { private var cache: [String: T] = [:] private let fileURL: URL

public init(directory: URL = .documentsDirectory, filename: String = "data.json") { self.fileURL = directory.appendingPathComponent(filename) // Synchronous load during init (actor isolation not yet active) self.cache = Self.loadSynchronously(from: fileURL) }

// MARK: - Public API

public func save(_ item: T) throws { cache[item.id] = item try persistToFile() }

public func delete(_ id: String) throws { cache[id] = nil try persistToFile() }

public func find(by id: String) -> T? { cache[id] }

public func loadAll() -> [T] { Array(cache.values) }

// MARK: - Private

private func persistToFile() throws { let data = try JSONEncoder().encode(Array(cache.values)) try data.write(to: fileURL, options: .atomic) }

private static func loadSynchronously(from url: URL) -> [String: T] { guard let data = try? Data(contentsOf: url), let items = try? JSONDecoder().decode([T].self, from: data) else { return [:] } return Dictionary(uniqueKeysWithValues: items.map { ($0.id, $0) }) } } ```

### Usage

All calls are automatically async due to actor isolation:

```swift let repository = LocalRepository<Question>()

// Read — fast O(1) lookup from in-memory cache let question = await repository.find(by: "q-001") let allQuestions = await repository.loadAll()

// Write — updates cache and persists to file atomically try await repository.save(newQuestion) try await repository.delete("q-001") ```

### Combining with @Observable ViewModel

```swift @Observable final class QuestionListViewModel { private(set) var questions: [Question] = [] private let repository: LocalRepository<Question>

init(repository: LocalRepository<Question> = LocalRepository()) { self.repository = repository }

func load() async { questions = await repository.loadAll() }

func add(_ question: Question) async throws { try await repository.save(question) questions = await repository.loadAll() } } ```

## Key Design Decisions

| Decision | Rationale | |----------|-----------| | Actor (not class + lock) | Compiler-enforced thread safety, no manual synchronization | | In-memory cache + file persistence | Fast reads from cache, durable writes to disk | | Synchronous init loading | Avoids async initialization complexity | | Dictionary keyed by ID | O(1) lookups by identifier | | Generic over `Codable & Identifiable` | Reusable across any model type | | Atomic file writes (`.atomic`) | Prevents partial writes on crash |

## Best Practices

- **Use `Sendable` types** for all data crossing actor boundaries - **Keep the actor's public API minimal** — only expose domain operations, not persistence details - **Use `.atomic` writes** to prevent data corruption if the app crashes mid-write - **Load synchronously in `init`** — async initializers add complexity with minimal benefit for local files - **Combine with `@Observable`** ViewModels for reactive UI updates

## Anti-Patterns to Avoid

- Using `DispatchQueue` or `NSLock` instead of actors for new Swift concurrency code - Exposing the internal cache dictionary to external callers - Making the file URL configurable without validation - Forgetting that all actor method calls are `await` — callers must handle async context - Using `nonisolated` to bypass actor isolation (defeats the purpose)

## When to Use

- Local data storage in iOS/macOS apps (user data, settings, cached content) - Offline-first architectures that sync to a server later - Any shared mutable state that multiple parts of the app access concurrently - Replacing legacy `DispatchQueue`-based thread safety with modern Swift concurrency

Intended uses

  • Local data storage in iOS/macOS apps (user data, settings, cached content)
  • Offline-first architectures that sync to a server later
  • Any shared mutable state that multiple parts of the app access concurrently
  • Replacing legacy DispatchQueue-based thread safety with modern Swift concurrency

Implementation notes

  • Use Sendable types for all data crossing actor boundaries
  • Keep the actor's public API minimal — only expose domain operations, not persistence details
  • Use .atomic writes to prevent data corruption if the app crashes mid-write
  • Load synchronously in init — async initializers add complexity with minimal benefit for local files
  • Combine with @Observable ViewModels for reactive UI updates

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.