update-swiftui-apis
avdlee/swiftui-agent-skill · skills.sh
Open source Repository Open in the app JSON README (API)
About
Skill publicada por avdlee/swiftui-agent-skill no skills.sh. Instale com: npx skills add avdlee/swiftui-agent-skill@update-swiftui-apis
Details
- Kind
- Agent skills
- Topic
- No topic detected
- Publisher
- avdlee
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 3,523
- Forks
- 156
- Open pull requests
- 2
- Last push
- 2026-08-12T13:34:21Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 15:22:09
- Updated
- 2026-09-08 15:04:42
- Origin id
avdlee/swiftui-agent-skill/update-swiftui-apis
README
# SwiftUI Expert Skill
[](https://github.com/AvdLee/SwiftUI-Agent-Skill/blob/main/LICENSE)
[](https://skills.sh/avdlee/swiftui-agent-skill/swiftui-expert-skill)
[](https://github.com/AvdLee/SwiftUI-Agent-Skill/releases)
[](https://github.com/AvdLee/SwiftUI-Agent-Skill/stargazers)
Expert guidance for any AI coding tool that supports the [Agent Skills open format](https://agentskills.io/home) — 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](https://agent-plugins.org) (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:
- [Swift Concurrency Expert](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill)
- [Core Data Expert](https://github.com/AvdLee/Core-Data-Agent-Skill)
- [Swift Testing Expert](https://github.com/AvdLee/Swift-Testing-Agent-Skill)
- [Xcode Build Optimization Agent Skill](https://github.com/AvdLee/Xcode-Build-Optimization-Agent-Skill)
- [Xcode Simulator AI Control Agent Skill](https://www.rocketsim.app/docs/features/agentic-development/agent-skill/)
## How to Use This Skill
### Option A: Using skills.sh (recommended)
Install this skill with a single command:
```bash
npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill
```
For more information, [visit the skills.sh platform page](https://skills.sh/avdlee/swiftui-agent-skill/swiftui-expert-skill).
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:
1. In the ChatGPT desktop app, select **Codex** (or ChatGPT with **Work** enabled), or use the plugin browser in Codex CLI.
2. Open **Plugins** and search for "SwiftUI Expert".
3. 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:
1. Add the marketplace:
```bash
/plugin marketplace add AvdLee/SwiftUI-Agent-Skill
```
2. Install the Skill:
```bash
/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`:
```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.
### Using another tool?
See [INSTALLATION.md](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:**
```text
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`](skills/swiftui-expert-skill/references/trace-analysis.md) and [`skills/swiftui-expert-skill/references/trace-recording.md`](skills/swiftui-expert-skill/references/trace-recording.md).
## Skill Structure
<!-- BEGIN REFERENCE STRUCTURE -->
```text
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
```
<!-- END REFERENCE STRUCTURE -->
## Maintenance
The repository includes a maintenance skill for keeping API guidance current:
```text
.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](https://github.com/NSHipster/sosumi.ai) 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](https://agentskills.io/home), which has specific structural requirements.
Please read [CONTRIBUTING.md](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](https://github.com/Dimillian/Skills) by [Thomas Ricouard](https://github.com/Dimillian) — a collection of SwiftUI-focused Codex skills covering UI patterns, performance auditing, and Liquid Glass.
- [SwiftLee SwiftUI articles](https://www.avanderlee.com/category/swiftui/) and [Swift articles](https://www.avanderlee.com/category/swift/) by [Antoine van der Lee](https://www.avanderlee.com) — practical SwiftUI best practices covering state management, accessibility, view composition, performance debugging, image optimization, and more.
- [Swift Charts Examples](https://github.com/jordibruin/Swift-Charts-Examples) by [Jordi Bruin](https://x.com/jordibruin) — 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](https://www.avanderlee.com) and [Omar Elsayed](https://www.swiftdifferently.com). 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](https://www.avanderlee.com/category/swiftui/) on his blog called SwiftLee.
## Resources
- [Story behind this skill](https://www.swiftdifferently.com/blog/swiftui/How%20I%20stopped-resisting-ai-and-atarted-teaching-it)
## License
This skill is open-source and available under the MIT License. See [LICENSE](LICENSE) for details.