SwiftUI Agent Skills 指南

AI 写 SwiftUI 最常见的问题，不是语法完全错误，而是代码“看起来像对的”：状态所有权不清、导航模型过时、并发边界含糊，或者混入一个根本不存在的 API。Agent Skills 的价值，是把通用模型变成带有 Apple 平台工程约束的协作者。

Agent Skill 到底是什么？

Skill 通常是一个包含 SKILL.md 的目录。它告诉 Codex、Claude Code、Cursor 等编程代理：什么时候启用这项能力、应该先阅读哪些参考资料、生成代码时遵守哪些规则，以及最终输出应该长什么样。它不是 Xcode 插件，也不是一个新的 Swift package；它更像给 AI 的“团队工程手册 + 专项知识包”。

与把所有规则塞进一份超长提示词相比，Skill 可以按任务触发。做 SwiftUI 动画时加载动画知识，处理 StoreKit 时加载购买与交易验证规则，调试滚动卡顿时再加载性能与 Instruments 指南。这种按需上下文，通常更准确，也更省 token。

两套方案，一张表看懂

路线一：把 Xcode 文档变成 AI 的事实来源

这套方案最有价值的设计，是明确规定“所有事实与 API 都必须以本地 /docs 为准”。写代码前先选文档，审查代码时标出使用了哪些文档；如果资料里没有对应类型或 API，就应该承认不确定，而不是补全一个听起来合理的名字。

当前提取范围不仅是 SwiftUI 布局，还包含 App Intents、AlarmKit、StoreKit、WebKit、SwiftData 继承、Swift Concurrency、Liquid Glass、visionOS Widget，以及 InlineArray、Span 等底层性能能力。

需要留意的限制

• 需要 macOS 与 Xcode 26 或更高版本；文档目录没有完成提取时，Skill 按约定不应继续给出 SwiftUI 指导。
• 它是一个宽入口。复杂项目仍然需要你在任务里明确目标，例如“按 Apple 文档审查状态所有权与导航”。
• 本地 Xcode 版本决定了参考资料版本，团队应统一工具链，避免同一任务得到不同可用性结论。

路线二：84 个可组合的 iOS 专项 Skills

这套仓库的优势是路由精度。你不需要每次都把完整 Apple 开发知识放进上下文：一个使用 SwiftData、StoreKit 2、App Intents 与 WidgetKit 的订阅应用，可以只安装这几项，再搭配 SwiftUI patterns、Swift Concurrency、测试与无障碍 Skill。

下面是截至本文更新时的完整 84 项分类。展开每组可以快速核对是否覆盖你的项目栈。

应该怎么选？从任务而不是数量出发

场景 A：刚开始用 AI 写 SwiftUI

先装 swiftui-skills 作为 Apple 文档约束，再从 84 项集合里加入 swiftui-patterns、swiftui-navigation、swift-concurrency、swift-testing 与 ios-accessibility。这五项覆盖了大多数新项目最容易出错的地方。

场景 B：已有产品，正在开发具体功能

按照技术栈选，不要按照“看起来以后可能会用”来选。订阅应用加入 storekit；有系统入口加入 app-intents 与 widgetkit；重数据的应用加入 swiftdata 或 core-data；端侧 AI 产品加入 apple-on-device-ai。

场景 C：做代码审查与稳定性治理

优先组合 swiftui-performance、debugging-instruments、metrickit、swift-security、ios-accessibility 和 app-store-review。这组更接近上线前的工程守门员，而不是代码生成器。

安装：通用 Agent 与 Codex

安装 Apple 本地文档型 Skill

# 直接安装并从 Xcode 提取文档
curl -fsSL https://swiftui-skills.ameyalambat.com/install | bash

# 或通过 skills CLI
npx skills add ameyalambat128/swiftui-skills

通过管道执行远程脚本前，建议先打开仓库里的安装脚本做一次审查。安装完成后需要运行对应目录中的 setup.sh，并重新启动 Agent 会话，让新 Skill 被发现。

交互式挑选 84 项集合

# 打开交互界面，选择 Skill 与目标 Agent
npx skills add dpearson2699/swift-ios-skills

# 只安装指定能力
npx skills add dpearson2699/swift-ios-skills \
  --skill swiftui-patterns \
  --skill swift-concurrency \
  --skill swift-testing

# 检查与更新
npx skills check
npx skills update

在 Codex 中安装单项 Skill

$skill-installer install \
  https://github.com/dpearson2699/swift-ios-skills/tree/main/skills/swiftui-patterns

把最后的目录名替换成目录表中的任意 Skill。项目专属规则适合安装在项目作用域；跨项目通用的 SwiftUI 与工程规范，适合放在个人共享作用域。

一套更稳的组合工作流

1. 先声明目标与部署下限。告诉 Agent 是新功能、重构还是审查，并明确 iOS 最低版本，防止新 API 被无条件使用。
2. 让事实层先选文档。要求 swiftui-skills 列出本次使用的 Apple 文档与 availability 约束。
3. 只加载任务对应的专项 Skill。例如导航问题用 swiftui-navigation，购买问题用 storekit，不要把整个目录都塞进一次任务。
4. 要求完整验证。让 Agent 构建目标、运行测试，并在 UI 变更时检查 Dynamic Type、VoiceOver 与深色模式。
5. 把结论沉淀进项目规则。反复出现的架构选择应该进入项目自己的 Skill 或 AGENTS.md，而不是每次重新讨论。

一个可复用的任务开场可以这样写：

请使用本地 Apple 文档作为 API 事实来源，
并使用 swiftui-patterns、swift-concurrency 和 swift-testing。
目标：为 iOS 26 应用实现可测试的异步加载页面。
先列出选用文档与状态所有权，再修改代码、构建并运行测试。
不要引入项目当前没有使用的新架构。

版本与许可证：安装前最后看两眼

Apple 平台 API 更新很快。本文核对的上游快照分别是 2026 年 7 月 6 日的 swiftui-skills 提交与 2026 年 7 月 4 日的 swift-ios-skills 提交；仓库内容、支持版本与 Skill 数量之后仍可能变化。对 beta 框架，务必用当前 Xcode SDK 再验证一次。

许可证也不同：swiftui-skills 使用 MIT；swift-ios-skills 使用 PolyForm Perimeter 1.0.0，允许用于开发应用和闭源商业工作流，但限制把这些内容重新包装成竞争产品。团队分发、修改或做商业集成前，应阅读上游 LICENSE，而不是只依赖本文摘要。

常见问题