Back to search
swiftui-expert-skill
MarketplaceWorks with Claude CodeGitHubIncomplete
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/avdlee-swiftui-agent-skill)HTML
<a href="/listings/avdlee-swiftui-agent-skill"><img src="/api/listings/avdlee-swiftui-agent-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 47 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/marketplace/marketplace.schema.json",
- "name": "swiftui-expert-skill",
- "version": "5.3.0",
- "owner": {
- "name": "Antoine van der Lee",
- "email": "contact@avanderlee.com"
- },
- "metadata": {
- "description": "SwiftUI best practices for state management, view composition, performance, modern SDK APIs, and Liquid Glass."
- },
- "plugins": [
- {
- "name": "swiftui-expert",
- "description": "Expert SwiftUI guidance for state management, view composition, performance, modern SDK APIs, and Liquid Glass patterns.",
- "repository": "https://github.com/AvdLee/SwiftUI-Agent-Skill",
- "version": "5.3.0",
- "author": {
- "name": "Antoine van der Lee",
- "email": "contact@avanderlee.com"
- },
- "license": "MIT",
- "category": "development",
- "keywords": [
- "swift",
- "swiftui",
- "ios",
- "apple",
- "state-management",
- "performance",
- "sdk-27",
- "liquid-glass"
- ],
- "tags": [
- "swift",
- "swiftui",
- "ios",
- "apple",
- "state-management",
- "performance",
- "sdk-27",
- "liquid-glass"
- ],
- "source": "./"
- }
- ]
- }
README.md · README · 238 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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, SDK 27 changes, and 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@latest 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).
- Installed before the Agent Plugins migration? Run `npx skills@latest update` using skills CLI 1.5.24 or newer. It migrates the saved skill path without treating the skill as deleted.
- 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, SDK 27 changes, and 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
- - **Environment** -- `@Entry`, stable defaults, and invalidation-aware propagation
- - **View composition** -- extraction patterns, container views, identity stability
- - **Modifiers** -- conditional identity, no-effect values, and `AnyShapeStyle`
- - **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
- - **SDK 27** -- `@State` and `@ContentBuilder` migrations, reordering, AsyncImage caching, swipe actions, dialogs, and toolbars
- - **Accessibility** -- VoiceOver, Dynamic Type, grouping, traits
- - **Image optimization** -- AsyncImage, downsampling, caching
- - **Latest APIs** -- deprecated-to-modern migration guide (iOS 15+ through iOS 27+)
- - **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).
- Looking for a visual way to explore Instruments traces? [RocketTrace](https://rockettrace.app/?utm_source=github&utm_medium=referral&utm_campaign=swiftui-agent-skill&utm_content=readme-trace-section) is a companion app created by this repository's author for inspecting and understanding trace data.
- ## 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
- document-apps.md - Document protocol, reading, writing, autosave, and FileDocument migration
- environment-patterns.md - @Entry, stable defaults, custom actions, and environment invalidation
- focus-patterns.md
- image-optimization.md - AsyncImage usage, downsampling, caching
- iphone-duo.md - Choosing a large-display technique by screen structure, Duo displays, fold regions, displacement, hinge effects, and scene accessories
- 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
- modifier-patterns.md - Conditional modifiers, structural identity, and AnyShapeStyle
- 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
- styled-text-editing.md - AttributedString editing, selection, formatting, and Markdown
- text-patterns.md
- toolbar-patterns.md - Customization, overflow, visibility, transitions, and minimization
- trace-analysis.md
- trace-recording.md
- view-structure.md - View extraction and composition patterns
- webkit-integration.md - WebView, WebPage, navigation, JavaScript, and exports
- ```
- <!-- 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-started-teaching-it)
- ## License
- This skill is open-source and available under the MIT License. See [LICENSE](LICENSE) for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.