swiftui-expert-skill
Use when writing, reviewing, or refactoring SwiftUI code for iOS or macOS, including state management and `@Observable` data flow, view composition and invalidation/performance, lists and `ForEach` identity, environment usage, localization, animations, Liquid Glass adoption, migrating soft-deprecated APIs, or Instruments `.trace` capture/analysis for hangs, hitches, CPU hotspots, or
AvdLee · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add AvdLee/SwiftUI-Agent-Skill --skill swiftui-expert-skill技能说明
name: swiftui-expert-skill
description: Use when writing, reviewing, or refactoring SwiftUI code for iOS or macOS, including state management and @Observable data flow, view composition and invalidation/performance, lists and ForEach identity, environment usage, localization, animations, Liquid Glass adoption, migrating soft-deprecated APIs, or Instruments .trace capture/analysis for hangs, hitches, CPU hotspots, or
excessive view updates.
SwiftUI Expert Skill
Operating Rules
- Consult
references/latest-apis.mdat the start of every task to avoid deprecated APIs - Prefer native SwiftUI APIs over UIKit/AppKit bridging unless bridging is necessary
- Focus on correctness and performance; do not enforce specific architectures (MVVM, VIPER, etc.)
- Encourage separating business logic from views for testability without mandating how
- Follow Apple's Human Interface Guidelines and API design patterns
- Only adopt Liquid Glass when explicitly requested by the user (see
references/liquid-glass.md) - Present performance optimizations as suggestions, not requirements
- Use
#availablegating with sensible fallbacks for version-specific APIs
Task Workflow
Review existing SwiftUI code
- Read the code under review and identify which topics apply
- Flag deprecated APIs (compare against
references/latest-apis.md) - Run the Topic Router below for each relevant topic
- Validate
#availablegating and fallback paths for iOS 26+ features
Improve existing SwiftUI code
- Audit current implementation against the Topic Router topics
- Replace deprecated APIs with modern equivalents from
references/latest-apis.md - Refactor hot paths to reduce unnecessary state updates
- Extract complex view bodies into separate subviews
- Suggest image downsampling when
UIImage(data:)is encountered (optional optimization, seereferences/image-optimization.md)
Implement new SwiftUI feature
- Design data flow first: identify owned vs injected state
- Structure views for optimal diffing (extract subviews early)
- Apply correct animation patterns (implicit vs explicit, transitions)
- Use
Buttonfor all tappable elements; add accessibility grouping and labels - Gate version-specific APIs with
#availableand provide fallbacks
Record a new Instruments trace
Trigger when the user asks to "record a trace", "profile the app", "capture a session", etc. Full reference: references/trace-recording.md.
- Confirm target — attach to a running app, launch an app, or record all processes? If the user didn't say, ask. List connected devices when useful:
python3 "${SKILL_DIR}/scripts/record_trace.py" --list-devices - Pick a template based on target kind — the
SwiftUItemplate populates the SwiftUI lane on any real device: a physical iOS/iPadOS device or the host Mac. The only exception is the iOS Simulator, where the SwiftUI lane comes back empty — switch to--template "Time Profiler"in that case (still gives Time Profiler + Hangs + Animation Hitches). Always check--list-devices:simulatorskind →Time Profiler;deviceskind (real devices and the host Mac) → defaultSwiftUI. Full decision table inreferences/trace-recording.md. - Start the recording. For agent-driven sessions where the user says "I'll tell you when I'm done", start in the background and use a stop-file:
For interactive sessions, just tell the user to press Ctrl+C when done.python3 "${SKILL_DIR}/scripts/record_trace.py" \ --device "<name|udid>" --attach "<AppName>" \ --stop-file /tmp/stop-trace --output ~/Desktop/session.trace - Signal stop — when the user says they've finished exercising the app,
touch /tmp/stop-trace. The script cleanly SIGINTs xctrace and waits up to 60s for finalisation. - Analyse the resulting trace (flow into the "Trace-driven improvement" workflow below).
Trace-driven improvement (Instruments .trace provided)
Trigger whenever the user's request references a .trace file. A target SwiftUI source file is optional — if given, cite specific lines; if not, recommend where to look based on view names and symbols the trace already reveals.
Full reference: references/trace-analysis.md. Summary of the composition pattern:
- Scope the analysis. Ask yourself: does the user want the whole trace, or a slice?
- "focus on X / after X / between X and Y / during X" → resolve to a window first (see step 2).
- No scoping cue → analyse the whole trace.
- Resolve a window (only if the user scoped). The parser exposes two discovery modes:
Both modes accept# Find a log that marks the start/end of the region of interest: python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \ --list-logs --log-message-contains "loaded feed" --log-limit 5 # Or list os_signpost intervals (paired begin/end), filterable by name: python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \ --list-signposts --signpost-name-contains "ImageDecode"--window START_MS:END_MSto scope discovery. Pick thetime_ms(for logs) orstart_ms/end_ms(for signposts) that match the user's description. Build a window like--window 10400:11700. - Run the main analysis (with or without
--window):python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \ --json-only --top 10 [--window START_MS:END_MS] - Interpret with
references/trace-analysis.md— key diagnostics:main_running_coverage_pctinside each correlation (<25% = blocked; ≥75% = CPU-bound).swiftui-causes.top_sourcesreveals why updates keep happening — high-edge-count sources likeUserDefaultObserver.send()or wideEnvironmentWriterentries are structural invalidation bugs. Fixing one often collapses many downstream hot views.
- When a specific view shows as expensive, ask who's invalidating it. Use `--f