Skip to content
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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/avdlee-swiftui-agent-skill/badge.svg)](/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)

  1. {
  2. "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/marketplace/marketplace.schema.json",
  3. "name": "swiftui-expert-skill",
  4. "version": "5.3.0",
  5. "owner": {
  6. "name": "Antoine van der Lee",
  7. "email": "contact@avanderlee.com"
  8. },
  9. "metadata": {
  10. "description": "SwiftUI best practices for state management, view composition, performance, modern SDK APIs, and Liquid Glass."
  11. },
  12. "plugins": [
  13. {
  14. "name": "swiftui-expert",
  15. "description": "Expert SwiftUI guidance for state management, view composition, performance, modern SDK APIs, and Liquid Glass patterns.",
  16. "repository": "https://github.com/AvdLee/SwiftUI-Agent-Skill",
  17. "version": "5.3.0",
  18. "author": {
  19. "name": "Antoine van der Lee",
  20. "email": "contact@avanderlee.com"
  21. },
  22. "license": "MIT",
  23. "category": "development",
  24. "keywords": [
  25. "swift",
  26. "swiftui",
  27. "ios",
  28. "apple",
  29. "state-management",
  30. "performance",
  31. "sdk-27",
  32. "liquid-glass"
  33. ],
  34. "tags": [
  35. "swift",
  36. "swiftui",
  37. "ios",
  38. "apple",
  39. "state-management",
  40. "performance",
  41. "sdk-27",
  42. "liquid-glass"
  43. ],
  44. "source": "./"
  45. }
  46. ]
  47. }
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)

  1. # SwiftUI Expert Skill
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/AvdLee/SwiftUI-Agent-Skill/blob/main/LICENSE)
  3. [![Weekly Installs](https://img.shields.io/badge/weekly%20installs-31.4k-brightgreen)](https://skills.sh/avdlee/swiftui-agent-skill/swiftui-expert-skill)
  4. [![GitHub Release](https://img.shields.io/github/v/release/AvdLee/SwiftUI-Agent-Skill)](https://github.com/AvdLee/SwiftUI-Agent-Skill/releases)
  5. [![GitHub Stars](https://img.shields.io/github/stars/AvdLee/SwiftUI-Agent-Skill?style=flat)](https://github.com/AvdLee/SwiftUI-Agent-Skill/stargazers)
  6. 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.
  7. This repository distills practical SwiftUI best practices into actionable, concise references for agents and code review workflows.
  8. 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.
  9. ## Who this is for
  10. - Teams adopting modern SwiftUI APIs who want quick, correct defaults
  11. - Developers reviewing or refactoring SwiftUI views and data flow
  12. - Anyone shipping performant lists, scrolling, sheets, and navigation in SwiftUI
  13. ## See also my other skills:
  14. - [Swift Concurrency Expert](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill)
  15. - [Core Data Expert](https://github.com/AvdLee/Core-Data-Agent-Skill)
  16. - [Swift Testing Expert](https://github.com/AvdLee/Swift-Testing-Agent-Skill)
  17. - [Xcode Build Optimization Agent Skill](https://github.com/AvdLee/Xcode-Build-Optimization-Agent-Skill)
  18. - [Xcode Simulator AI Control Agent Skill](https://www.rocketsim.app/docs/features/agentic-development/agent-skill/)
  19. ## How to Use This Skill
  20. ### Option A: Using skills.sh (recommended)
  21. Install this skill with a single command:
  22. ```bash
  23. npx skills@latest add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill
  24. ```
  25. For more information, [visit the skills.sh platform page](https://skills.sh/avdlee/swiftui-agent-skill/swiftui-expert-skill).
  26. 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.
  27. Then use the skill in your AI agent, for example:
  28. > Use the swiftui expert skill and review the current SwiftUI code for state-management and performance improvements
  29. ### Option B: ChatGPT & Codex (OpenAI Plugins Directory)
  30. This plugin is distributed through the universal OpenAI Plugins Directory shared by ChatGPT and Codex:
  31. 1. In the ChatGPT desktop app, select **Codex** (or ChatGPT with **Work** enabled), or use the plugin browser in Codex CLI.
  32. 2. Open **Plugins** and search for "SwiftUI Expert".
  33. 3. Install the plugin. The skill becomes available in new chats and sessions.
  34. ### Option C: Claude Code Plugin
  35. #### Personal Usage
  36. To install this Skill for your personal use in Claude Code:
  37. 1. Add the marketplace:
  38. ```bash
  39. /plugin marketplace add AvdLee/SwiftUI-Agent-Skill
  40. ```
  41. 2. Install the Skill:
  42. ```bash
  43. /plugin install swiftui-expert@swiftui-expert-skill
  44. ```
  45. #### Project Configuration
  46. To automatically provide this Skill to everyone working in a repository, configure the repository's `.claude/settings.json`:
  47. ```json
  48. {
  49. "enabledPlugins": {
  50. "swiftui-expert@swiftui-expert-skill": true
  51. },
  52. "extraKnownMarketplaces": {
  53. "swiftui-expert-skill": {
  54. "source": {
  55. "source": "github",
  56. "repo": "AvdLee/SwiftUI-Agent-Skill"
  57. }
  58. }
  59. }
  60. }
  61. ```
  62. When team members open the project, Claude Code will prompt them to install the Skill.
  63. ### Option D: Cursor Plugin
  64. 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.
  65. ### Using another tool?
  66. See [INSTALLATION.md](INSTALLATION.md) for all other installation options: pi, Gemini CLI, Autohand Code, and manual installation.
  67. **How to verify**:
  68. Your agent should reference the workflow/checklists in `skills/swiftui-expert-skill/SKILL.md` and jump into the relevant reference file for your task.
  69. ## What's Inside
  70. 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.
  71. - **State management** -- property wrapper selection, `@Observable`, data flow patterns
  72. - **Environment** -- `@Entry`, stable defaults, and invalidation-aware propagation
  73. - **View composition** -- extraction patterns, container views, identity stability
  74. - **Modifiers** -- conditional identity, no-effect values, and `AnyShapeStyle`
  75. - **Performance** -- hot-path optimization, lazy loading, `@Observable` granularity
  76. - **Lists & ForEach** -- stable identity, Table, inline filtering pitfalls
  77. - **Navigation & sheets** -- NavigationStack, NavigationSplitView, Inspector, enum-based sheets
  78. - **Swift Charts** -- marks, axes, selection, styling, accessibility, Chart3D
  79. - **Animations** -- implicit/explicit, transitions, phase/keyframe, `@Animatable` macro
  80. - **macOS** -- scenes, window styling, Table, HSplitView, AppKit interop
  81. - **Liquid Glass** -- iOS 26+ glass effects, containers, fallback patterns
  82. - **SDK 27** -- `@State` and `@ContentBuilder` migrations, reordering, AsyncImage caching, swipe actions, dialogs, and toolbars
  83. - **Accessibility** -- VoiceOver, Dynamic Type, grouping, traits
  84. - **Image optimization** -- AsyncImage, downsampling, caching
  85. - **Latest APIs** -- deprecated-to-modern migration guide (iOS 15+ through iOS 27+)
  86. - **Instruments trace recording & analysis** -- bundled `xctrace` toolchain for diagnosing hangs, hitches, and expensive SwiftUI view updates (see below)
  87. Non-opinionated: focuses on correctness and performance, not architecture or code style.
  88. ## Recording & Analysing Instruments Traces
  89. 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.
  90. **When it triggers:**
  91. - A `.trace` path appears in the prompt (analysis).
  92. - The user asks to record, profile, or capture a session (recording).
  93. **What the agent can then ask:**
  94. ```text
  95. Analyse ~/Desktop/MyApp.trace and tell me what's wrong.
  96. Focus analysis on what happens right after the 'feed loaded' log.
  97. Which of my SwiftUI views is responsible for the hang around 6s?
  98. Record a new trace: attach to MyApp on my iPhone — I'll tell you when I'm done.
  99. ```
  100. **Under the hood:**
  101. - `scripts/record_trace.py` — wraps `xctrace record`. Supports attach / launch / all-processes, stop-file for agent-driven sessions, time-limits, JSON device & template discovery.
  102. - `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.
  103. - `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).
  104. **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.
  105. 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).
  106. 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.
  107. ## Skill Structure
  108. <!-- BEGIN REFERENCE STRUCTURE -->
  109. ```text
  110. skills/swiftui-expert-skill/
  111. SKILL.md
  112. references/
  113. accessibility-patterns.md - Accessibility traits, grouping, Dynamic Type, and VoiceOver
  114. animation-advanced.md - Performance, interpolation, and complex animation chains
  115. animation-basics.md - Core animation concepts, implicit/explicit animations, timing
  116. animation-transitions.md - View transitions, matchedGeometryEffect, and state changes
  117. charts-accessibility.md - Charts accessibility, fallback strategies, and WWDC sessions
  118. charts.md - Swift Charts marks, axes, selection, styling, composition, and Chart3D
  119. document-apps.md - Document protocol, reading, writing, autosave, and FileDocument migration
  120. environment-patterns.md - @Entry, stable defaults, custom actions, and environment invalidation
  121. focus-patterns.md
  122. image-optimization.md - AsyncImage usage, downsampling, caching
  123. iphone-duo.md - Choosing a large-display technique by screen structure, Duo displays, fold regions, displacement, hinge effects, and scene accessories
  124. latest-apis.md
  125. layout-best-practices.md - Layout patterns and GeometryReader alternatives
  126. liquid-glass.md - iOS 26+ glass effects and fallback patterns
  127. list-patterns.md - ForEach identity and list performance
  128. localization.md
  129. macos-scenes.md - Scene lifecycle, multi-window setups, and menu bar scenes on macOS
  130. macos-views.md - macOS-specific SwiftUI views and platform differences from iOS
  131. macos-window-styling.md - Window chrome, toolbar, and title bar styling in SwiftUI
  132. modifier-patterns.md - Conditional modifiers, structural identity, and AnyShapeStyle
  133. performance-patterns.md - Hot-path optimizations and update control
  134. previews.md
  135. scroll-patterns.md - ScrollViewReader and programmatic scrolling
  136. sheet-navigation-patterns.md - Sheets and type-safe navigation
  137. soft-deprecation.md
  138. state-management.md - Property wrapper selection and data flow
  139. styled-text-editing.md - AttributedString editing, selection, formatting, and Markdown
  140. text-patterns.md
  141. toolbar-patterns.md - Customization, overflow, visibility, transitions, and minimization
  142. trace-analysis.md
  143. trace-recording.md
  144. view-structure.md - View extraction and composition patterns
  145. webkit-integration.md - WebView, WebPage, navigation, JavaScript, and exports
  146. ```
  147. <!-- END REFERENCE STRUCTURE -->
  148. ## Maintenance
  149. The repository includes a maintenance skill for keeping API guidance current:
  150. ```text
  151. .agents/skills/update-swiftui-apis/
  152. SKILL.md - Workflow for scanning Apple docs and updating latest-apis.md
  153. references/
  154. scan-manifest.md - Categorized API areas, doc paths, and search queries to scan
  155. ```
  156. 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.
  157. Note: only `swiftui-expert-skill` is intended to be published in the Cursor plugin. The maintenance skill remains a repository workflow utility.
  158. ## Contributing
  159. Contributions are welcome! This repository follows the [Agent Skills open format](https://agentskills.io/home), which has specific structural requirements.
  160. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for:
  161. - How to contribute improvements to `SKILL.md` and the reference files
  162. - Format requirements and quality standards
  163. - Pull request process
  164. ## Acknowledgments
  165. Several SwiftUI guidelines in this skill were inspired by or derived from the following works:
  166. - [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.
  167. - [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.
  168. - [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.
  169. ## About the authors
  170. 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.
  171. ## Resources
  172. - [Story behind this skill](https://www.swiftdifferently.com/blog/swiftui/How%20I%20stopped-resisting-ai-and-started-teaching-it)
  173. ## License
  174. 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 in

Free to use. If it’s helped, pass it on.