swiftui-expert-skill – Coding skill for AI agents

SwiftUI Expert Skill

When to Use

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, API migrations and analysis of explicitly selected Instruments traces.

Operating Rules

• Consult references/latest-apis.md at 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 #available gating 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 #available gating 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, see references/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 Button for all tappable elements; add accessibility grouping and labels
• Gate version-specific APIs with #available and 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.

1. 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
   

2. Pick a supported template for the target and installed Xcode. List devices/templates, then verify the recorded schemas rather than inferring lane availability from device kind. SwiftUI lanes may be absent on Simulator configurations; use Time Profiler or another supported configuration when appropriate. Missing lanes remain unknown/unavailable. Full guidance: references/trace-recording.md.

3. 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:

   python3 "${SKILL_DIR}/scripts/record_trace.py" \
       --device "<name|udid>" --attach "<AppName>" \
       --stop-file "$TRACE_RUN_DIR/stop" --output ~/Desktop/session.trace
   

Create TRACE_RUN_DIR with mktemp -d before the background example and retain its exact private path for the stop call. For interactive sessions, just tell the user to press Ctrl+C when done.

4. Signal stop — when the user says they've finished exercising the app, touch "$TRACE_RUN_DIR/stop". The script cleanly SIGINTs xctrace and waits up to 60s for finalisation.

5. 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:

1. 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.

2. Resolve a window (only if the user scoped). The parser exposes two discovery modes:

   # 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"
   

Both modes accept --window START_MS:END_MS to scope discovery. Pick the time_ms (for logs) or start_ms/end_ms (for signposts) that match the user's description. Build a window like --window 10400:11700.

3. 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]
   

4. Interpret with references/trace-analysis.md — key diagnostics:

• main_running_coverage_pct is a sampling heuristic assuming 1ms samples; low or high coverage alone does not prove blocking or CPU saturation.
• swiftui-causes.top_sources reveals *why* updates keep happening — high-edge-count sources like UserDefaultObserver.send() or wide EnvironmentWriter entries are investigation candidates, not proof of a bug or feedback loop. Confirm repeated writes and causality in the app before changing architecture.

5. When a specific view shows as expensive, ask who's invalidating it. Use --fanin-for "<view name>" to get the ranked list of source nodes driving the updates.

6. Optionally ground in source. If the user pointed at a file, read it and match view names / user-code symbols against identifiers there. If not, recommend which files to open based on the view names SwiftUI reported.

7. Return a prioritised plan. Cite evidence (coverage %, hot symbol, overlapping view, log timestamp, cause-graph edges) and route each recommendation to a Topic Router reference.

8. Only edit code if the user asked for edits.

Topic Router

Consult the reference file for each topic relevant to the current task:

| Topic | Reference |

|-------|-----------|

| State management | references/state-management.md |

| View composition | references/view-structure.md |

| Performance | references/performance-patterns.md |

| Lists and ForEach | references/list-patterns.md |

| Layout | references/layout-best-practices.md |

| Sheets and navigation | references/sheet-navigation-patterns.md |

| ScrollView | references/scroll-patterns.md |

| Focus management | references/focus-patterns.md |

| Animations (basics) | references/animation-basics.md |

| Animations (transitions) | references/animation-transitions.md |

| Animations (advanced) | references/animation-advanced.md |

| Accessibility | references/accessibility-patterns.md |

| Swift Charts | references/charts.md |

| Charts accessibility | references/charts-accessibility.md |

| Image optimization | references/image-optimization.md |

| Liquid Glass (iOS 26+) | references/liquid-glass.md |

| macOS scenes | references/macos-scenes.md |

| macOS window styling | references/macos-window-styling.md |

| macOS views | references/macos-views.md |

| Text patterns | references/text-patterns.md |

| Localization | references/localization.md |

| Deprecated API lookup | references/latest-apis.md |

| Handling soft-deprecated APIs | references/soft-deprecation.md |

| Previews | references/previews.md |

| Instruments trace analysis | references/trace-analysis.md |

| Instruments trace recording | references/trace-recording.md |

Correctness Checklist

These are review prompts. Distinguish correctness defects from measured performance risks and team preferences; context can justify exceptions:

• [ ] @State properties are private
• [ ] @Binding only where a child modifies parent state
• [ ] Read-through inputs are not stored as @State or @StateObject; explicit owned drafts may legitimately initialize from a passed value
• [ ] @StateObject for view-owned objects; @ObservedObject for injected
• [ ] iOS 17+: @State with @Observable; @Bindable for injected observables needing bindings
• [ ] ForEach uses identity appropriate to the collection; avoid positional IDs for insertable/reorderable model items
• [ ] Constant number of views per ForEach element; List rows are unary
• [ ] Review frequently recreated environment action closures for unnecessary inval

… (full content is in the download package)