home / skills / steipete / agent-scripts / swift-concurrency-expert

swift-concurrency-expert skill

safe

This skill reviews Swift concurrency usage in 6.2+ projects and applies minimal, safe fixes to improve isolation, Sendable safety, and performance.

npx playbooks add skill steipete/agent-scripts --skill swift-concurrency-expert

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.8 KB

---
name: swift-concurrency-expert
description: Swift Concurrency review and remediation for Swift 6.2+. Use when asked to review Swift Concurrency usage, improve concurrency compliance, or fix Swift concurrency compiler errors in a feature or file.
---

# Swift Concurrency Expert

_Attribution: copied from @Dimillian’s `Dimillian/Skills` (2025-12-31)._

## Overview

Review and fix Swift Concurrency issues in Swift 6.2+ codebases by applying actor isolation, Sendable safety, and modern concurrency patterns with minimal behavior changes.

## Workflow

### 1. Triage the issue

- Capture the exact compiler diagnostics and the offending symbol(s).
- Identify the current actor context (`@MainActor`, `actor`, `nonisolated`) and whether a default actor isolation mode is enabled.
- Confirm whether the code is UI-bound or intended to run off the main actor.

### 2. Apply the smallest safe fix

Prefer edits that preserve existing behavior while satisfying data-race safety.

Common fixes:
- **UI-bound types**: annotate the type or relevant members with `@MainActor`.
- **Protocol conformance on main actor types**: make the conformance isolated (e.g., `extension Foo: @MainActor SomeProtocol`).
- **Global/static state**: protect with `@MainActor` or move into an actor.
- **Background work**: move expensive work into a `@concurrent` async function on a `nonisolated` type or use an `actor` to guard mutable state.
- **Sendable errors**: prefer immutable/value types; add `Sendable` conformance only when correct; avoid `@unchecked Sendable` unless you can prove thread safety.


## Reference material

- See `references/swift-6-2-concurrency.md` for Swift 6.2 changes, patterns, and examples.
- See `references/swiftui-concurrency-tour-wwdc.md` for SwiftUI-specific concurrency guidance.

Overview

This skill provides Swift Concurrency review and remediation for Swift 6.2+ codebases. I focus on applying actor isolation, Sendable safety, and modern async/await patterns to resolve compiler errors and data-race risks while preserving existing behavior. Use this skill when you need a targeted, minimal change fix or a guided refactor for concurrency issues.

How this skill works

I triage compiler diagnostics to identify offending symbols, current actor contexts, and whether code is UI-bound or intended for background execution. I then apply the smallest safe fix—annotations, actor extraction, or API adjustments—preferencing fixes that preserve semantics. When necessary I provide guidance on Sendable conformance, nonisolated/actor separation, and safe background execution patterns.

When to use it

Compiler errors related to actor isolation, Sendable, or main-actor inference in Swift 6.2+ projects
Review and harden concurrency usage before release or code review
Refactor shared/global mutable state to eliminate data races
Migrate UI-bound code to @MainActor or decouple heavy work off the main actor
Ensure protocol conformances and extensions comply with actor isolation rules

Best practices

Capture exact diagnostics and the smallest reproducible code sample before changing code
Prefer the minimal annotation or extraction that fixes the issue to avoid behavioral changes
Annotate UI-facing types with @MainActor and move heavy work to nonisolated async functions or actors
Favor immutable/value types and explicit Sendable conformance; avoid @unchecked Sendable unless proven safe
Use actors to encapsulate mutable state rather than broad global locks or unchecked sharing

Example use cases

Fixing 'isolated function' or 'non-sendable type' compiler errors in a view model
Converting a global cache to an actor to prevent concurrent mutation crashes
Annotating protocol conformances to match main-actor types without changing public API
Moving expensive parsing or network work off the main actor and returning results via async
Reviewing Sendable conformance for custom types used across Tasks and actors

FAQ

Will fixes change runtime behavior?

I aim for the smallest safe change that preserves behavior; when behavior changes are required I describe them and propose migration steps.

When is @unchecked Sendable acceptable?

Only when you can prove thread safety (immutable state, no shared mutable references). Prefer explicit safe design or actor encapsulation.