SwiftUI 专家指南
为 SwiftUI 开发、审查和性能优化提供可执行的专家指导。
未见恶意、凭据窃取或隐蔽外传等红线风险；技能要求确认 Instruments 目标，并将录制输出限定到用户指定路径。但录制脚本、xctrace、文件写入和外部安装命令会产生系统外部效应，缺少统一的权限说明、敏感数据处理、数据流披露、回滚方案和逐次明确确认，因此扣分。
操作规则、任务流程和主题路由整体一致，包含失败状态、可用性回退和 trace 停止机制；但静态材料未证明引用的 references 与 scripts 一定存在或可运行，也没有提交测试、CI 覆盖或异常输入的可诊断反馈。依据静态上限和不确定性扣分。
名称、受众和 SwiftUI/iOS/macOS、代码审查、重构、实现及 Instruments 场景较清晰，trace 触发词和部分非适用情形已有说明；但未明确完整的非适用边界、中文输出支持、不同工具环境兼容性及中国大陆网络可达性，部分安装和外部文档依赖海外服务，因此扣分。
SKILL.md 采用操作规则、工作流、路由、检查清单和参考资料的分层结构；README 提供多种安装方式、MIT 标识和版本相关说明。缺少明确维护责任人、更新路径、变更日志，以及对脚本和引用文件依赖的完整安装/故障排查说明，因此扣分。
内容覆盖状态管理、性能、可访问性、动画、图表和 trace 分析，示例通常可直接转化为代码审查建议，核心任务价值明确；但未提供可验证的代表性产出、执行结果或与替代方案的比较，且部分建议依赖未展示的文件和脚本，静态评估按上限给分。
材料包含部分 Apple WWDC 链接、API 版本标注和具体代码示例，具备有限审计线索；但没有提交测试套件、真实 CI 执行证据或多来源交叉验证，且大量断言未逐项标注来源，静态可验证性有限。
- 引用的 references/latest-apis.md、trace 脚本及其他资源未在所给材料中完整呈现，安装或执行前应确认其存在、版本和权限。
- Instruments trace 可能包含应用性能和用户行为信息；使用前应确认目标、输出位置及数据敏感性，并避免未经同意上传。
- 部分 API、WWDC 资料和安装入口依赖 Apple、GitHub 或其他海外服务；应验证中国大陆网络可达性，并准备离线或本地文档替代方案。
- 建议对代码示例进行目标 SDK、部署版本和编译验证，尤其是 iOS 26+ API、图表 API 和图像处理示例。
它能做什么 & 适用场景
这是一个面向 iOS 和 macOS SwiftUI 开发的 Agent Skill，覆盖状态管理、视图组合、列表身份、环境值、动画、本地化和性能优化等主题。它要求代理按任务读取对应的参考文件，并优先检查最新 API 和弃用迁移建议。技能还包含基于 xctrace 的 Instruments 轨迹录制与分析流程，用于定位卡顿、挂起、CPU 热点和过度视图更新。它适合希望让 AI 编码工具按照现代 SwiftUI 实践审查或改进代码的团队。
代理会先读取 references/latest-apis.md，再根据任务读取状态管理、视图结构、性能、列表、动画、可访问性、macOS、Liquid Glass 或其他主题参考文件。对于 SwiftUI 代码，它检查属性包装器、ForEach 稳定身份、可用性判断、动画写法、预览数据和其他正确性规则，并提出或执行符合任务要求的改进。用户提供 .trace 文件时，技能可运行 scripts/analyze_trace.py 分析 Time Profiler、Hangs、Animation Hitches、SwiftUI 更新和原因图；用户要求录制轨迹时，可运行 scripts/record_trace.py 调用 xctrace，并支持设备列表、附加进程、停止文件和输出 .trace 文件。
- 正在开发 iOS 或 macOS SwiftUI 功能，希望 AI 先设计清晰的状态所有权和数据流。
- 需要审查或重构现有 SwiftUI 代码，重点检查弃用 API、属性包装器和视图失效范围。
- 构建包含列表、ForEach、滚动、导航、sheet 或动画的界面，并希望减少身份和更新方面的问题。
- 准备采用 iOS 26+ API 或 Liquid Glass，同时需要保留旧系统的 #available 回退路径。
- 已有 Instruments .trace 文件，想根据主线程覆盖率、热点符号和 SwiftUI 原因图制定优化优先级。
- 需要改善 SwiftUI 界面的本地化、VoiceOver、Dynamic Type 或图表可访问性。
优缺点一览
- 覆盖从状态管理、视图结构到性能、可访问性、图表和 macOS 场景的较完整 SwiftUI 主题。
- 提供可按任务加载的参考文件和明确的正确性检查清单。
- 包含 Instruments .trace 的录制、范围筛选、原因图分析和源代码定位流程。
- 不强制采用 MVVM、VIPER 等特定架构，适合已有不同架构的项目。
- MIT 许可，遵循 Agent Skills open format。
- 深度建议依赖仓库中的 references 文件；只使用 SKILL.md 而不加载参考文件会降低效果。
- 轨迹录制和分析流程依赖 macOS、Xcode 提供的 xctrace，不能在没有该工具链的环境中完整运行。
- 对 iOS Simulator，SwiftUI Instruments lane 会为空，必须改用 Time Profiler 模板。
- 来源材料没有提供独立测试套件或跨工具实测结果。
如何安装
从仓库安装指定技能：
npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill
也可以克隆仓库后，将 swiftui-expert-skill/ 文件夹按目标工具的官方技能目录要求安装或建立符号链接。对于 Codex/OpenAI 兼容工具，README 给出的方式是：
cp -R swiftui-expert-skill/ "$CODEX_HOME/skills/swiftui-expert-skill"
该仓库也提供 Claude Code、Cursor 和 pi 的安装路径；具体目录由相应工具的官方文档决定。
如何使用
安装后，在 AI 编码工具中明确要求使用该技能。例如：
Use the swiftui expert skill and review the current SwiftUI code for state-management and performance improvements
若分析轨迹，可提供 .trace 路径；若录制轨迹，应说明是附加到运行中的应用、启动应用还是记录所有进程，并在需要时提供设备名称或 UDID。技能会根据真实设备或 iOS Simulator 选择 SwiftUI 或 Time Profiler 模板。