AvdLee SwiftUI-Agent-Skill：按需加载的 SwiftUI 最佳实践

大多数 AI 助手对 SwiftUI 的理解停留在"Stack Overflow 答案"的水平。AvdLee/SwiftUI-Agent-Skill 反其道而行之：把按主题整理好的参考文件在 agent 需要时再加载，避免模型在 @StateObject 与 @Observable 之间乱猜，也不会随手用错 layout 容器。

为什么这个 Skill 重要

README 把项目定位为可移植的 Agent Plugin（规范 1.0.0）：兼容的客户端可以从根目录的 plugin.json manifest 与 skills/ 目录自动发现这个 skill。仓库内置了 Claude Code、Cursor、Codex 与 pi 的客户端 manifest，README 与其 INSTALLATION.md 另外记录了 ChatGPT（Work 模式）与 Gemini CLI 的安装路径。该 skill 不强加架构或代码风格偏好，只聚焦正确性与性能。

仓库在 GitHub 上有 3.5k star，MIT 许可。README 上的 skills.sh 徽章显示周安装量为 16.6k（以徽章快照为准，数字会随时变化）——重要的是安装量已经让它跻身当下最广泛采用的 SwiftUI skill 之一。

参考覆盖面广却不挤占 agent 的任务上下文，因为文件是按需加载的：

• 状态管理（property wrappers、@Observable、数据流模式）
• 视图组合（抽取模式、容器视图、identity 稳定性）
• 性能（热路径优化、懒加载、@Observable 粒度）
• 列表与 ForEach（稳定 identity、Table、内联过滤的陷阱）
• 导航与 sheets（NavigationStack、NavigationSplitView、Inspector、基于 enum 的 sheet）
• Swift Charts（marks、axes、selection、styling、accessibility、Chart3D）
• 动画（implicit/explicit、transitions、phase/keyframe、@Animatable 宏）
• macOS 场景、窗口样式、Table、HSplitView、AppKit 互操作
• Liquid Glass（iOS 26+ 玻璃效果、容器、降级模式）
• Accessibility（VoiceOver、Dynamic Type、grouping、traits）
• 图片优化（AsyncImage、降采样、缓存）
• 最新 API（从 iOS 15+ 到 iOS 26+ 的废弃→现代迁移指南）
• Instruments trace 录制与分析（包装 xctrace 的 Python 工具链）

安装

README 推荐的 skills.sh 安装路径：

npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill

在 Claude Code 上，README 给出的插件市场方式：

/plugin marketplace add AvdLee/SwiftUI-Agent-Skill
/plugin install swiftui-expert@swiftui-expert-skill

如果想让全队成员在打开项目时都被提示安装，把下面这段加到 .claude/settings.json：

{
  "enabledPlugins": {
    "swiftui-expert@swiftui-expert-skill": true
  },
  "extraKnownMarketplaces": {
    "swiftui-expert-skill": {
      "source": {
        "source": "github",
        "repo": "AvdLee/SwiftUI-Agent-Skill"
      }
    }
  }
}

在 Codex 或 ChatGPT（Work 模式）中，README 指向 OpenAI Plugins Directory——在 Plugins 浏览器里搜 "SwiftUI Expert"。在 Cursor 上，README 指出仓库同时提供了可移植的 Agent Plugins manifest（plugin.json）和 Cursor Plugin manifest（.cursor-plugin/plugin.json）。

实战：以状态与性能为切入点评审一个 SwiftUI 视图

你接手了一个动画卡顿、子视图在父组件每次刷新时都重建的 SwiftUI 页面。让 agent 加载这个 skill 评审一遍。

Step 1. 用下面这种措辞触发 skill：

Use the swiftui expert skill and review the current SwiftUI code for state-management and performance improvements.

Step 2. agent 会先打开 skills/swiftui-expert-skill/SKILL.md，再根据当前文件跳转到 references/state-management.md 和 references/performance-patterns.md。

Step 3. skill 引导 agent 给出的一些常见修法：

• 如果模型仅面向 iOS 17+，把 @StateObject + ObservableObject 换成 @Observable。
• 把状态往下推，让拥有自己 @State 的子视图不再触发父视图失效。
• 在 ForEach 中使用稳定的 id；不要在非 Identifiable 集合上用 \.self。
• 把耗时操作从 body 移到计算属性或 init 中。

Step 4. 让 agent 每次修改后重跑，再用 Instruments（xctrace）检查视图更新峰值——下一节演示 skill 在这一步怎么帮上忙。

实战：用内置的 Python 工具链分析 .xctrace 文件

用户反馈 feed 滚动时有 6 秒的卡顿。skill 自带 Python 工具链，能把 trace 解析成结构化的 lanes。

Step 1. 把 trace 放到桌面上：~/Desktop/MyApp.trace。

Step 2. 让 agent 执行：

Analyse ~/Desktop/MyApp.trace and tell me what's wrong.

Step 3. agent 调用 scripts/analyze_trace.py，读取 Time Profiler、Hangs、Animation Hitches、SwiftUI updates 与 SwiftUI cause-graph 五个 lane，把 hangs/hitches 与主线程采样关联起来，输出 JSON 与 Markdown 摘要。

Step 4. 先看每次 hang/hitch 关联里的 main_running_coverage_pct 指标。README 的判读规则：< 25% 意味着主线程被阻塞（I/O、锁、同步 await），≥ 75% 意味着 CPU 密集。这两种情况的修法完全不同——前者要切到 actor 或 Task，后者要把手写的 layout 换成 LazyVGrid。

Step 5. 用 --window START_MS:END_MS 进一步圈定分析时段，或者用 --fanin-for 把特定视图的失效源一路追溯回去。

技巧

• 让 agent 养成"打开对应参考文件"的习惯，而不是要求模型凭训练数据记忆 SwiftUI 规则。
• 分析 Hangs trace 时先看 main_running_coverage_pct——一个数就能区分主线程阻塞与 CPU 密集。
• iOS 26+ 的 Liquid Glass 在 references/liquid-glass.md 中有明确的降级模式；上线 .glassEffect 之前先查那里。
• 在 Cursor 上，README 把 ~/.cursor/plugins/local 下的本地克隆描述为当前可用的安装方式，市场上架则是"once listed"之后的选项。

何时不用这个 Skill

如果你的最低目标是 iOS 17 之前的 SwiftUI，或者必须坚持 @StateObject/ObservableObject 模式，这个 skill 倾向于用 @Observable，会把 agent 领向你部署目标不适用的写法。如果你需要专门的并发指导（actors、async let、Swift 6 strict concurrency），AvdLee 另有一个 Swift-Concurrency-Agent-Skill。如果你想要的是 Apple 平台 skill 的目录而不是某一个深度专项，看 twostraws/Swift-Agent-Skills。

查看 排行榜 了解更多 skill。