保姆级实操：10 分钟给 Claude Code 装上 SwiftUI 技能包，AI 写的界面立刻不一样

用 Claude Code、Codex 这类 AI 编程助手写 SwiftUI，很多人都有过类似体验：代码"看起来能跑"，编译也过了，但一细看全是坑——还在用早已弃用的 foregroundColor()、NavigationView，图标按钮对 VoiceOver 完全隐身，列表一长就莫名卡顿。问题在于，这些坑大模型自己很难发现：它训练数据里的旧写法太多，而 SwiftUI 的演进又太快。

SwiftUI-Agent-Skill 要解决的正是这件事。它把资深 iOS 开发者数千小时的实战经验，浓缩成一份 AI 可以直接执行的"纠偏清单"，装进 Claude Code 后，AI 写代码时会先按这套规则自查，再产出带行号、带 before/after 修复建议、按优先级排序的结构化报告。本文从环境检查、两种安装路径到真实项目验证，全程实操带你 10 分钟上手。

安装前准备：先确认你的环境就绪

在动手之前，先把工具链检查一遍，避免装到一半卡住。

第一步，确认 Node.js 是否可用。 推荐安装方式依赖 npx，它随 Node.js 一起分发。在终端执行：

npx --version

如果提示 npx: command not found，说明机器上没有 Node。macOS 用户先通过 Homebrew 安装：

brew install node

如果连 Homebrew 都没有，需要先去官网完成安装——这是唯一需要提前准备的系统级依赖。

第二步，确认你的 AI 工具支持 Agent Skills 开放格式。 该技能基于 Anthropic 最早提出、随后开放的 Agent Skills 标准，天然兼容 Claude Code、Codex、Gemini、Cursor 等主流工具。仓库 README.md 中明确说明，它基于作者原有的 AGENTS.md 知识沉淀而来，采用 agentskills.io 格式，因此"几分钟就能把多年经验带进你选的编码智能体"。

第三步，明确安装范围。 npx 安装过程中会让你选择：技能只装进当前项目，还是全局对所有项目生效。个人练手建议先装单项目，验证效果后再放开。

一键安装：npx 命令与 Claude Code 插件市场

路径一：npx 一键安装（推荐）

在终端执行：

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

安装器会自动拉取仓库、解析技能元信息，并把 swiftui-pro 写入你的 AI 工具技能目录。安装时按提示选择使用范围即可。

路径二：Claude Code 插件市场

Claude Code 用户有更原生的一条路——先添加技能市场，再直接安装插件：

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

插件市场方式的好处是后续升级、管理都走 Claude Code 自身的插件体系，适合长期使用。

路径三：克隆仓库手动配置

如果你用的是 Cursor、Gemini 等工具，或者想先看看技能包内部长什么样，直接克隆整个仓库，把 swiftui-pro/ 目录放进你所用工具的技能目录即可：

git clone https://github.com/twostraws/swiftui-agent-skill

克隆下来的仓库结构一目了然：swiftui-pro/SKILL.md 是技能入口，定义完整审查流程与输出格式；swiftui-pro/references/ 是 9 份规则文档；swiftui-pro/agents/openai.yaml 则为 Codex 等工具提供界面配置（品牌色、图标、默认提示词）。有意思的是，仓库里同时保留了两套技能目录：Claude 原生 skills 目录下的版本使用 ${CLAUDE_SKILL_DIR} 变量引用规则文件（见 swiftui-pro/skills/swiftui-pro/SKILL.md），根目录版本则使用相对路径——这也侧面说明它对多种工具目录结构都做了适配。

无论走哪条路，装好后技能的名字都叫 SwiftUI Pro，版本 1.1，作者是 Hacking with Swift 的 Paul Hudson。

装完怎么用：三种触发方式与局部审查

技能就绪后，触发方式非常灵活。在 Claude Code 中用斜杠命令：

/swiftui-pro

在 Codex 中用美元命令：

$swiftui-pro

也可以直接用自然语言唤起：

Use the SwiftUI Pro skill to look for performance problems in this project.

更实用的是局部审查——只查你关心的维度，省时省 token。比如：

/swiftui-pro Check for deprecated API
$swiftui-pro Focus on accessibility

触发后，AI 会按照 swiftui-pro/SKILL.md 定义的流程依次加载 9 份规则文件，对项目做一次系统性"体检"。

9 大审查维度：AI 的专业级"体检表"

打开 swiftui-pro/SKILL.md，可以看到审查流程明确分 9 步，每一份参考文档对应一类高频错误：

规则文档	防住的坑
api.md	弃用 API 照用不误，不采用现代替代写法
views.md	视图拆分不当、动画链式调用错误
data.md	@State/@Observable 误用、脆弱的 Binding(get:set:)
navigation.md	旧式 NavigationView、navigationDestination 重复注册
design.md	固定尺寸、UIScreen.main.bounds 等违反 HIG 的写法
accessibility.md	VoiceOver、Dynamic Type、Reduce Motion 缺失
performance.md	body 里做重计算、滥用 AnyView、闭包存储
swift.md	Swift 语言层面的现代写法与并发问题
hygiene.md	敏感数据乱存 @AppStorage、缺测试等工程卫生问题

以 api.md 为例，规则细到令人发指：一律用 foregroundStyle() 替代 foregroundColor()，用 clipShape(.rect(cornerRadius:)) 替代 cornerRadius()，用 Tab API 替代 tabItem()，能用 containerRelativeFrame()/visualEffect()/Layout 协议就别用 GeometryReader，iOS 26 下原生 WebView 取代手包的 WKWebView……这些恰恰是模型最容易写错、而普通开发者又不一定盯得住的细节。

规则文档还会纠正数据流层面的架构问题。data.md 要求 @Observable 类必须标注 @MainActor、所有共享数据用 @Observable + @State/@Bindable，并强烈反对在 view body 里用 Binding(get:set:) 手搓绑定——这类写法脆弱且难维护。性能维度同样硬核：performance.md 直接要求避免 AnyView、用三元表达式替代 if/else 视图分支以保留结构身份、异步工作优先用 task()（视图消失时自动取消）而非 onAppear()。

值得强调的是，SKILL.md 开篇就声明"只报告真实问题，不吹毛求疵、不凭空编造"——它不是让 AI 无限挑刺，而是精准纠偏。

跑一个真实项目验证：审查报告长什么样

技能装好、触发之后，产出是高度结构化的。以 SKILL.md 中内置的示例输出为例，AI 会按文件分组，每个问题依次给出：文件名与具体行号、违反的规则、修改前后对照。这是报告中"API 现代化"维度的一个典型片段：

// Before
Text("Hello").foregroundColor(.red)

// After
Text("Hello").foregroundStyle(.red)

这是无障碍维度的经典案例——图标按钮对 VoiceOver 用户完全不可见，必须补上文字标签：

// Before
Button(action: addUser) {
    Image(systemName: "plus")
}

// After
Button("Add User", systemImage: "plus", action: addUser)

这是数据流维度最常见的脆弱写法，手搓绑定应改用 @State 绑定 + onChange()：

// Before
TextField("Username", text: Binding(
    get: { model.username },
    set: { model.username = $0; model.save() }
))

// After
TextField("Username", text: $model.username)
    .onChange(of: model.username) {
        model.save()
    }

最后，报告会附上一份按优先级排序的总结，明确告诉你先改哪几处收益最大：

1. Accessibility (high)： 第 24 行的新增按钮对 VoiceOver 不可见。
2. Deprecated API (medium)： 第 12 行的 foregroundColor() 应改为 foregroundStyle()。
3. Data flow (medium)： 第 31 行的手工绑定脆弱且难以维护。

你可以把这段示例当成验收标准：装好技能后，随便丢一个之前 AI 生成的 SwiftUI 文件进去跑一轮，如果报告能定位到具体行、给出可执行的 before/after，就说明整条链路已经打通，你手里的 AI 助手已经从"能写"进化到了"写得好"。

写在最后

从环境检查到完成安装，通常不超过 10 分钟。你得到的不是一个提示词模板，而是一套可版本化、可共享、可组合的技能资产——它基于 MIT 协议开源，同一作者还维护着 SwiftData Pro、Swift Concurrency Pro、Swift Testing Pro 等姊妹技能，可以按需搭配，逐步搭建完整的 Swift AI 开发工作流。下次再让 AI 写 SwiftUI 之前，不妨先让它按这套规则自查一遍，界面质量的变化会立竿见影。