agentleFS
apexbymanishapexbymanish/claude-ai-agents-ios/.claude/skills/swift-concurrency/SKILL.md

swift-concurrency

Skill0 starsChanged 3 months agoMITView on GitHub

Procedure for reviewing real Swift code for concurrency correctness — async/await, actors, Sendable, cancellation, task lifetime — not a Swift Concurrency tutorial. Use when the task involves async/await, Task, actors, MainActor, Sendable, or a data-race/concurrency question like "is this thread-safe?".

25 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use swiftdata, swift-testing and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Prisma-Labs-DevSkill

    swiftdata

    API reference: SwiftData. Query for @Model, ModelContext, @Query, schema migrations.

    Also in 3 projects that use this

  • pluginagentmarketplaceSkill

    swift-testing

    Test Swift applications - XCTest, Swift Testing, UI tests, mocking, TDD, CI/CD

    Also in 4 projects that use this

  • xfstudioSkill

    swiftui-expert-skill

    Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns.

    Also in 8 projects that use this

  • eugenepyvovarovSkill

    swift-concurrency-expert

    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.

    Also in 4 projects that use this

  • AvdLeeSkill

    swift-testing-expert

    Expert guidance for Swift Testing: test structure, #expect/#require macros, traits and tags, parameterized tests, test plans, parallel execution, async waiting patterns, and XCTest migration. Use when writing new Swift tests, modernizing XCTest suites, debugging flaky tests, or improving test quality and maintainability in Apple-platform or Swift server projects.

    Also in 3 projects that use this

  • twostrawsSkill

    swiftdata-pro

    Writes, reviews, and improves SwiftData code using modern APIs and best practices. Use when reading, writing, or reviewing projects that use SwiftData.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 24 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If ios-agent MCP is configured, mcp__ios-agent__review_swift_concurrency alongside the manual read — STATIC_ANALYSIS tier, same as reading …

    line 28
  2. Distinctive:

    Read the actual code — never assess concurrency from a description of it.

    line 71
  3. Very specific:

    Check which detection patterns above apply.

    line 73
  4. Distinctive:

    If the question is "is this thread-safe," don't answer yes/no from this reading alone — see Evidence Requirements.

    line 78
  5. Distinctive:

    If Swift 6 / strict concurrency mode isn't enabled, say so — it's the single highest-leverage recommendation available, since it turns …

    line 80
  6. Very specific:

    Never say "thread-safe" from this skill's static read alone — STATIC_ANALYSIS plus a concurrency-relevant test or Swift 6 strict-mode build …

    line 137
  7. Distinctive:

    Never say a data race "does not exist" — say "no data-race pattern found during static inspection."

    line 140
  8. Very specific:

    Never claim @unchecked Sendable usage is "safe" without stating the specific invariant that makes it safe (e.g.

    line 142

“Common” is measured: kept by at least 6 in 10 of the 24 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Swift Concurrency

Purpose

Review real project code for concurrency correctness, and grade every finding at the evidence tier it actually earned — never assert "thread-safe" from reading code alone.

When to Use

Any task touching async/await, Task, actors, @MainActor, Sendable, or a direct question about thread safety, data races, or cancellation behavior.

Inputs

  • The actual code under review — read it, don't reason about concurrency in the abstract.
  • Whether the project has Swift 6 language mode (or -strict-concurrency=complete under Swift 5) enabled — this changes what the compiler itself can prove vs. what only a careful read can flag.
  • If ios-agent MCP is configured, mcp__ios-agent__review_swift_concurrency alongside the manual read — STATIC_ANALYSIS tier, same as reading the code, never higher (per ios-evidence-reporting's tool-tier rule).

Core Knowledge

  • Structured vs. unstructured concurrency: async let and task groups tie a child task's lifetime to its parent's scope — the parent can't return until children finish or are cancelled. Unstructured Task {} has no such guarantee; it keeps running independent of whoever created it unless something explicitly cancels it.
  • @MainActor isolation: UI-touching state needs main-actor isolation. @Observable/ObservableObject types get no isolation for free — annotate the type (or the specific properties/methods that need it) explicitly.
  • Sendable: a type crossing an isolation boundary (passed into a Task, an actor method, or another isolation domain) needs to be safe to do so — genuinely immutable, internally synchronized, or a value type with no shared mutable state.
  • Actor reentrancy: an actor method that awaits can be re-entered by another call to the same actor during the suspension — actors are not a mutex. State checked before an await is not guaranteed to still hold after it resumes.
  • Cancellation is cooperative: calling .cancel() on a Task sets a flag; it does not stop execution. Code has to actually check Task.isCancelled or call try Task.checkCancellation() to respond.

Detection Patterns

PatternRiskDetect by
Unstructured Task {} in onAppear/init/button action, never stored or cancelledOutlives the view; can touch deallocated state or double-fire on re-rendergrep for Task { inside SwiftUI lifecycle hooks/actions with no stored handle and no .task {} alternative used
Long-running loop with no cancellation check.cancel() does nothing — work keeps running after the caller gave upgrep for/while loops inside async functions for absence of Task.isCancelled/checkCancellation
View-model type read/written from both SwiftUI and a background task, not @MainActorData race on non-Sendable state; Swift 6 refuses to compile, Swift 5 may silently corruptCheck whether types backing SwiftUI views carry @MainActor; check whether Swift 6 mode is even enabled to catch this at all
@unchecked Sendable / nonisolated(unsafe)Manually disables the compiler's only mechanical safety net for this type — a real race risk hiding behind a suppressiongrep for both exact terms
Task.detached used out of habitLoses the calling actor's isolation, priority, and task-local values (e.g. a request ID for logging) for no deliberate reasongrep Task.detached; check whether escaping context was actually intentional
Continuation (withCheckedContinuation) resumed on more than one path, or not on all pathsDouble-resume crashes at runtime; missed resume hangs the awaiting task foreverTrace every exit path (success, error, early return) out of the continuation closure
State read before an await inside an actor method, relied on unchanged after it resumesActor reentrancy — another call can interleave during the suspension and change that stateLook for a state read, then an await, then logic that trusts the pre-await value without re-checking
Task stored as a property, never cancelled in deinit/equivalentWastes resources or touches a gone context indefinitelyCheck every stored Task property has a matching cancel; prefer .task {} for SwiftUI, which handles this automatically

Procedure

  1. Read the actual code — never assess concurrency from a description of it.
  2. Check which detection patterns above apply; for each hit, read enough surrounding code to confirm it's real, not a false positive (e.g. a Task.detached that's genuinely meant to escape context).
  3. For each real finding, state: the pattern, the risk, and the concrete fix — a code diff, not a description of one.
  4. If the question is "is this thread-safe," don't answer yes/no from this reading alone — see Evidence Requirements.
  5. If Swift 6 / strict concurrency mode isn't enabled, say so — it's the single highest-leverage recommendation available, since it turns several of these patterns into compile errors instead of silent bugs.

Common Mistakes

  • Treating "no data race pattern found by reading" as "this is thread-safe" — a static read can't see the actual concurrent interleaving.
  • Suggesting @unchecked Sendable as a quick fix for a compiler warning instead of understanding what the warning is protecting against.
  • Recommending Task.detached as the default for "fire and forget" work — plain Task {} is almost always the right default.

Verification

  • A pattern match from step 2 above is STATIC_ANALYSIS.
  • Confirming the compiler rejects a violation under Swift 6 strict mode is BUILD_VERIFIED — genuinely stronger evidence than a manual read, since the compiler is checking every path, not just the ones read.
  • A concurrency-relevant test (e.g. asserting a task actually stops after cancellation, or a continuation resumes exactly once across its tested paths) is TEST_VERIFIED.
  • Actual concurrent behavior observed under Thread Sanitizer or in a real run is RUNTIME_VERIFIED.

Evidence Requirements

Per ios-evidence-reporting's matrix, "thread-safe" specifically requires STATIC_ANALYSIS and a concurrency-relevant test or Swift 6 strict-mode compilation — never inspection alone. Grade every finding honestly:

Claim:
"Task cancellation is handled correctly."

Static:
Cancellation path inspected — Task.isCancelled checked at the loop
boundary in FeedLoader.swift:88.

Tests:
No test currently exercises cancellation.

Runtime:
Not observed.

Final:
PARTIALLY VERIFIED — STATIC_ANALYSIS only. Recommend a test that
cancels mid-loop and asserts the loop actually stops.

Claim Restrictions

  • Never say "thread-safe" from this skill's static read alone — STATIC_ANALYSIS plus a concurrency-relevant test or Swift 6 strict-mode build is the minimum.
  • Never say a data race "does not exist" — say "no data-race pattern found during static inspection."
  • Never claim @unchecked Sendable usage is "safe" without stating the specific invariant that makes it safe (e.g. "immutable after init") — an unjustified suppression is itself a finding to report, not a claim to validate.

Output Format

One finding per issue: pattern name, file:line, risk, concrete fix (a diff, not prose), and the evidence tier the finding itself is graded at. Close with the ios-evidence-reporting status block.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.