Swift Concurrency Agent Skill

为支持 Agent Skills 开放格式 的任何 AI 编码工具提供专家级指导——涵盖安全并发、性能优化以及 Swift 6+ 迁移。

本技能基于全面的 Swift Concurrency 课程，并将其提炼为供 AI Agent 使用的简洁、可执行的参考指南。

适用对象

• 正在迁移至 Swift 6 / 严格并发检查，需要安全默认配置及快速分类问题的团队。
• 正在调试数据竞争（data races）、隔离错误或不稳定（flaky）异步测试的开发者。
• 任何希望应用高性能并发模式（如 actors、tasks、Sendable、async streams）的开发者。

参阅我的其他技能：

• SwiftUI Expert
• Core Data Expert
• Swift Testing Expert

如何使用此技能

选项 A：使用 skills.sh（推荐）

通过单条命令安装此技能：

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

欲了解更多信息，请访问 skills.sh 平台页面。

随后即可在 AI Agent 中使用，例如：

Use the swift concurrency skill and analyze the current project for Swift Concurrency improvements

选项 B：Claude Code 插件

个人使用

在 Claude Code 中为个人安装此技能：

1. 添加市场：

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

2. 安装技能：

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

项目配置

若要自动为仓库中的所有贡献者提供此技能，请配置仓库的 .claude/settings.json：

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

当团队成员打开该项目时，Claude Code 将提示他们安装此技能。

选项 C：使用 pi 包管理器

通过 pi 安装：

pi install https://github.com/AvdLee/Swift-Concurrency-Agent-Skill

该技能将在 pi 会话中自动可用。

选项 D：手动安装

1. Clone 此仓库。
2. 按照您所用工具的官方技能安装文档，安装或创建软链接（symlink） swift-concurrency/ 文件夹（参阅下方链接）。
3. 正常使用 AI 工具，并要求它使用 “swift-concurrency” 技能来处理 Swift 并发任务。

技能存放位置

请遵循您所用工具的官方文档，以下是一些常用工具的参考：

• Codex: 技能存放位置
• Claude: 使用 Skills
• Cursor: 启用 Skills

验证方法：

您的 Agent 应当引用 swift-concurrency/SKILL.md 中的分类/手册，并针对您的错误或任务跳转到相关的参考文件。

此技能提供的内容

本技能为您的 AI 编码工具提供全面的 Swift 并发指导，涵盖以下方面：

指导并发决策

• 为任务选择正确的工具（async/await、actors、tasks、task groups）
• 理解何时使用 @MainActor、自定义 actors 或 nonisolated
• 梳理隔离域，并在编译时预防数据竞争
• 正确应用 Sendable 一致性（针对值类型和引用类型）

编写安全并发代码

• 避免 actor 重入（reentrancy）和循环引用等常见陷阱
• 通过适当的隔离防止数据竞争
• 正确处理任务取消和错误传播
• 在并发上下文中安全地管理内存

优化性能

• 在序列化、异步和并行执行之间做出最优选择
• 减少 actor 争用和不必要的挂起点
• 理解并行性能的权衡点

迁移至 Swift 6

• 针对现有代码库的分步迁移策略
• 逐步启用严格并发检查
• 将基于闭包的代码重写为 async/await
• 从 Combine/RxSwift 迁移至 Swift Concurrency
• 使用迁移工具处理即将推出的 Swift 特性

测试并发代码

• 使用 Swift Testing（推荐）或 XCTest 编写可靠的测试
• 处理测试中的 @MainActor 隔离
• 使用 withMainSerialExecutor 进行确定性测试
• 通过正确的异步处理避免不稳定的测试

集成 Core Data

• 使用 NSManagedObjectID 在隔离域之间安全传递数据
• 实现数据访问对象（Data Access Object）