swift-code-reviewer-skill 1.1.1 → 1.2.1

package/bin/install.js

@@ -38,16 +38,7 @@ function copyRecursive(src, dest) {
   }
 }
 
-function install() {
-  log('\n  Swift Code Reviewer Skill Installer', colors.cyan + colors.bright);
-  log('  ====================================\n', colors.cyan);
-
-  // Determine paths
-  const homeDir = os.homedir();
-  const skillsDir = path.join(homeDir, '.claude', 'skills');
-  const targetDir = path.join(skillsDir, SKILL_NAME);
-
-  // Find package root (where SKILL.md is located)
+function findPackageRoot() {
   let packageRoot = __dirname;
   while (!fs.existsSync(path.join(packageRoot, 'SKILL.md'))) {
     const parent = path.dirname(packageRoot);
@@ -57,14 +48,23 @@ function install() {
     }
     packageRoot = parent;
   }
+  return packageRoot;
+}
+
+function install() {
+  log('\n  Swift Code Reviewer Skill Installer', colors.cyan + colors.bright);
+  log('  ====================================\n', colors.cyan);
+
+  const homeDir = os.homedir();
+  const skillsDir = path.join(homeDir, '.claude', 'skills');
+  const targetDir = path.join(skillsDir, SKILL_NAME);
+  const packageRoot = findPackageRoot();
 
-  // Check if Claude Code skills directory exists
   if (!fs.existsSync(skillsDir)) {
     log(`  Creating skills directory: ${skillsDir}`, colors.yellow);
     fs.mkdirSync(skillsDir, { recursive: true });
   }
 
-  // Check for existing installation
   if (fs.existsSync(targetDir)) {
     log(`  Updating existing installation at:`, colors.yellow);
     log(`  ${targetDir}\n`, colors.yellow);
@@ -74,10 +74,8 @@ function install() {
     log(`  ${targetDir}\n`, colors.blue);
   }
 
-  // Create target directory
   fs.mkdirSync(targetDir, { recursive: true });
 
-  // Files to copy
   const filesToCopy = [
     'SKILL.md',
     'README.md',
@@ -86,10 +84,8 @@ function install() {
     'CHANGELOG.md'
   ];
 
-  // Directories to copy
-  const dirsToCopy = ['references'];
+  const dirsToCopy = ['references', 'skills', 'templates'];
 
-  // Copy files
   for (const file of filesToCopy) {
     const src = path.join(packageRoot, file);
     const dest = path.join(targetDir, file);
@@ -100,7 +96,6 @@ function install() {
     }
   }
 
-  // Copy directories
   for (const dir of dirsToCopy) {
     const src = path.join(packageRoot, dir);
     const dest = path.join(targetDir, dir);
@@ -111,10 +106,11 @@ function install() {
     }
   }
 
-  // Success message
   log('\n  Installation complete!', colors.green + colors.bright);
   log('\n  The skill is now available in Claude Code.', colors.reset);
-  log('  Use it by asking Claude to:', colors.reset);
+  log('  To add the review agent and /review command to a project, run:', colors.reset);
+  log('\n    npx swift-code-reviewer-skill init\n', colors.cyan);
+  log('  Or use it directly by asking Claude to:', colors.reset);
   log('\n    - "Review this PR"', colors.cyan);
   log('    - "Review LoginView.swift"', colors.cyan);
   log('    - "Review my uncommitted changes"', colors.cyan);
@@ -124,6 +120,69 @@ function install() {
   log('  Documentation: https://github.com/Viniciuscarvalho/swift-code-reviewer-skill\n', colors.blue);
 }
 
+function init() {
+  log('\n  Swift Code Reviewer — Project Setup', colors.cyan + colors.bright);
+  log('  =====================================\n', colors.cyan);
+
+  const packageRoot = findPackageRoot();
+  const cwd = process.cwd();
+
+  // Verify we're in a git repo (likely a real project)
+  if (!fs.existsSync(path.join(cwd, '.git'))) {
+    log('  Warning: Not a git repository. Running anyway.\n', colors.yellow);
+  }
+
+  const claudeDir = path.join(cwd, '.claude');
+  const agentsDir = path.join(claudeDir, 'agents');
+  const commandsDir = path.join(claudeDir, 'commands');
+
+  const templateAgentSrc = path.join(packageRoot, 'templates', 'agents', 'swift-code-reviewer.md');
+  const templateCommandSrc = path.join(packageRoot, 'templates', 'commands', 'review.md');
+
+  // Check templates exist
+  if (!fs.existsSync(templateAgentSrc)) {
+    log('  Error: Agent template not found. Reinstall the skill with:', colors.red);
+    log('    npx swift-code-reviewer-skill\n', colors.cyan);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(agentsDir, { recursive: true });
+  fs.mkdirSync(commandsDir, { recursive: true });
+
+  let created = 0;
+  let skipped = 0;
+
+  // Copy agent
+  const agentDest = path.join(agentsDir, 'swift-code-reviewer.md');
+  if (fs.existsSync(agentDest)) {
+    log('  Skipped: .claude/agents/swift-code-reviewer.md (already exists)', colors.yellow);
+    skipped++;
+  } else {
+    fs.copyFileSync(templateAgentSrc, agentDest);
+    log('  Created: .claude/agents/swift-code-reviewer.md', colors.green);
+    created++;
+  }
+
+  // Copy command
+  const commandDest = path.join(commandsDir, 'review.md');
+  if (fs.existsSync(commandDest)) {
+    log('  Skipped: .claude/commands/review.md (already exists)', colors.yellow);
+    skipped++;
+  } else {
+    fs.copyFileSync(templateCommandSrc, commandDest);
+    log('  Created: .claude/commands/review.md', colors.green);
+    created++;
+  }
+
+  log(`\n  Done! ${created} file(s) created, ${skipped} skipped.`, colors.green + colors.bright);
+
+  if (created > 0) {
+    log('\n  Usage:', colors.reset);
+    log('    /review          — run a full code review before pushing', colors.cyan);
+    log('    @swift-code-reviewer — invoke the agent directly\n', colors.cyan);
+  }
+}
+
 function uninstall() {
   log('\n  Uninstalling Swift Code Reviewer Skill', colors.yellow + colors.bright);
   log('  ======================================\n', colors.yellow);
@@ -146,11 +205,13 @@ function showHelp() {
   log('  Usage: npx swift-code-reviewer-skill [command]\n', colors.reset);
   log('  Commands:', colors.bright);
   log('    (none)     Install the skill to ~/.claude/skills/', colors.reset);
+  log('    init       Scaffold agent + /review command into current project', colors.reset);
   log('    uninstall  Remove the skill from ~/.claude/skills/', colors.reset);
   log('    help       Show this help message\n', colors.reset);
   log('  Examples:', colors.bright);
-  log('    npx swift-code-reviewer-skill', colors.cyan);
-  log('    npx swift-code-reviewer-skill uninstall\n', colors.cyan);
+  log('    npx swift-code-reviewer-skill              # install skill globally', colors.cyan);
+  log('    npx swift-code-reviewer-skill init          # add agent + command to project', colors.cyan);
+  log('    npx swift-code-reviewer-skill uninstall     # remove skill\n', colors.cyan);
 }
 
 // Parse command line arguments
@@ -158,6 +219,10 @@ const args = process.argv.slice(2);
 const command = args[0];
 
 switch (command) {
+  case 'init':
+  case 'setup':
+    init();
+    break;
   case 'uninstall':
   case 'remove':
     uninstall();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swift-code-reviewer-skill",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Claude Code skill for comprehensive Swift/SwiftUI code reviews with multi-layer analysis",
   "keywords": [
     "claude",
@@ -9,9 +9,21 @@
     "swift",
     "swiftui",
     "code-review",
+    "code-quality",
+    "architecture-review",
+    "performance-audit",
+    "security-analysis",
+    "swift-6",
+    "async-await",
+    "sendable",
+    "concurrency",
     "ios",
     "macos",
-    "apple"
+    "apple",
+    "dependency-injection",
+    "testing",
+    "accessibility",
+    "best-practices"
   ],
   "author": "Vinicius Carvalho",
   "license": "MIT",
@@ -29,6 +41,8 @@
   "files": [
     "bin/",
     "references/",
+    "skills/",
+    "templates/",
     "SKILL.md",
     "README.md",
     "LICENSE",

package/references/companion-skills.md

@@ -0,0 +1,70 @@
+# Companion Skills Reference
+
+Full attribution and update instructions: [`skills/README.md`](../skills/README.md)
+Original authors: [@AvdLee](https://github.com/AvdLee), [@Dimillian](https://github.com/Dimillian), [@bocato](https://github.com/bocato)
+
+---
+
+## swiftui-expert-skill · `skills/swiftui-expert-skill/`
+
+| Reference file                         | When to consult                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `references/state-management.md`       | Property wrapper selection — @State, @Binding, @Observable, @Environment  |
+| `references/latest-apis.md`            | Deprecation detection — always check before flagging an API as deprecated |
+| `references/view-structure.md`         | View extraction rules and composition depth limits                        |
+| `references/performance-patterns.md`   | Equatable conformance, body evaluation cost, lazy loading                 |
+| `references/accessibility-patterns.md` | VoiceOver grouping, traits, Dynamic Type support                          |
+| `references/liquid-glass.md`           | iOS 26+ Liquid Glass adoption and availability gating                     |
+| `references/animation-basics.md`       | Implicit/explicit animation, withAnimation, matchedGeometryEffect         |
+| `references/macos-scenes.md`           | macOS-specific Scene types, window styling, settings                      |
+
+---
+
+## swift-concurrency · `skills/swift-concurrency/`
+
+| Reference file                     | When to consult                                             |
+| ---------------------------------- | ----------------------------------------------------------- |
+| `references/sendable.md`           | Sendable conformance, `@unchecked Sendable` justification   |
+| `references/actors.md`             | Actor isolation, custom actors vs @MainActor                |
+| `references/async-await-basics.md` | Structured vs unstructured tasks, `Task.detached` rationale |
+| `references/migration.md`          | Swift 6 migration patterns, minimum blast-radius approach   |
+| `references/testing.md`            | Concurrency-safe test patterns                              |
+| `references/threading.md`          | Thread safety, GCD interop, isolation boundaries            |
+
+---
+
+## swift-testing · `skills/swift-testing/`
+
+| Reference file                      | When to consult                                               |
+| ----------------------------------- | ------------------------------------------------------------- |
+| `references/test-organization.md`   | @Suite hierarchy, naming, tagging                             |
+| `references/test-doubles.md`        | Dummy / Fake / Stub / Spy / Mock taxonomy                     |
+| `references/async-testing.md`       | `#expect(throws:)`, async confirmation patterns               |
+| `references/parameterized-tests.md` | `@Test(arguments:)` for data-driven tests                     |
+| `references/migration-xctest.md`    | XCTest → Swift Testing migration checklist                    |
+| `references/fixtures.md`            | Fixture placement with `#if DEBUG`, test target vs app target |
+
+---
+
+## swift-expert · `skills/swift-expert/`
+
+| Reference file                     | When to consult                                                       |
+| ---------------------------------- | --------------------------------------------------------------------- |
+| `references/async-concurrency.md`  | Cross-cutting concurrency patterns                                    |
+| `references/protocol-oriented.md`  | Protocol hierarchies, associated types, existentials, `any` vs `some` |
+| `references/memory-performance.md` | Value vs reference semantics, ARC, retain cycles                      |
+| `references/swiftui-patterns.md`   | Additional SwiftUI architectural guidance                             |
+
+---
+
+## swiftui-ui-patterns · `skills/swiftui-ui-patterns/`
+
+| Reference file                   | When to consult                                           |
+| -------------------------------- | --------------------------------------------------------- |
+| `references/components-index.md` | Full component catalogue — start here for any UI pattern  |
+| `references/navigationstack.md`  | Route enums, RouterPath, `navigationDestination`          |
+| `references/sheets.md`           | Item-driven sheets, SheetDestination enum                 |
+| `references/theming.md`          | Semantic color enforcement via `@Environment(Theme.self)` |
+| `references/async-state.md`      | `.task(id:)`, LoadState enum, CancellationError           |
+| `references/tabview.md`          | Tab architecture, per-tab independent navigation history  |
+| `references/grids.md`            | LazyVGrid / LazyHGrid patterns and identity               |

package/skills/README.md

@@ -0,0 +1,43 @@
+# Bundled Companion Skills
+
+This directory contains five companion skills vendored directly into `swift-code-reviewer-skill` so that reviewers have a complete, self-contained knowledge base after a single install or clone — no extra setup required.
+
+## Thanks to the original authors
+
+These skills are based on the public Swift/SwiftUI work of three community contributors:
+
+| Author              | GitHub                                     | Known for                                                     |
+| ------------------- | ------------------------------------------ | ------------------------------------------------------------- |
+| Antoine van der Lee | [@AvdLee](https://github.com/AvdLee)       | SwiftLee — concurrency, testing, Swift 6 migration            |
+| Thomas Ricouard     | [@Dimillian](https://github.com/Dimillian) | IceCubesApp — SwiftUI architecture, Liquid Glass, UI patterns |
+| Eduardo Bocato      | [@bocato](https://github.com/bocato)       | Clean Architecture, protocol-oriented Swift, Swift expert     |
+
+Attribution is best-effort — upstream folders carried no `LICENSE` or `AUTHORS` files. If you are one of the original authors and want the attribution corrected or content removed, please [open an issue](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues).
+
+---
+
+## Skills index
+
+| Skill                                                 | Primary author | Description                                                                                     | References                                                                              |
+| ----------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [swiftui-expert-skill](swiftui-expert-skill/SKILL.md) | @Dimillian     | Write, review, or improve SwiftUI code: state management, view composition, Liquid Glass, macOS | [19 files](swiftui-expert-skill/references/) · [NOTICE](swiftui-expert-skill/NOTICE.md) |
+| [swift-concurrency](swift-concurrency/SKILL.md)       | @AvdLee        | Expert guidance on actors, Sendable, async/await, Swift 6 migration, data races                 | [13 files](swift-concurrency/references/) · [NOTICE](swift-concurrency/NOTICE.md)       |
+| [swift-testing](swift-testing/SKILL.md)               | @AvdLee        | Modern Swift Testing framework: @Test, #expect, doubles, snapshots, XCTest migration            | [9 files](swift-testing/references/) · [NOTICE](swift-testing/NOTICE.md)                |
+| [swift-expert](swift-expert/SKILL.md)                 | @bocato        | Senior Swift 6+ specialist: protocol-oriented design, memory, concurrency, SwiftUI patterns     | [5 files](swift-expert/references/) · [NOTICE](swift-expert/NOTICE.md)                  |
+| [swiftui-ui-patterns](swiftui-ui-patterns/SKILL.md)   | @Dimillian     | Component-level SwiftUI patterns: navigation, lists, sheets, grids, theming, gestures           | [32 files](swiftui-ui-patterns/references/) · [NOTICE](swiftui-ui-patterns/NOTICE.md)   |
+
+---
+
+## Updating a skill
+
+Each skill is a verbatim copy of its source. To refresh one:
+
+```bash
+rsync -rL --exclude='.DS_Store' ~/.agents/skills/swiftui-expert-skill/ skills/swiftui-expert-skill/
+rsync -rL --exclude='.DS_Store' ~/.claude/skills/swift-concurrency/ skills/swift-concurrency/
+rsync -rL --exclude='.DS_Store' ~/.claude/skills/swift-testing/ skills/swift-testing/
+rsync -rL --exclude='.DS_Store' ~/.maestro/skills/swift-expert/ skills/swift-expert/
+rsync -rL --exclude='.DS_Store' ~/.maestro/skills/swiftui-ui-patterns/ skills/swiftui-ui-patterns/
+```
+
+Do not edit files under `skills/` directly — changes will be overwritten on the next sync.

package/skills/swift-concurrency/NOTICE.md

@@ -0,0 +1,18 @@
+# swift-concurrency — Attribution Notice
+
+Bundled into `swift-code-reviewer-skill` on 2026-04-21 from
+`~/.claude/skills/swift-concurrency`.
+
+Primary author (best-effort attribution): **Antoine van der Lee ([@AvdLee](https://github.com/AvdLee))**
+Also credited: [@Dimillian](https://github.com/Dimillian), [@bocato](https://github.com/bocato)
+
+These three authors' public Swift/SwiftUI content — including SwiftLee, IceCubesApp,
+and their various open-source contributions — informed the skills bundled here.
+
+License: the upstream folder did not contain a LICENSE file at the time of vendoring.
+Content is reproduced here in good faith for reference alongside this MIT-licensed
+project. If you are an upstream author and want the attribution corrected, the license
+clarified, or the content removed, please open an issue at:
+https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues
+
+Changes from upstream: none (verbatim copy; `.DS_Store` files excluded).

package/skills/swift-concurrency/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: swift-concurrency
+description: '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).'
+---
+# Swift Concurrency
+
+## Overview
+
+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)
+
+1. 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.
+2. Before proposing fixes, identify the isolation boundary: `@MainActor`, custom actor, actor instance isolation, or nonisolated.
+3. Do not recommend `@MainActor` as a blanket fix. Justify why main-actor isolation is correct for the code.
+4. Prefer structured concurrency (child tasks, task groups) over unstructured tasks. Use `Task.detached` only with a clear reason.
+5. If recommending `@preconcurrency`, `@unchecked Sendable`, or `nonisolated(unsafe)`, require:
+   - a documented safety invariant
+   - a follow-up ticket to remove or migrate it
+6. For migration work, optimize for minimal blast radius (small, reviewable changes) and add verification steps.
+7. Course references are for deeper learning only. Use them sparingly and only when they clearly help answer the developer’s question.
+
+## 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`?)
+- Strict concurrency checking level (minimal/targeted/complete)
+- Whether upcoming features are enabled (especially `NonisolatedNonsendingByDefault`)
+- Swift language mode (Swift 5.x vs Swift 6) and SwiftPM tools version
+
+### Manual checks (no scripts)
+
+- SwiftPM:
+  - Check `Package.swift` for `.defaultIsolation(MainActor.self)`.
+  - Check `Package.swift` for `.enableUpcomingFeature("NonisolatedNonsendingByDefault")`.
+  - Check for strict concurrency flags: `.enableExperimentalFeature("StrictConcurrency=targeted")` (or similar).
+  - Check tools version at the top: `// swift-tools-version: ...`
+- Xcode projects:
+  - Search `project.pbxproj` for:
+    - `SWIFT_DEFAULT_ACTOR_ISOLATION`
+    - `SWIFT_STRICT_CONCURRENCY`
+    - `SWIFT_UPCOMING_FEATURE_` (and/or `SWIFT_ENABLE_EXPERIMENTAL_FEATURES`)
+
+If any of these are unknown, ask the developer to confirm them before giving migration-sensitive guidance.
+
+## Quick Decision Tree
+
+When a developer needs concurrency guidance, follow this decision tree:
+
+1. **Starting fresh with async code?**
+   - Read `references/async-await-basics.md` for foundational patterns
+   - For parallel operations → `references/tasks.md` (async let, task groups)
+
+2. **Protecting shared mutable state?**
+   - Need to protect class-based state → `references/actors.md` (actors, @MainActor)
+   - Need thread-safe value passing → `references/sendable.md` (Sendable conformance)
+
+3. **Managing async operations?**
+   - Structured async work → `references/tasks.md` (Task, child tasks, cancellation)
+   - Streaming data → `references/async-sequences.md` (AsyncSequence, AsyncStream)
+
+4. **Working with legacy frameworks?**
+   - Core Data integration → `references/core-data.md`
+   - General migration → `references/migration.md`
+
+5. **Performance or debugging issues?**
+   - Slow async code → `references/performance.md` (profiling, suspension points)
+   - Testing concerns → `references/testing.md` (XCTest, Swift Testing)
+
+6. **Understanding threading behavior?**
+   - Read `references/threading.md` for thread/task relationship and isolation
+
+7. **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
+```swift
+// Use for: Single asynchronous operations
+func fetchUser() async throws -> User {
+    try await networkClient.get("/user")
+}
+```
+
+**async let** - Running multiple independent async operations in parallel
+```swift
+// 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
+```swift
+// Use for: Fire-and-forget operations, bridging sync to async contexts
+Task {
+    await updateUI()
+}
+```
+
+**Task Group** - Dynamic parallel operations with structured concurrency
+```swift
+// 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
+```swift
+// 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
+```swift
+// Use for: View models, UI-related classes
+@MainActor
+class ViewModel: ObservableObject {
+    @Published var data: String = ""
+}
+```
+
+### Common Scenarios
+
+**Scenario: Network request with UI update**
+```swift
+Task { @concurrent in
+    let data = try await fetchData() // Background
+    await MainActor.run {
+        self.updateUI(with: data) // Main thread
+    }
+}
+```
+
+**Scenario: Multiple parallel network requests**
+```swift
+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**
+```swift
+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
+- **`tasks.md`** - Task lifecycle, cancellation, priorities, task groups, structured vs unstructured
+- **`threading.md`** - Thread/task relationship, suspension points, isolation domains, nonisolated
+- **`memory-management.md`** - Retain cycles in tasks, memory safety patterns
+- **`actors.md`** - Actor isolation, @MainActor, global actors, reentrancy, custom executors, Mutex
+- **`sendable.md`** - Sendable conformance, value/reference types, @unchecked, region isolation
+- **`linting.md`** - Concurrency-focused lint rules and SwiftLint `async_without_await`
+- **`async-sequences.md`** - AsyncSequence, AsyncStream, when to use vs regular async methods
+- **`core-data.md`** - NSManagedObject sendability, custom executors, isolation conflicts
+- **`performance.md`** - Profiling with Instruments, reducing suspension points, execution strategies
+- **`testing.md`** - XCTest async patterns, Swift Testing, concurrency testing utilities
+- **`migration.md`** - Swift 6 migration strategy, closure-to-async conversion, @preconcurrency, FRP migration
+
+## Best Practices Summary
+
+1. **Prefer structured concurrency** - Use task groups over unstructured tasks when possible
+2. **Minimize suspension points** - Keep actor-isolated sections small to reduce context switches
+3. **Use @MainActor judiciously** - Only for truly UI-related code
+4. **Make types Sendable** - Enable safe concurrent access by conforming to Sendable
+5. **Handle cancellation** - Check Task.isCancelled in long-running operations
+6. **Avoid blocking** - Never use semaphores or locks in async contexts
+7. **Test concurrent code** - Use proper async test methods and consider timing issues
+
+## Verification Checklist (When You Change Concurrency Code)
+
+- Confirm build settings (default isolation, strict concurrency, upcoming features) before interpreting diagnostics.
+- After refactors:
+  - Run tests, especially concurrency-sensitive ones (see `references/testing.md`).
+  - If performance-related, verify with Instruments (see `references/performance.md`).
+  - If lifetime-related, verify deinit/cancellation behavior (see `references/memory-management.md`).
+
+## Glossary
+
+See `references/glossary.md` for quick definitions of core concurrency terms used across this skill.
+
+---
+
+**Note**: This skill is based on the comprehensive [Swift Concurrency Course](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=skill-footer) by Antoine van der Lee.