SwiftUI Expert Skill
Expert guidance for any AI coding tool that supports the Agent Skills open format — SwiftUI state management, view composition, performance, and iOS 26+ Liquid Glass adoption.
This repository distills practical SwiftUI best practices into actionable, concise references for agents and code review workflows.
This repository is packaged as a portable Agent Plugin (spec 1.0.0): compatible clients discover the skill automatically from the root plugin.json manifest and the skills/ directory. Client-specific manifests for Claude Code, Cursor, Codex, and pi are included as well.
Who this is for
- Teams adopting modern SwiftUI APIs who want quick, correct defaults
- Developers reviewing or refactoring SwiftUI views and data flow
- Anyone shipping performant lists, scrolling, sheets, and navigation in SwiftUI
See also my other skills:
How to Use This Skill
Option A: Using skills.sh (recommended)
Install this skill with a single command:
npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill
For more information, visit the skills.sh platform page.
Then use the skill in your AI agent, for example:
Use the swiftui expert skill and review the current SwiftUI code for state-management and performance improvements
Option B: ChatGPT & Codex (OpenAI Plugins Directory)
This plugin is distributed through the universal OpenAI Plugins Directory shared by ChatGPT and Codex:
- In the ChatGPT desktop app, select Codex (or ChatGPT with Work enabled), or use the plugin browser in Codex CLI.
- Open Plugins and search for "SwiftUI Expert".
- Install the plugin. The skill becomes available in new chats and sessions.
Option C: Claude Code Plugin
Personal Usage
To install this Skill for your personal use in Claude Code:
- Add the marketplace:
/plugin marketplace add AvdLee/SwiftUI-Agent-Skill
- Install the Skill:
/plugin install swiftui-expert@swiftui-expert-skill
Project Configuration
To automatically provide this Skill to everyone working in a repository, configure the repository's .claude/settings.json:
{
"enabledPlugins": {
"swiftui-expert@swiftui-expert-skill": true
},
"extraKnownMarketplaces": {
"swiftui-expert-skill": {
"source": {
"source": "github",
"repo": "AvdLee/SwiftUI-Agent-Skill"
}
}
}
}
When team members open the project, Claude Code will prompt them to install the Skill.
Option D: Cursor Plugin
Load the plugin from a local clone by placing it in ~/.cursor/plugins/local, or install it from the Cursor Marketplace once listed. Cursor supports both the portable Agent Plugins manifest (plugin.json) and the Cursor Plugin manifest (.cursor-plugin/plugin.json) included in this repository.
See INSTALLATION.md for all other installation options: pi, Gemini CLI, Autohand Code, and manual installation.
How to verify:
Your agent should reference the workflow/checklists in skills/swiftui-expert-skill/SKILL.md and jump into the relevant reference file for your task.
What's Inside
This skill covers the full surface of SwiftUI development -- from state management and view composition to Swift Charts, macOS multi-window scenes, animations, and iOS 26+ Liquid Glass -- without bloating your agent's task context. Reference files load on demand, so your agent gets deep guidance only for the topic at hand.
- State management -- property wrapper selection,
@Observable, data flow patterns
- View composition -- extraction patterns, container views, identity stability
- Performance -- hot-path optimization, lazy loading,
@Observable granularity
- Lists & ForEach -- stable identity, Table, inline filtering pitfalls
- Navigation & sheets -- NavigationStack, NavigationSplitView, Inspector, enum-based sheets
- Swift Charts -- marks, axes, selection, styling, accessibility, Chart3D
- Animations -- implicit/explicit, transitions, phase/keyframe,
@Animatable macro
- macOS -- scenes, window styling, Table, HSplitView, AppKit interop
- Liquid Glass -- iOS 26+ glass effects, containers, fallback patterns
- Accessibility -- VoiceOver, Dynamic Type, grouping, traits
- Image optimization -- AsyncImage, downsampling, caching
- Latest APIs -- deprecated-to-modern migration guide (iOS 15+ through iOS 26+)
- Instruments trace recording & analysis -- bundled
xctrace toolchain for diagnosing hangs, hitches, and expensive SwiftUI view updates (see below)
Non-opinionated: focuses on correctness and performance, not architecture or code style.
Recording & Analysing Instruments Traces
Unlike the other reference files — which are text guidance — this part of the skill ships an executable Python toolchain that wraps xctrace. It lets the agent record a new .trace and analyse an existing one end-to-end: the parser reads the Time Profiler, Hangs, Animation Hitches, SwiftUI updates, and SwiftUI cause-graph lanes, correlates hangs/hitches with main-thread samples, and emits JSON + markdown so the agent can reason over structured data instead of the raw xctrace export firehose.
When it triggers:
- A
.trace path appears in the prompt (analysis).
- The user asks to record, profile, or capture a session (recording).
What the agent can then ask:
Analyse ~/Desktop/MyApp.trace and tell me what's wrong.
Focus analysis on what happens right after the 'feed loaded' log.
Which of my SwiftUI views is responsible for the hang around 6s?
Record a new trace: attach to MyApp on my iPhone — I'll tell you when I'm done.
Under the hood:
scripts/record_trace.py — wraps xctrace record. Supports attach / launch / all-processes, stop-file for agent-driven sessions, time-limits, JSON device & template discovery.scripts/analyze_trace.py — runs the five-lane analysis. Discovery modes --list-logs, --list-signposts, --fanin-for let the agent scope to a time window or trace a specific view back to its invalidation sources. --window START_MS:END_MS restricts every lane to a slice.scripts/instruments_parser/ — one module per lane (time_profiler, hangs, hitches, swiftui, causes), plus cross-lane correlate and a markdown summary renderer. Pure stdlib Python 3; only external dep is xctrace (ships with Xcode).
Key diagnostic: main_running_coverage_pct on each hang/hitch correlation. < 25 % → main thread was blocked (I/O, lock, sync await); ≥ 75 % → CPU-bound. This single metric separates two radically different fix paths.
Full guidance: skills/swiftui-expert-skill/references/trace-analysis.md and skills/swiftui-expert-skill/references/trace-recording.md.
Skill Structure
skills/swiftui-expert-skill/
SKILL.md
references/
accessibility-patterns.md - Accessibility traits, grouping, Dynamic Type, and VoiceOver
animation-advanced.md - Performance, interpolation, and complex animation chains
animation-basics.md - Core animation concepts, implicit/explicit animations, timing
animation-transitions.md - View transitions, matchedGeometryEffect, and state changes
charts-accessibility.md - Charts accessibility, fallback strategies, and WWDC sessions
charts.md - Swift Charts marks, axes, selection, styling, composition, and Chart3D
focus-patterns.md
image-optimization.md - AsyncImage usage, downsampling, caching
latest-apis.md
layout-best-practices.md - Layout patterns and GeometryReader alternatives
liquid-glass.md - iOS 26+ glass effects and fallback patterns
list-patterns.md - ForEach identity and list performance
localization.md
macos-scenes.md - Scene lifecycle, multi-window setups, and menu bar scenes on macOS
macos-views.md - macOS-specific SwiftUI views and platform differences from iOS
macos-window-styling.md - Window chrome, toolbar, and title bar styling in SwiftUI
performance-patterns.md - Hot-path optimizations and update control
previews.md
scroll-patterns.md - ScrollViewReader and programmatic scrolling
sheet-navigation-patterns.md - Sheets and type-safe navigation
soft-deprecation.md
state-management.md - Property wrapper selection and data flow
text-patterns.md
trace-analysis.md
trace-recording.md
view-structure.md - View extraction and composition patterns
Maintenance
The repository includes a maintenance skill for keeping API guidance current:
.agents/skills/update-swiftui-apis/
SKILL.md - Workflow for scanning Apple docs and updating latest-apis.md
references/
scan-manifest.md - Categorized API areas, doc paths, and search queries to scan
Use this skill after new iOS or Xcode releases to refresh the deprecated API reference. It requires the Sosumi MCP to be available. See AGENTS.md or CONTRIBUTING.md for details.
Note: only swiftui-expert-skill is intended to be published in the Cursor plugin. The maintenance skill remains a repository workflow utility.
Contributing
Contributions are welcome! This repository follows the Agent Skills open format, which has specific structural requirements.
Please read CONTRIBUTING.md for:
- How to contribute improvements to
SKILL.md and the reference files
- Format requirements and quality standards
- Pull request process
Acknowledgments
Several SwiftUI guidelines in this skill were inspired by or derived from the following works:
- Skills by Thomas Ricouard — a collection of SwiftUI-focused Codex skills covering UI patterns, performance auditing, and Liquid Glass.
- SwiftLee SwiftUI articles and Swift articles by Antoine van der Lee — practical SwiftUI best practices covering state management, accessibility, view composition, performance debugging, image optimization, and more.
- Swift Charts Examples by Jordi Bruin — a comprehensive collection of Swift Charts examples covering line, bar, area, range, heat map, and point charts with accessibility and customization patterns. Used with permission.
About the authors
Created by Antoine van der Lee and Omar Elsayed. With years of experience in Swift & SwiftUI, this skill distills practical knowledge into actionable guidance for AI assistants. Antoine published tens of articles on SwiftUI on his blog called SwiftLee.
Resources
License
This skill is open-source and available under the MIT License. See LICENSE for details.
一个打包好的专家技能，以开放的 Agent Skills 格式为 AI 编程工具提供深入的 SwiftUI 最佳实践指导——涵盖状态管理、视图组合、性能优化以及 iOS 26+ Liquid Glass 的适配。