Swift Concurrency Agent Skill: triage guidance loaded on demand

The payload is a skill directory and five client manifests

There is no library to add to a target and no module to import. What ships is reference material plus the manifests that tell a coding tool where to find it. The top-level tree gives the shape: a `skills/` directory, a root `plugin.json`, and per-client manifests in `.claude-plugin/`, `.codex-plugin/` and `.cursor-plugin/`, alongside an `agents/` directory and an `INSTALLATION.md`.

The discovery mechanism is the Agent Plugins format, spec 1.0.0. A compatible client finds the skill automatically from the root manifest and the `skills/` directory, which is why the same repository works across tools rather than needing a fork per editor. For the pi client the contract is a package manifest, and it is three lines:

{
  "keywords": ["pi-package"],
  "pi": {
    "skills": ["./skills/swift-concurrency"]
  }
}

The audience is stated plainly at the top: teams migrating to Swift 6 or strict concurrency who want safe defaults and quick triage, developers chasing data races and isolation errors and flaky async tests, and anyone who wants performance-minded patterns around actors, tasks, `Sendable` and async streams. The claim of neutrality is part of the pitch. The project describes itself as non-opinionated, aimed at industry-standard practice and compile-time safety rather than architectural preference, and it says it works with any Swift project, coding style or architecture.

Installing with skills.sh, and what the update command repairs

The recommended path is a single command, and it targets one skill out of the repository rather than cloning anything:

npx skills@latest add https://github.com/avdlee/swift-concurrency-agent-skill --skill swift-concurrency

After that, the skill is invoked from a prompt, and the README's own example asks the agent to analyse the current project for Swift Concurrency improvements. The repository also documents a migration edge case worth knowing before you hit it. If you installed before the move to Agent Plugins, the saved skill path is stale, and the fix is:

npx skills@latest update

That update needs skills CLI 1.5.24 or newer, and its stated purpose is to migrate the saved skill path without treating the skill as deleted. The distinction is small but the symptom is not: without it the tool can report a skill that was never removed.

The other clients take different routes rather than the same one. For ChatGPT and Codex the plugin is published in the OpenAI Plugins Directory, and installation happens in the ChatGPT desktop app by choosing Codex, or ChatGPT with Work enabled, or by using the plugin browser in Codex CLI, then opening Plugins and searching for Swift Concurrency. The skill becomes available in new chats and sessions, which matters if you were expecting it in the conversation you already have open. For Cursor, load the plugin from a local clone by placing it in `~/.cursor/plugins/local`, or install it from the Cursor Marketplace once listed. `INSTALLATION.md` covers pi, Gemini CLI, Autohand Code and manual installation.

Sharing it with a team through .claude/settings.json

For Claude Code there are two levels, and the second is the interesting one. Personal installation is two slash commands, first the marketplace, then the plugin:

/plugin marketplace add AvdLee/Swift-Concurrency-Agent-Skill

/plugin install swift-concurrency@swift-concurrency-agent-skill

Team-wide installation is a committed file rather than a manual step. The repository's `.claude/settings.json` example enables the plugin and registers the GitHub source of the marketplace:

{
  "enabledPlugins": {
    "swift-concurrency@swift-concurrency-agent-skill": true
  },
  "extraKnownMarketplaces": {
    "swift-concurrency-agent-skill": {
      "source": {
        "source": "github",
        "repo": "AvdLee/Swift-Concurrency-Agent-Skill"
      }
    }
  }
}

Commit that and every clone of the repository carries the intent. The described behaviour is a prompt: when team members open the project, Claude Code asks them to install the skill. That is a deliberate choice against silent enablement, and it has a matching cost, since the decision still lands on each person rather than on the build.

The same author publishes sibling skills for SwiftUI, Core Data and Swift Testing. Bundling by subject is convenient, and it also means a team ends up maintaining four plugin entries rather than one.

A triage playbook versus pasting a course chapter

This project is a distillation of a paid course, and the interesting engineering decision is not the content but the shape of it. The README's verification step is precise: your agent should reference the triage or playbook in `skills/swift-concurrency/SKILL.md` and then jump into the relevant reference file for the error or task in front of it. One entry point, many files, each opened on demand.

The alternative is the obvious one: read the course and paste the relevant chapter into your prompt. That works and it costs the same tokens on every single request, whether the question is about an actor reentrancy bug or about testing. It also puts you in charge of deciding which chapter applies, which is the judgement the skill was built to supply.

A third option sits between the two. Enable strict concurrency checking in the build and let the compiler emit the diagnostics. That is not a substitute, because a compiler names the offending declaration and a triage playbook is supposed to tell you which isolation boundary to move, but it is the part of the workflow that produces ground truth, and it costs nothing extra to keep. The skill's list of what it prevents, data races at compile time, is a statement about Swift's type system rather than about a Markdown file.

Six capability areas and the Swift 6.2 surface

The stated coverage runs from picking a tool to migrating an existing codebase. On decisions it covers choosing between async and await, actors, tasks and task groups, and deciding when `@MainActor`, a custom actor or `nonisolated` is the right one. On safe code it names actor reentrancy and retain cycles, task cancellation and error propagation, and memory in concurrent contexts. On performance it separates serialized, asynchronous and parallel execution, and points at actor contention and suspension points as the things to remove.

The migration material is the part aimed at an existing codebase rather than a new one: step-by-step strategies, enabling strict concurrency checking incrementally, rewriting closure-based code to async and await, and moving off Combine or RxSwift. The testing section names Swift Testing as the recommendation over XCTest, covers handling `@MainActor` isolation inside tests, and points at `withMainSerialExecutor` as the way to get deterministic behaviour instead of a retry loop.

There is also a Core Data section, which is unusual for a concurrency skill: passing data between isolation domains with `NSManagedObjectID`, the data access object pattern, custom actor executors, and the pitfalls people hit with Core Data concurrency. And the Swift 6.2 coverage is itemised rather than vague: default actor isolation, `isolated deinit`, global actor conformance for protocols, `nonisolated(nonsending)` and `@concurrent`, the Approachable Concurrency build settings, and concurrency-safe notifications on iOS 26 and later. The stated design rule for all of it is brevity, on the grounds that the agent is already smart and does not need material about things it already knows.

Where the guidance cannot enforce anything

Start with the honest limit. Every claim in this repository is a claim about what a language model will do when it reads some text. There is no hook, no build task, no linter and no test in the top-level tree, so an agent that ignores the skill behaves exactly as it did before, and there is no signal that tells you the skill went unused.

The verification advice is therefore prompt-shaped rather than mechanical. The README asks that your agent reference the playbook in `skills/swift-concurrency/SKILL.md` and open the relevant reference file. If you want a check, that sentence is the only thing to check against, and it is a habit to observe in a session rather than a gate to configure.

Second, the install paths are not equal in maturity. Cursor's route is a local clone or the Cursor Marketplace once listed, which reads as a listing that has not happened yet, while the ChatGPT and Codex route requires the desktop app or a plugin browser, so a browser-only ChatGPT account is not covered by what is written. And the skills.sh route has its own version floor, 1.5.24 for the update command that repairs a pre-migration install.

Third, the coverage is stated as of Swift 6.2 and iOS 26. A team on an older toolchain gets advice for a newer one, and nothing in the repository maps a feature back to the release it landed in.

MIT licence, releases in May and August, a push on 2026-09-14

The licence is MIT, and the payload being Markdown makes that licence close to decorative: there is no runtime dependency to satisfy, no transitive supply chain, and nothing to vendor. An upgrade is a re-fetch of text.

The release history is short and regular. Version 2.1.1 shipped on 2026-05-04, 2.2.0 on 2026-08-07, and 2.3.0 on 2026-08-12. The last push was on 2026-09-14, and the repository is not archived, so the content is still moving even though the releases are sparse.

That is the whole upgrade story, and its weakness is obvious. A Markdown skill cannot be pinned the way a library is, so a team that wants reproducibility has to commit the skill files themselves rather than point a manifest at a moving branch. The homepage is the Swift Concurrency Course, which is also where the guidance came from, and the practical question for anyone weighing this is whether the distilled version covers the ground your own codebase actually hits. The stated answer is that it assumes nothing about your architecture, which also means it will not know anything specific about it.

Editorial conclusion

Adopt it if your team is on Swift 6 or is debugging isolation errors, because a triage entry point plus per-topic reference files is a cheaper way to put that guidance in front of an agent than pasting a course chapter into every prompt. Do not expect anything to be enforced: nothing in the repository is a compiler flag, so strict concurrency checking still has to be turned on in your build settings. Confirm the install landed by checking that your agent opens skills/swift-concurrency/SKILL.md and the matching reference file instead of answering from memory.

Frequently asked questions

Official sources

1. AvdLee/Swift-Concurrency-Agent-Skill on GitHub
2. License: MIT
3. Project website
4. README
5. Releases