{
  "markdown": "# SwiftUI Expert Skill\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/AvdLee/SwiftUI-Agent-Skill/blob/main/LICENSE)\n[![Weekly Installs](https://img.shields.io/badge/weekly%20installs-16.6k-brightgreen)](https://skills.sh/avdlee/swiftui-agent-skill/swiftui-expert-skill)\n[![GitHub Release](https://img.shields.io/github/v/release/AvdLee/SwiftUI-Agent-Skill)](https://github.com/AvdLee/SwiftUI-Agent-Skill/releases)\n[![GitHub Stars](https://img.shields.io/github/stars/AvdLee/SwiftUI-Agent-Skill?style=flat)](https://github.com/AvdLee/SwiftUI-Agent-Skill/stargazers)\n\nExpert 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.\n\nThis repository distills practical SwiftUI best practices into actionable, concise references for agents and code review workflows.\n\nThis 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.\n\n## Who this is for\n- Teams adopting modern SwiftUI APIs who want quick, correct defaults\n- Developers reviewing or refactoring SwiftUI views and data flow\n- Anyone shipping performant lists, scrolling, sheets, and navigation in SwiftUI\n\n## See also my other skills:\n- [Swift Concurrency Expert](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill)\n- [Core Data Expert](https://github.com/AvdLee/Core-Data-Agent-Skill)\n- [Swift Testing Expert](https://github.com/AvdLee/Swift-Testing-Agent-Skill)\n- [Xcode Build Optimization Agent Skill](https://github.com/AvdLee/Xcode-Build-Optimization-Agent-Skill)\n- [Xcode Simulator AI Control Agent Skill](https://www.rocketsim.app/docs/features/agentic-development/agent-skill/)\n\n## How to Use This Skill\n\n### Option A: Using skills.sh (recommended)\nInstall this skill with a single command:\n\n```bash\nnpx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill\n```\n\nFor more information, [visit the skills.sh platform page](https://skills.sh/avdlee/swiftui-agent-skill/swiftui-expert-skill).\n\nThen use the skill in your AI agent, for example:\n> Use the swiftui expert skill and review the current SwiftUI code for state-management and performance improvements\n\n### Option B: ChatGPT & Codex (OpenAI Plugins Directory)\n\nThis plugin is distributed through the universal OpenAI Plugins Directory shared by ChatGPT and Codex:\n\n1. In the ChatGPT desktop app, select **Codex** (or ChatGPT with **Work** enabled), or use the plugin browser in Codex CLI.\n2. Open **Plugins** and search for \"SwiftUI Expert\".\n3. Install the plugin. The skill becomes available in new chats and sessions.\n\n### Option C: Claude Code Plugin\n\n#### Personal Usage\nTo install this Skill for your personal use in Claude Code:\n\n1. Add the marketplace:\n\n```bash\n/plugin marketplace add AvdLee/SwiftUI-Agent-Skill\n```\n\n2. Install the Skill:\n\n```bash\n/plugin install swiftui-expert@swiftui-expert-skill\n```\n\n#### Project Configuration\nTo automatically provide this Skill to everyone working in a repository, configure the repository's `.claude/settings.json`:\n\n```json\n{\n  \"enabledPlugins\": {\n    \"swiftui-expert@swiftui-expert-skill\": true\n  },\n  \"extraKnownMarketplaces\": {\n    \"swiftui-expert-skill\": {\n      \"source\": {\n        \"source\": \"github\",\n        \"repo\": \"AvdLee/SwiftUI-Agent-Skill\"\n      }\n    }\n  }\n}\n```\n\nWhen team members open the project, Claude Code will prompt them to install the Skill.\n\n### Option D: Cursor Plugin\n\nLoad 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.\n\n### Using another tool?\n\nSee [INSTALLATION.md](INSTALLATION.md) for all other installation options: pi, Gemini CLI, Autohand Code, and manual installation.\n\n**How to verify**:\n\nYour agent should reference the workflow/checklists in `skills/swiftui-expert-skill/SKILL.md` and jump into the relevant reference file for your task.\n\n## What's Inside\n\nThis 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.\n\n- **State management** -- property wrapper selection, `@Observable`, data flow patterns\n- **View composition** -- extraction patterns, container views, identity stability\n- **Performance** -- hot-path optimization, lazy loading, `@Observable` granularity\n- **Lists & ForEach** -- stable identity, Table, inline filtering pitfalls\n- **Navigation & sheets** -- NavigationStack, NavigationSplitView, Inspector, enum-based sheets\n- **Swift Charts** -- marks, axes, selection, styling, accessibility, Chart3D\n- **Animations** -- implicit/explicit, transitions, phase/keyframe, `@Animatable` macro\n- **macOS** -- scenes, window styling, Table, HSplitView, AppKit interop\n- **Liquid Glass** -- iOS 26+ glass effects, containers, fallback patterns\n- **Accessibility** -- VoiceOver, Dynamic Type, grouping, traits\n- **Image optimization** -- AsyncImage, downsampling, caching\n- **Latest APIs** -- deprecated-to-modern migration guide (iOS 15+ through iOS 26+)\n- **Instruments trace recording & analysis** -- bundled `xctrace` toolchain for diagnosing hangs, hitches, and expensive SwiftUI view updates (see below)\n\nNon-opinionated: focuses on correctness and performance, not architecture or code style.\n\n## Recording & Analysing Instruments Traces\n\nUnlike 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.\n\n**When it triggers:**\n\n- A `.trace` path appears in the prompt (analysis).\n- The user asks to record, profile, or capture a session (recording).\n\n**What the agent can then ask:**\n\n```text\nAnalyse ~/Desktop/MyApp.trace and tell me what's wrong.\n\nFocus analysis on what happens right after the 'feed loaded' log.\n\nWhich of my SwiftUI views is responsible for the hang around 6s?\n\nRecord a new trace: attach to MyApp on my iPhone — I'll tell you when I'm done.\n```\n\n**Under the hood:**\n\n- `scripts/record_trace.py` — wraps `xctrace record`. Supports attach / launch / all-processes, stop-file for agent-driven sessions, time-limits, JSON device & template discovery.\n- `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.\n- `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).\n\n**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.\n\nFull 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).\n\n## Skill Structure\n<!-- BEGIN REFERENCE STRUCTURE -->\n```text\nskills/swiftui-expert-skill/\n  SKILL.md\n  references/\n    accessibility-patterns.md - Accessibility traits, grouping, Dynamic Type, and VoiceOver\n    animation-advanced.md - Performance, interpolation, and complex animation chains\n    animation-basics.md - Core animation concepts, implicit/explicit animations, timing\n    animation-transitions.md - View transitions, matchedGeometryEffect, and state changes\n    charts-accessibility.md - Charts accessibility, fallback strategies, and WWDC sessions\n    charts.md - Swift Charts marks, axes, selection, styling, composition, and Chart3D\n    focus-patterns.md\n    image-optimization.md - AsyncImage usage, downsampling, caching\n    latest-apis.md\n    layout-best-practices.md - Layout patterns and GeometryReader alternatives\n    liquid-glass.md - iOS 26+ glass effects and fallback patterns\n    list-patterns.md - ForEach identity and list performance\n    localization.md\n    macos-scenes.md - Scene lifecycle, multi-window setups, and menu bar scenes on macOS\n    macos-views.md - macOS-specific SwiftUI views and platform differences from iOS\n    macos-window-styling.md - Window chrome, toolbar, and title bar styling in SwiftUI\n    performance-patterns.md - Hot-path optimizations and update control\n    previews.md\n    scroll-patterns.md - ScrollViewReader and programmatic scrolling\n    sheet-navigation-patterns.md - Sheets and type-safe navigation\n    soft-deprecation.md\n    state-management.md - Property wrapper selection and data flow\n    text-patterns.md\n    trace-analysis.md\n    trace-recording.md\n    view-structure.md - View extraction and composition patterns\n```\n<!-- END REFERENCE STRUCTURE -->\n\n## Maintenance\n\nThe repository includes a maintenance skill for keeping API guidance current:\n\n```text\n.agents/skills/update-swiftui-apis/\n  SKILL.md               - Workflow for scanning Apple docs and updating latest-apis.md\n  references/\n    scan-manifest.md     - Categorized API areas, doc paths, and search queries to scan\n```\n\nUse 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.\n\nNote: only `swiftui-expert-skill` is intended to be published in the Cursor plugin. The maintenance skill remains a repository workflow utility.\n\n## Contributing\n\nContributions are welcome! This repository follows the [Agent Skills open format](https://agentskills.io/home), which has specific structural requirements.\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for:\n- How to contribute improvements to `SKILL.md` and the reference files\n- Format requirements and quality standards\n- Pull request process\n\n## Acknowledgments\n\nSeveral SwiftUI guidelines in this skill were inspired by or derived from the following works:\n\n- [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.\n- [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.\n- [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.\n\n## About the authors\n\nCreated 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.\n\n## Resources\n- [Story behind this skill](https://www.swiftdifferently.com/blog/swiftui/How%20I%20stopped-resisting-ai-and-atarted-teaching-it)\n\n## License\n\nThis skill is open-source and available under the MIT License. See [LICENSE](LICENSE) for details.\n",
  "bytes": 12546,
  "sha": "7e417c743e707f51c2d4febff21ba38bde60688b4a3ec10dc4f1c149014840ce",
  "repo_slug": "avdlee/swiftui-agent-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_avdlee_swiftui_agent_skill_swiftui_exper_4c3b2314/readme"
}