SwiftUI Agent Skill

What It Does

SwiftUI Agent Skill is a single-skill pack (swiftui-expert-skill) that gives any agent supporting the Agent Skills open format expert guidance on writing, reviewing, and refactoring SwiftUI for iOS and macOS. It targets iOS and macOS developers and teams adopting modern SwiftUI APIs. The bulk of the value is a 26-file reference corpus (8,680 lines) covering state management, view composition, performance, lists, navigation, Swift Charts, animations, macOS scenes, accessibility, localization, and iOS 26+ Liquid Glass. On top of the prose guidance it ships an executable Python toolchain that wraps xctrace to record and analyze Instruments .trace files, correlating hangs and animation hitches with SwiftUI view-update cause graphs.

The Good

The reference corpus is authoritative and unusually deep. The 26 reference files total 8,680 lines, ranging from a 39-line soft-deprecation policy to an 854-line view-structure guide and a 602-line Swift Charts reference. Every one of the 26 references cited in the SKILL.md Topic Router resolves to a real file (zero broken links). The content is non-opinionated by design: it enforces correctness and performance rules without mandating MVVM or any architecture, which keeps it usable across teams with different conventions.

The bundled Instruments parser is a genuine differentiator. No other agent skill we have reviewed ships an executable trace analyzer. The instruments_parser package is 13 pure-stdlib Python modules (one per lane: time_profiler, hangs, hitches, swiftui, causes, plus cross-lane correlate and a markdown summary). It reads five Instruments lanes, correlates hangs and hitches against main-thread samples, and exposes a single diagnostic (main_running_coverage_pct, below 25 percent means blocked, at or above 75 percent means CPU-bound) that separates two radically different fix paths. Discovery modes (--list-logs, --list-signposts, --fanin-for) and a --window START_MS:END_MS flag let an agent scope analysis to a precise slice or trace a specific view back to its invalidation sources.

The parser logic is correct, verified with real assertions. I monkeypatched the xctrace.export_schema call to feed the hangs lane synthetic export XML containing three hangs (100ms, 600ms, 1500ms). The parser correctly converted nanoseconds to milliseconds, sorted offenders descending, and bucketed them into the right severity ranges (one each in lt_250ms, 250ms_1s, gt_1s). The worst duration (1500.0ms) and total (2200.0ms) matched hand calculation exactly. Thread and process name extraction (Main Thread, Background Thread, MyApp) also worked. The bundled 3-test pytest suite passes (it covers env-var redaction and the system-wide-recording consent guard, both added by a recent security PR).

Distribution across agent runtimes is exemplary. The repo ships ready-made manifests for six channels: skills.sh (npx skills add), Claude Code (.claude-plugin/marketplace.json plus plugin.json), Cursor (.cursor-plugin/plugin.json), Codex and OpenAI-compatible tools (agents/openai.yaml), the pi package manager (package.json), and manual copy. The Claude Code project-config snippet in the README lets a team pin the skill in .claude/settings.json so every contributor is prompted to install it. The README links to each tool's official "where to save skills" documentation.

Provenance and authorship are strong. The primary author is Antoine van der Lee, who writes the widely-read SwiftLee SwiftUI blog and is credited as the source of much of the guidance. The repo holds 3,336 stars and 153 forks (about 4.6 percent fork density, a healthy reuse signal), is six months old, and carries an MIT license. A README badge claims 16.6k weekly installs via skills.sh.

The Bad

The executable half only runs on macOS with full Xcode installed. The trace toolchain shells out to xctrace, which ships only inside the full Xcode bundle. On a host with just Command Line Tools (the common CI and server configuration), /usr/bin/xctrace is a stub that prints tool 'xctrace' requires Xcode and exits non-zero. This means the recording and live-export paths are macOS-plus-Xcode only, narrowing who can use the differentiating feature. The pure-reference half works everywhere.

record_trace.py surfaces xctrace failures as an uncaught traceback. When xctrace list devices or xctrace list templates fails (as it does without full Xcode), the script raises a raw subprocess.CalledProcessError traceback rather than catching it and printing a friendly "Xcode is required" message. By contrast analyze_trace.py handles a missing trace file cleanly (error: trace not found). The recording side is noticeably less polished on error paths than the analysis side.

Version drift across the distribution manifests. In the current HEAD the three plugin manifests disagree: .claude-plugin/marketplace.json, .claude-plugin/plugin.json, and .cursor-plugin/plugin.json all read 4.0.0, while agents/openai.yaml (the Codex/OpenAI surface) reads 2.2.0, two major versions behind. The latest GitHub release is tagged 4.1.0. A contributor installing via Codex sees a stale version string. This is a manifest-hygiene gap, not a functional break, but it is exactly the kind of self-consistency issue a skill this mature should not have.

Smoke Test Results

Host-based testing on macOS (aarch64) with Command Line Tools only (no full Xcode). The repo was shallow-cloned to /tmp/swiftui-skill-review. Full transcript in the sandbox log linked below.

Structural validation

$ wc -l swiftui-expert-skill/references/*.md | tail -1
8680 total (26 reference files)

$ find swiftui-expert-skill -name "SKILL.md" | wc -l
1 (single published skill; the maintenance skill lives under .agents/ and is documented as non-published)

$ # frontmatter compliance (against the repo's own copilot-instructions rules):
name: swiftui-expert-skill (20 chars, <=64, lowercase-hyphen-only) PASS
description: 409 chars (<=1024) PASS

$ # Topic Router reference resolution (26 unique refs cited in SKILL.md):
missing files: NONE - all resolve PASS

$ # version consistency across manifests:
.claude-plugin/marketplace.json version 4.0.0
.claude-plugin/plugin.json version 4.0.0
.cursor-plugin/plugin.json version 4.0.0
agents/openai.yaml version 2.2.0 <- DRIFT
git release tag 4.1.0 <- DRIFT WARN

$ # LICENSE present:
LICENSE -> MIT License PASS

Pass rate: 5 of 6. The single warning is manifest version drift (Claude/Cursor at 4.0.0, OpenAI at 2.2.0, release tag at 4.1.0). Everything structural is clean: one published skill, compliant frontmatter, zero broken references, MIT license.

Run B. Functional verification (does the toolchain do what it claims?)

$ python3 swiftui-expert-skill/scripts/record_trace.py --help
usage: record_trace.py [-h] [--list-devices | --list-templates] ... PASS (CLI loads)

$ python3 swiftui-expert-skill/scripts/analyze_trace.py --help
usage: analyze_trace.py [-h] --trace TRACE [--output OUTPUT] ... PASS (CLI loads)

$ python3 -m pytest tests/ -q
... PASS (3 passed in 0.01s)

$ python3 analyze_trace.py --trace /tmp/nope.trace --json-only
error: trace not found: /tmp/nope.trace PASS (clean error, no traceback)

$ python3 record_trace.py --list-devices (host has no full Xcode)
subprocess.CalledProcessError: Command '['xctrace', 'list', 'devices']' ... PARTIAL (uncaught traceback; xctrace stub needs Xcode)

$ # hangs lane parser fed synthetic xctrace-export XML (monkeypatched export):
count: 3 worst_duration_ms: 1500.0 total_duration_ms: 2200.0
severity_buckets: {'lt_250ms': 1, '250ms_1s': 1, 'gt_1s': 1}
ALL ASSERTIONS PASSED PASS (parser logic correct)

Functional pass rate: 5 of 6. The parser logic is verified correct via synthetic input. The one partial is the recording path, which is blocked by the host lacking full Xcode (a host limitation, not a skill defect), compounded by the script surfacing the failure as an uncaught traceback.

Full functional log ->

What the runs tell you

The agent-skill and reference half is impeccable: compliant frontmatter, every cross-reference resolves, tests pass, and the parser produces correct output on controlled input. The executable half is real and well-engineered, but its differentiating capability (recording and live-analyzing traces) is gated behind full Xcode on macOS, which I could not exercise on this host. Treat the analysis parser as verified and the recording pipeline as trusted-on-Xcode-but-not-independently-confirmed here.

Setup Walkthrough

1. Quickest path is skills.sh: npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill. This drops the swiftui-expert-skill/ folder into your tool's skills directory.
2. For Claude Code, add the marketplace then install: /plugin marketplace add AvdLee/SwiftUI-Agent-Skill, then /plugin install swiftui-expert@swiftui-expert-skill.
3. Verify by asking your agent to use the "swiftui-expert" skill on a SwiftUI file. It should consult SKILL.md and pull in the relevant reference (for example references/state-management.md).
4. To use the trace toolchain, you need macOS with full Xcode (not just Command Line Tools). Confirm with xctrace version. Run python3 scripts/analyze_trace.py --trace your.trace --json-only to analyze, or python3 scripts/record_trace.py --list-devices before recording.

Gotcha: on a host with only Command Line Tools, xctrace is a stub. analyze_trace.py degrades gracefully (clean errors), but record_trace.py --list-devices throws an uncaught traceback. Install full Xcode and run xcode-select if you need the recording path.

Alternatives

1. aldefy/compose-skill -- the Jetpack-Compose/Android counterpart. Same open-format skill idea for a different mobile platform. Prefer it if your stack is Android.
2. Dimillian/Skills -- a collection of SwiftUI-focused Codex skills that partly inspired this repo. Lighter weight and less structured, but a faster skim for a single topic. This skill is the more complete and maintained successor.
3. anthropics/skills -- the official Anthropic general-purpose skill pack. Broader coverage across many languages but no SwiftUI depth and no Instruments tooling. Use it for general tasks and this skill for SwiftUI.