SwiftUI-Agent-Skill

让 AI 写出更专业的 SwiftUI 代码

图1：项目作者 Paul Hudson（@twostraws），Hacking with Swift 创始人，GitHub 4000+ 星项目作者

---

背景：AI 写 SwiftUI，问题一堆

当你用 Claude Code、Codex 或 Gemini 写 SwiftUI 时，是否遇到过这些问题：代码用到了已经被废弃的 API、按钮对 VoiceOver 视障用户完全隐形、滚动时帧率骤降、导航写法混用了新旧两种模式导致 Bug 频出？

这并非用户的错。LLM 的训练数据有截止日期，而 Apple 每年 WWDC 都会淘汰一批旧 API、引入新写法。据统计，AI 编程工具生成的 SwiftUI 代码中，以下问题最为常见：

• 废弃 API 滥用：用 foregroundColor() 而非 foregroundStyle()、用 cornerRadius() 而非 clipShape(.rect())、用 onChange() 单参数版本而非双参数版本。
• 无障碍问题：图标按钮没有文字标签，VoiceOver 用户完全不知道按钮是干什么的。
• 性能陷阱：GeometryReader 滥用、AnyView 滥用、view body 中使用 if/else 分支而非三元表达式导致结构身份丢失。
• 数据流混乱：还在用 ObservableObject + @Published，而 Swift 5.9+ 的 @Observable 宏才是现代写法。

Paul Hudson 在 Reddit 发帖后，该项目两天内获得 1000+ GitHub Stars，目前已有 4000+，充分说明了社区对这类工具的强烈需求。

---

SwiftUI Pro 是什么：给 AI 看的 SwiftUI 最佳实践百科

SwiftUI Agent Skill（又称 SwiftUI Pro）是一个 Agent Skill 格式的插件，由 Paul Hudson 编写，托管于 GitHub（MIT 许可证）。它以 Markdown 文件的形式，向 AI 编程助手传授 SwiftUI 开发中那些"教科书不会写、文档没写清楚、LLM 训练数据容易过时"的细节知识。

用生活化的比喻来说：它就像一位资深 iOS 开发者坐在 AI 旁边，在 AI 每写一段 SwiftUI 代码时，就翻到对应的"检查清单"提醒一句"这里用 foregroundStyle 更好"、"这个按钮 VoiceOver 看不见"。

核心内容：9 大模块，覆盖完整开发流程

项目包含 9 个参考文件，涵盖：

模块	核心检查项
api.md	废弃 API 更新（foregroundStyle、Tab API、GeometryReader 替代方案）
views.md	视图结构与动画最佳实践，避免在 body 中写大段逻辑
data.md	@Observable vs ObservableObject 选择，数据流架构
navigation.md	NavigationStack vs NavigationView，新旧导航 API 混用问题
design.md	Apple HIG 合规、固定尺寸 vs 弹性布局、ContentUnavailableView
accessibility.md	Dynamic Type、VoiceOver、Reduce Motion、图片 alt 文本
performance.md	避免 AnyView、避免条件分支 view、三元替代 if/else
swift.md	现代 Swift API（FormatStyle、Swift Concurrency、Foundation 改进）
hygiene.md	代码整洁、安全存储敏感信息、SwiftLint 配置

SKILL.md 本身定义了 AI 使用这些参考文件的流程：审查代码时，先检查废弃 API，再查视图写法，然后数据流、导航、可访问性、性能、Swift 惯用法，最后整体代码整洁度。

---

安装与使用：三条命令搞定

支持 Claude Code、Codex、Gemini、Cursor 等主流 AI 编程工具。

方式一：npx 安装（通用）

npx skills add https://github.com/twostraws/swiftui-agent-skill --skill swiftui-pro

方式二：Claude Code 插件市场

/plugin marketplace add twostraws/SwiftUI-Agent-Skill
/plugin install swiftui-pro@swiftui-agent-skill

安装后，在对话中触发即可：

• Claude Code：/swiftui-pro
• Codex：$swiftui-pro
• 支持部分审查：/swiftui-pro Check for deprecated API

Paul Hudson 还在 Hacking with Swift 发布了配套 YouTube 视频，指导如何在 Xcode 中安装和使用 Agent Skills，Xcode 16+ 已原生支持这一机制。

---

技术架构：无 AI 的"AI 辅助工具"

这个项目本身不包含任何机器学习模型。它的"智能"来自于 Paul Hudson 数十年 SwiftUI 开发经验的结构化沉淀。

技术特点：

• 格式：纯 Markdown，采用 Agent Skills 标准格式
• 分发：通过 npx skills add 或各 AI 工具的插件市场分发，无服务端组件
• 本地执行：插件加载后完全在本地 AI 编程工具内运行，无网络请求，无数据上传
• Token 优化：项目 README 明确要求贡献者"保持 Markdown 简洁"，避免无意义的重复内容浪费 token

代码结构：

SwiftUI-Agent-Skill/
├── swiftui-pro/
│   ├── SKILL.md              # 主入口，定义审查流程和输出格式
│   ├── .claude-plugin        # Claude Code 插件配置
│   ├── agents/openai.yaml    # OpenAI Agent 配置
│   ├── references/           # 9 个专项检查参考文件
│   │   ├── api.md / accessibility.md / performance.md ...
│   │   └── views.md / data.md / navigation.md ...
│   └── skills/swiftui-pro/  # Skill 元数据
└── assets/logo.svg          # 项目 Logo

---

局限性：Token 成本与语言限制

项目 README 坦诚列出了使用限制：

• Token 消耗：SKILL.md 包含所有核心指令，每次调用都会消耗 token。用户需要为 token 预算负责，不必要的大文件会浪费成本。
• LLM 知识截止日期问题：Skill 能纠正 API 用法，但无法凭空告诉 AI"iOS 27 有什么新 API"——这部分仍然依赖 LLM 的知识。
• 仅支持 Apple 平台：Skill 针对 SwiftUI 设计，不适用于 UIKit、跨平台 Flutter 或 React Native 项目。
• 无法运行代码验证：Skill 是静态分析工具，不会实际编译运行 Swift 代码来验证正确性。

---

行业意义：AI 编程的"垂直领域知识库"范式

SwiftUI Agent Skill 代表了一种新兴趋势：不是让 LLM 自己记住所有知识，而是构建外部知识检索增强（RAG）来补充 LLM 的弱项。

Paul Hudson 的 Swift Agent Skills 系列（SwiftUI Pro、SwiftData Pro、Swift Concurrency Pro、Swift Testing Pro）正在形成一套完整的 Apple 平台 AI 开发知识体系。这一模式的可复制性很强——任何有深度积累的垂直领域（嵌入式、数据库、游戏引擎等）都可以参照这个范式建立自己的 Agent Skill。

对于国内 iOS 开发团队而言，这意味着：

• 新人使用 AI 编程工具时，可以通过这套 Skill 快速获得"有经验开发者"的代码审查反馈
• 团队可以 fork 项目，定制符合内部规范的 SwiftUI 检查规则
• Token 成本可控的前提下，可显著提升 AI 生成代码的可用性

---

项目信息

• 作者：Paul Hudson @twostraws
• 主页：Hacking with Swift
• 许可证：MIT
• 相关项目：Swift Agent Skills 总库、SwiftData Agent Skill、Swift Concurrency Agent Skill

图2：SwiftUI Agent Skill 官方 Logo