Swift Concurrency Pro Agent Skill

The swift-concurrency-pro skill is designed to review Swift code for concurrency correctness, modern API usage, and common async/await pitfalls. It is specifically optimized for Swift 6.2 or later with strict concurrency checking enabled.

How to use

When invoking the skill, you can provide an optional [focus area] argument to narrow the scope of the review.

Core Review Principles

• Target Version: Focuses on Swift 6.2+ with strict concurrency.
• Structured Concurrency: Prefers task groups over unstructured Task {} blocks.
• Modern APIs: Prefers async/await over closure-based variants and Swift concurrency over Grand Central Dispatch (GCD).
• Safety over Silencing: Never suggests @unchecked Sendable to fix compiler errors; instead, it recommends actors, value types, or sending parameters.
• Context Awareness: Compares concurrency build settings across different targets or packages if the code spans multiple modules.

argument-hint: "[focus area]"

When using unstructured concurrency, understand the difference in actor isolation:

• Task {}: Inherits the caller's actor isolation. If called from a @MainActor function, the task body runs on the @MainActor, making it safe to perform UI updates.
• Task.detached {}: Does not inherit the caller's actor isolation or priority. It is used for genuinely independent background work that needs to shed the current actor context.

Best Practice: Prefer Task {} with explicit isolation changes or structured concurrency. Only use Task.detached when you specifically need to shed the caller's actor context and priority.

@MainActor
func example() {
    Task {
        // Still on MainActor; safe to update UI here.
        label.text = "Done"
    }

    Task.detached {
        // Not on MainActor; updating UI here is a bug.
        // Use this for genuinely independent background work.
    }
}

A common concurrency bug occurs when assuming an actor's state remains unchanged after an await call. Because actors are reentrant, other tasks may have modified the actor's state during the suspension point.

Best Practices:

1. Never assume state is unchanged after await.
2. Capture results in local variables: Instead of force-unwrapping an actor property after an await, assign the result of the async work to a local variable first, then update the actor state.
3. Manage in-flight tasks: To prevent multiple callers from performing the same expensive work (like downloading a file) simultaneously, store the Task in a dictionary (e.g., inFlight) and have subsequent callers await the existing task.

// Fix: Capture the result in a local, then assign to avoid reentrancy issues.
actor VideoCache {
    var items: [URL: Video] = [: ]

    func video(for url: URL) async throws -> Video {
        if let cached = items[url] { return cached }
        let video = try await downloadVideo(url)
        items[url] = video
        return video
    }
}

// Advanced: Use an in-flight dictionary to prevent duplicate work
actor VideoCache {
    var items: [URL: Video] = [:]
    var inFlight: [URL: Task<Video, Error>] = [:]

    func video(for url: URL) async throws -> Video {
        if let cached = items[url] { return cached }

        if let task = inFlight[url] {
            return try await task.value
        }

        let task = Task {
            try await downloadVideo(url)
        }

        inFlight[url] = task

        do {
            let video = try await task.value
            items[url] = video
            inFlight[url] = nil
            return video
        } catch {
            inFlight[url] = nil
            throw error
        }
    }
}

When performing reviews with this skill, the following technical constraints and preferences apply:

• Target Version: Swift 6.2 or later with strict concurrency checking enabled.
• Concurrency Model: Prefer Swift Concurrency over Grand Central Dispatch (GCD). GCD is acceptable for low-level, performance-critical synchronous work or framework interop, but should not be the default for new code.
• Structured vs Unstructured: Always prefer structured concurrency (e.g., TaskGroup) over unstructured tasks (Task {}).
• API Preference: If an API provides both async/await and closure-based variants, always prefer the async/await version.
• Avoid @unchecked Sendable: Do not suggest @unchecked Sendable to silence compiler errors. Instead, use actors, value types, or sending parameters to fix the underlying race condition. @unchecked Sendable should only be used for types with internal locking that are provably thread-safe.
• Build Settings: If code spans multiple targets or packages, compare their concurrency build settings to ensure consistent behavior.

In Swift 6.2, the mental model for nonisolated async functions has changed: a nonisolated async function now stays on the caller's actor by default unless it is explicitly offloaded elsewhere.

Implications:

• Calling a nonisolated async method on a helper struct no longer implies automatic background execution.
• If you require the function to run on the concurrent pool (background) rather than the caller's actor, you must use explicit offloading (such as the @concurrent attribute).

struct Measurements {
    func fetchLatest() async throws -> [Double] {
        let url = URL(string: "https://hws.dev/readings.json")!
        let (data, _) = try await URLSession.shared.data(from: url)
        return try JSONDecoder().decode([Double].self, from: data)
    }
}

@MainActor
struct WeatherStation {
    let measurements = Measurements()

    func getAverageTemperature() async throws -> Double {
        // In Swift 6.2, this call stays on the @MainActor
        let readings = try await measurements.fetchLatest()
        return readings.reduce(0, +) / Double(readings.count)
    }
}