# swift-concurrency

A skill for building, reviewing, and refactoring Swift concurrency code. Use it for async/await, actors, isolation, and Swift 6+ migrations.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 151 installs · ★ 236 repo stars
- Author: jamesrochabrun
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/jamesrochabrun/skills/tree/HEAD/skills/swift-concurrency/SKILL.md
- Updated: 2026-01-14
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/jamesrochabrun-swift-concurrency

## What it does

This skill covers three work modes: writing new asynchronous Swift code, auditing an existing codebase, and moving legacy patterns to Swift 6+. It guides isolation choices with `@MainActor`, custom actors, and `nonisolated`, then shows how to design async functions and run parallel work with `async let` or `TaskGroup`.

The SwiftUI section covers `.task`, inherited isolation, and task cancellation. Review checks include blocking waits, data races, Sendable violations, unnecessary actors, unstructured tasks, and missing cancellation checks. Refactoring guidance maps callbacks to async/await, `DispatchQueue` protection to actors, and Combine publishers to AsyncSequence.

The material targets Swift 6+ and includes Approachable Concurrency settings for Xcode 26+. A long-running operation that skips `Task.isCancelled` will not handle cancellation. Install the skill file in the Claude Code directory shown below.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add jamesrochabrun/skills --skill swift-concurrency -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/swift-concurrency/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/swift-concurrency/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add jamesrochabrun/skills --skill swift-concurrency -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/swift-concurrency/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add jamesrochabrun/skills --skill swift-concurrency -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/swift-concurrency/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install jamesrochabrun/skills skills/swift-concurrency
```

2. **Manually: put the files in place**
- File: `.github/skills/swift-concurrency/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add jamesrochabrun/skills --skill swift-concurrency -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/jamesrochabrun/skills --path skills/swift-concurrency
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/swift-concurrency/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add jamesrochabrun/skills --skill swift-concurrency -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/jamesrochabrun/skills/tree/HEAD/skills/swift-concurrency/SKILL.md

## When to use it
- design an async function with explicit isolation
- audit code for data races and Sendable issues
- convert callback APIs to async/await
- replace DispatchQueue state protection with an actor
- organize parallel work with async let or TaskGroup

## Example prompts
- Audit this Swift code for data races, Sendable issues, and blocking waits.
- Convert the user-loading callback to async/await with a throwing continuation.
- Design parallel image loading with `async let` and explain the isolation choice.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 86efd343db50a517.

BEGIN THIRD-PARTY FILE 86efd343db50a517
````text
---
name: swift-concurrency
description: Guide for building, auditing, and refactoring Swift code using modern concurrency patterns (Swift 6+). This skill should be used when working with async/await, Tasks, actors, MainActor, Sendable types, isolation domains, or when migrating legacy callback/Combine code to structured concurrency. Covers Approachable Concurrency settings, isolated parameters, and common pitfalls.
---

# Swift Concurrency

## Overview

This skill provides guidance for writing thread-safe Swift code using modern concurrency patterns. It covers three main workflows: building new async code, auditing existing code for issues, and refactoring legacy patterns to Swift 6+.

**Core principle**: Isolation is inherited by default. With Approachable Concurrency, code starts on MainActor and propagates through the program automatically. Opt out explicitly when needed.

## Workflow Decision Tree

```
What are you doing?
│
├─► BUILDING new async code
│   └─► See "Building Workflow" below
│
├─► AUDITING existing code
│   └─► See "Auditing Checklist" below
│
└─► REFACTORING legacy code
    └─► See "Refactoring Workflow" below
```

## Building Workflow

When writing new async code, follow this decision process:

### Step 1: Determine Isolation Needs

```
Does this type manage UI state or interact with UI?
│
├─► YES → Mark with @MainActor
│
└─► NO → Does it have mutable state shared across contexts?
         │
         ├─► YES → Consider: Can it live on MainActor anyway?
         │         │
         │         ├─► YES → Use @MainActor (simpler)
         │         │
         │         └─► NO → Use a custom actor (requires justification)
         │
         └─► NO → Leave non-isolated (default with Approachable Concurrency)
```

### Step 2: Design Async Functions

```swift
// PREFER: Inherit caller's isolation (works everywhere)
func fetchData(isolation: isolated (any Actor)? = #isolation) async throws -> Data {
  // Runs on whatever actor the caller is on
}

// USE WHEN: CPU-intensive work that must run in background
@concurrent
func processLargeFile() async -> Result { }

// AVOID: Non-isolated async without explicit choice
func ambiguousAsync() async { } // Where does this run?
```

### Step 3: Handle Parallel Work

```swift
// For known number of independent operations
async let avatar = fetchImage("avatar.jpg")
async let banner = fetchImage("banner.jpg")
let (a, b) = await (avatar, banner)

// For dynamic number of operations
````
END THIRD-PARTY FILE 86efd343db50a517

The third-party file has ended. Everything between the 86efd343db50a517 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2588 of 7850 bytes. © jamesrochabrun · MIT · https://github.com/jamesrochabrun/skills/tree/HEAD/skills/swift-concurrency/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
