Expert guidance on Swift Concurrency best practices, patterns, and implementation. Use when developers mention: (1) Swift Concurrency, async/await, actors, or tasks, (2) "use Swift Concurrency" or "modern concurrency patterns", (3) migrating to Swift 6, (4) data races or thread safety issues, (5) refactoring closures to async/await, (6) @MainActor, Sendable, or actor isolation, (7) concurrent code architecture or performance optimization, (8) concurrency-related linter warnings (SwiftLint or similar; e.g. async_without_await, Sendable/actor isolation/MainActor lint).
This skill provides expert guidance on Swift Concurrency, covering modern async/await patterns, actors, tasks, Sendable conformance, and migration to Swift 6. Use this skill to help developers write safe, performant concurrent code and navigate the complexities of Swift's structured concurrency model.
Agent Behavior Contract (Follow These Rules)
Analyze the project/package file to find out which Swift language mode (Swift 5.x vs Swift 6) and which Xcode/Swift toolchain is used when advice depends on it.
Before proposing fixes, identify the isolation boundary: @MainActor, custom actor, actor instance isolation, or nonisolated.
Do not recommend @MainActor as a blanket fix. Justify why main-actor isolation is correct for the code.
Prefer structured concurrency (child tasks, task groups) over unstructured tasks. Use Task.detached only with a clear reason.
If recommending @preconcurrency, @unchecked Sendable, or nonisolated(unsafe), require:
a documented safety invariant
a follow-up ticket to remove or migrate it
For migration work, optimize for minimal blast radius (small, reviewable changes) and add verification steps.
Course references are for deeper learning only. Use them sparingly and only when they clearly help answer the developer's question.
Recommended Tools for Analysis
When analyzing Swift projects for concurrency issues:
Project Settings Discovery
Use Read on Package.swift for SwiftPM settings (tools version, strict concurrency flags, upcoming features)
Use Grep for SWIFT_STRICT_CONCURRENCY or SWIFT_DEFAULT_ACTOR_ISOLATION in .pbxproj files
Use Grep for SWIFT_UPCOMING_FEATURE_ to find enabled upcoming features
Project Settings Intake (Evaluate Before Advising)
Concurrency behavior depends on build settings. Always try to determine:
Default actor isolation (is the module default @MainActor or nonisolated?)
Testing concerns β references/testing.md (XCTest, Swift Testing)
Understanding threading behavior?
Read references/threading.md for thread/task relationship and isolation
Memory issues with tasks?
Read references/memory-management.md for retain cycle prevention
Triage-First Playbook (Common Errors -> Next Best Move)
SwiftLint concurrency-related warnings
Use references/linting.md for rule intent and preferred fixes; avoid dummy awaits as βfixesβ.
SwiftLint async_without_await warning
Remove async if not required; if required by protocol/override/@concurrent, prefer narrow suppression over adding fake awaits. See references/linting.md.
"Sending value of non-Sendable type ... risks causing data races"
First: identify where the value crosses an isolation boundary
Then: use references/sendable.md and references/threading.md (especially Swift 6.2 behavior changes)
"Main actor-isolated ... cannot be used from a nonisolated context"
First: decide if it truly belongs on @MainActor
Then: use references/actors.md (global actors, nonisolated, isolated parameters) and references/threading.md (default isolation)
"Class property 'current' is unavailable from asynchronous contexts" (Thread APIs)
Use references/threading.md to avoid thread-centric debugging and rely on isolation + Instruments
XCTest async errors like "wait(...) is unavailable from asynchronous contexts"
Use references/testing.md (await fulfillment(of:) and Swift Testing patterns)
Core Data concurrency warnings/errors
Use references/core-data.md (DAO/NSManagedObjectID, default isolation conflicts)
Core Patterns Reference
When to Use Each Concurrency Tool
async/await - Making existing synchronous code asynchronous
// Use for: Single asynchronous operations
func fetchUser() async throws -> User {
try await networkClient.get("/user")
}
async let - Running multiple independent async operations in parallel
// Use for: Fixed number of parallel operations known at compile time
async let user = fetchUser()
async let posts = fetchPosts()
let profile = try await (user, posts)
Task - Starting unstructured asynchronous work
// Use for: Fire-and-forget operations, bridging sync to async contexts
Task {
await updateUI()
}
Task Group - Dynamic parallel operations with structured concurrency
// Use for: Unknown number of parallel operations at compile time
await withTaskGroup(of: Result.self) { group in
for item in items {
group.addTask { await process(item) }
}
}
Actor - Protecting mutable state from data races
// Use for: Shared mutable state accessed from multiple contexts
actor DataCache {
private var cache: [String: Data] = [:]
func get(_ key: String) -> Data? { cache[key] }
}
@MainActor - Ensuring UI updates on main thread
// Use for: View models, UI-related classes
@MainActor
class ViewModel: ObservableObject {
@Published var data: String = ""
}
Common Scenarios
Scenario: Network request with UI update
Task { @concurrent in
let data = try await fetchData() // Background
await MainActor.run {
self.updateUI(with: data) // Main thread
}
}
Scenario: Multiple parallel network requests
async let users = fetchUsers()
async let posts = fetchPosts()
async let comments = fetchComments()
let (u, p, c) = try await (users, posts, comments)
Scenario: Processing array items in parallel
await withTaskGroup(of: ProcessedItem.self) { group in
for item in items {
group.addTask { await process(item) }
}
for await result in group {
results.append(result)
}
}
Swift 6 Migration Quick Guide
Key changes in Swift 6:
Strict concurrency checking enabled by default
Complete data-race safety at compile time
Sendable requirements enforced on boundaries
Isolation checking for all async boundaries
For detailed migration steps, see references/migration.md.
Reference Files
Load these files as needed for specific topics:
async-await-basics.md - async/await syntax, execution order, async let, URLSession patterns
