AvdLee SwiftUI-Agent-Skill: SwiftUI Best Practices Loaded On Demand

Most AI assistants know SwiftUI at the level of a Stack Overflow answer. AvdLee/SwiftUI-Agent-Skill instead loads curated, topic-by-topic reference files exactly when the agent needs them, so the model does not have to guess between @StateObject and @Observable, or default to the wrong layout container.

Why This Skill Matters

The README frames the project as a portable Agent Plugin (spec 1.0.0): compatible clients discover the skill from a root plugin.json manifest and a skills/ directory. Client-specific manifests for Claude Code, Cursor, Codex, and pi are included, and the README plus its INSTALLATION.md document additional install paths for ChatGPT (Work mode) and Gemini CLI. The skill is non-opinionated about architecture and code style; it focuses on correctness and performance.

The repository has 3.5k stars on GitHub and is MIT-licensed. The README highlights weekly install volume via a skills.sh badge (16.6k weekly installs as of the badge snapshot); the exact weekly number changes — what matters is that the install volume makes this one of the more widely adopted SwiftUI skills today.

The reference surface is broad without bloating the agent's task context, because files load on demand:

• State management (property wrappers, @Observable, data flow patterns)
• View composition (extraction patterns, container views, identity stability)
• Performance (hot-path optimization, lazy loading, @Observable granularity)
• Lists and ForEach (stable identity, Table, inline filtering pitfalls)
• Navigation and 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, iOS 15+ through iOS 26+)
• Instruments trace recording and analysis (a Python toolchain wrapping xctrace)

Installation

The README recommends the skills.sh install route:

npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill

For Claude Code, the README documents a plugin marketplace route:

/plugin marketplace add AvdLee/SwiftUI-Agent-Skill
/plugin install swiftui-expert@swiftui-expert-skill

To ship the skill with a project so the whole team gets prompted to install it on first open, add to .claude/settings.json:

{
  "enabledPlugins": {
    "swiftui-expert@swiftui-expert-skill": true
  },
  "extraKnownMarketplaces": {
    "swiftui-expert-skill": {
      "source": {
        "source": "github",
        "repo": "AvdLee/SwiftUI-Agent-Skill"
      }
    }
  }
}

For Codex or ChatGPT (Work mode), the README points to the OpenAI Plugins Directory — search for "SwiftUI Expert" inside the Plugins browser. For Cursor, the README notes both a portable Agent Plugins manifest (plugin.json) and a Cursor Plugin manifest (.cursor-plugin/plugin.json) are included.

Real Workflow: Review a View for State and Performance

You inherit a SwiftUI screen that animates poorly and rebuilds expensive subviews on every parent tick. Ask your agent to consult the skill and review the file.

Step 1. Trigger the skill by phrasing:

Use the swiftui expert skill and review the current SwiftUI code for state-management and performance improvements.

Step 2. The agent should open skills/swiftui-expert-skill/SKILL.md, then jump to references/state-management.md and references/performance-patterns.md for the file in question.

Step 3. Common fixes the skill guides the agent toward:

• Replace @StateObject + ObservableObject with @Observable when the model is iOS 17+ only.
• Push state down so subviews with their own @State do not invalidate the parent.
• Use stable id keys in ForEach; never \.self on a non-Identifiable collection.
• Move heavy work out of body into a computed property or an init.

Step 4. Ask the agent to re-run after each change and re-check Instruments (xctrace) for view-update spikes — see the next workflow for how the skill helps there.

Real Workflow: Analyze an .xctrace File with the Bundled Python Toolchain

A user reports a 6-second hang during feed scroll. The skill ships a Python toolchain that parses the trace into structured lanes.

Step 1. Drop the trace on your Desktop: ~/Desktop/MyApp.trace.

Step 2. Ask the agent:

Analyse ~/Desktop/MyApp.trace and tell me what's wrong.

Step 3. The agent invokes scripts/analyze_trace.py, which reads the Time Profiler, Hangs, Animation Hitches, SwiftUI updates, and SwiftUI cause-graph lanes, correlates hangs/hitches with main-thread samples, and emits JSON plus a markdown summary.

Step 4. Read the main_running_coverage_pct metric on each hang/hitch correlation. The README's diagnostic rule: < 25% means the main thread was blocked (I/O, lock, sync await), ≥ 75% means CPU-bound. Those two cases call for radically different fixes — one wants an actor hop or a Task, the other wants LazyVGrid instead of a hand-rolled layout.

Step 5. Scope the analysis further with --window START_MS:END_MS to focus on a slice, or --fanin-for to trace a specific view back to its invalidation sources.

Tips

• Use the agent's "open the right reference file" habit instead of asking the model to remember SwiftUI rules from training data.
• For a Hangs trace, look at main_running_coverage_pct first — it separates blocked-main from CPU-bound in one number.
• iOS 26+ Liquid Glass has explicit fallback patterns in references/liquid-glass.md; check there before adopting .glassEffect in production.
• On Cursor, the README describes the local-clone path under ~/.cursor/plugins/local as the option available today, with a marketplace install "once listed".

When Not to Use This

If your stack is SwiftUI pre-iOS-17 or you are stuck on @StateObject/ObservableObject patterns, the skill's preference for @Observable will steer the agent away from patterns that match your deployment target. If you need Swift Concurrency-specific guidance (actors, async let, Swift 6 strict concurrency), AvdLee ships a separate Swift-Concurrency-Agent-Skill for that. If you want a directory of Apple-platform skills rather than a single deep one, see twostraws/Swift-Agent-Skills.

See the leaderboard for more skills.