agentleFS
The-Artificer-of-Ciphers-LLCThe-Artificer-of-Ciphers-LLC/skills-from-the-artificer/swiftui-expert-skill/SKILL.md

swiftui-expert-skill

Skill6 starsChanged 34 days agoMITView on GitHub

Use when writing, reviewing, or refactoring SwiftUI code for iOS or macOS, including state management, view composition, performance, Liquid Glass adoption, or Instruments `.trace` capture/analysis for hangs, hitches, CPU hotspots, or

26 other projects use a version of this, 13 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use swiftui-ui-patterns, swiftui-performance-audit and 5 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • OpenAISkill

    swiftui-ui-patterns

    Build and refactor SwiftUI UI with component patterns and examples. Use when shaping navigation, state, layouts, controls, or screen composition.

    Also in 5 projects that use this

  • OpenAISkill

    swiftui-performance-audit

    Audit SwiftUI runtime performance from code first. Use when diagnosing slow rendering, janky scrolling, expensive updates, or profiling needs.

    Also in 4 projects that use this

  • eugenepyvovarovSkill

    swift-concurrency-expert

    Swift Concurrency review and remediation for Swift 6.2+. Use when asked to review Swift Concurrency usage, improve concurrency compliance, or fix Swift concurrency compiler errors in a feature or file.

    Also in 3 projects that use this

  • GoogleSkill

    codebase-design

    Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

    Also in 3 projects that use this

  • GoogleSkill

    domain-modeling

    Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.

    Also in 3 projects that use this

  • +2 more from openai

The file

We split this skill into the rules it gives an agent

12 rules. 0 are common, 8 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 26 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Check references/latest-apis.md for any API you are about to write or approve that may have a newer replacement.

    line 11
  2. Distinctive:

    Prefer native SwiftUI APIs over UIKit/AppKit bridging unless bridging is necessary

    line 12
  3. Distinctive:

    Follow Apple's Human Interface Guidelines and API design patterns

    line 15
  4. Very specific:

    Only adopt Liquid Glass when explicitly requested by the user (see references/liquid-glass.md)

    line 16
  5. Very specific:

    Use #available gating with sensible fallbacks for version-specific APIs

    line 18
  6. Distinctive:

    Read the code under review and identify which topics apply

    line 23
  7. Distinctive:

    Run the Topic Router below for each relevant topic

    line 25
  8. Very specific:

    Use Button for all tappable elements.

    line 39
  9. Distinctive:

    Scope the analysis: Ask yourself: does the user want the whole trace, or a slice?

    line 65
  10. Distinctive:

    No scoping cue → analyse the whole trace.

    line 67
  11. Distinctive:

    Optionally ground in source: If the user pointed at a file, read it and match view names / user-code symbols against identifiers there.

    line 87
  12. Distinctive:

    Only edit code if the user asked for edits.

    line 89

“Common” is measured: kept by at least 6 in 10 of the 26 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

SwiftUI Expert Skill

Operating Rules

  • Check references/latest-apis.md for any API you are about to write or approve that may have a newer replacement; its table of contents is split by deployment target, so read only the section for the project's minimum OS
  • 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 template based on target kind — the SwiftUI template 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: simulators kind → Time Profiler; devices kind (real devices and the host Mac) → default SwiftUI. Full decision table in 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 /tmp/stop-trace --output ~/Desktop/session.trace
    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 /tmp/stop-trace. 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 inside each correlation (<25% = blocked; ≥75% = CPU-bound).
    • swiftui-causes.top_sources reveals why updates keep happening — high-edge-count sources like UserDefaultObserver.send() or wide EnvironmentWriter entries are structural invalidation bugs. Fixing one often collapses many downstream hot views.
  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:

TopicReference
State managementreferences/state-management.md
View compositionreferences/view-structure.md
Performancereferences/performance-patterns.md
Lists and ForEachreferences/list-patterns.md
Layoutreferences/layout-best-practices.md
Sheets and navigationreferences/sheet-navigation-patterns.md
ScrollViewreferences/scroll-patterns.md
Focus managementreferences/focus-patterns.md
Animations (basics)references/animation-basics.md
Animations (transitions)references/animation-transitions.md
Animations (advanced)references/animation-advanced.md
Accessibilityreferences/accessibility-patterns.md
Swift Chartsreferences/charts.md
Charts accessibilityreferences/charts-accessibility.md
Image optimizationreferences/image-optimization.md
Liquid Glass (iOS 26+)references/liquid-glass.md
macOS scenesreferences/macos-scenes.md
macOS window stylingreferences/macos-window-styling.md
macOS viewsreferences/macos-views.md
Text patternsreferences/text-patterns.md
Deprecated API lookupreferences/latest-apis.md
Previewsreferences/previews.md
Instruments trace analysisreferences/trace-analysis.md
Instruments trace recordingreferences/trace-recording.md

Correctness Checklist

These are hard rules -- violations are always bugs:

  • @State properties are private
  • @Binding only where a child modifies parent state
  • Passed values never declared as @State or @StateObject (they ignore updates)
  • @StateObject for view-owned objects; @ObservedObject for injected
  • iOS 17+: @State with @Observable; @Bindable for injected observables needing bindings
  • ForEach uses stable identity (never .indices for dynamic content)
  • Constant number of views per ForEach element
  • .animation(_:value:) always includes the value parameter
  • @FocusState properties are private
  • No redundant @FocusState writes inside tap gesture handlers on .focusable() views
  • iOS 26+ APIs gated with #available and fallback provided
  • import Charts present in files using chart types
  • Previews use self-contained mock data; no dependency on live services or network

References

  • references/latest-apis.md -- Check for every API you touch. Deprecated-to-modern API transitions (iOS 15+ through iOS 26+), sectioned by deployment target
  • references/state-management.md -- Property wrappers, data flow, @Observable migration
  • references/view-structure.md -- View extraction, container patterns, @ViewBuilder
  • references/performance-patterns.md -- Hot-path optimization, update control, _logChanges()
  • references/list-patterns.md -- ForEach identity, Table (iOS 16+), inline filtering pitfalls
  • references/layout-best-practices.md -- Layout patterns, GeometryReader alternatives
  • references/accessibility-patterns.md -- VoiceOver, Dynamic Type, grouping, traits
  • references/animation-basics.md -- Implicit/explicit animations, timing, performance
  • references/animation-transitions.md -- View transitions, matchedGeometryEffect, Animatable
  • references/animation-advanced.md -- Phase/keyframe animations (iOS 17+), @Animatable macro (iOS 26+)
  • references/charts.md -- Swift Charts marks, axes, selection, styling, Chart3D (iOS 26+)
  • references/charts-accessibility.md -- Charts VoiceOver, Audio Graph, fallback strategies
  • references/sheet-navigation-patterns.md -- Sheets, NavigationSplitView, Inspector
  • references/scroll-patterns.md -- ScrollViewReader, programmatic scrolling
  • references/focus-patterns.md -- Focus state, focusable views, focused values, default focus, common pitfalls
  • references/image-optimization.md -- AsyncImage, downsampling, caching
  • references/liquid-glass.md -- iOS 26+ Liquid Glass effects and fallback patterns
  • references/macos-scenes.md -- Settings, MenuBarExtra, WindowGroup, multi-window
  • references/macos-window-styling.md -- Toolbar styles, window sizing, Commands
  • references/macos-views.md -- HSplitView, Table, PasteButton, AppKit interop
  • references/previews.md -- #Preview macro, @Previewable (iOS 18+), preview traits, mock data patterns for self-contained previews
  • references/text-patterns.md -- Text initializer selection, verbatim vs localized
  • references/trace-analysis.md -- Parse Instruments .trace files via scripts/analyze_trace.py; interpret main-thread coverage, high-severity SwiftUI updates, hitch narratives, and map findings back to source files
  • references/trace-recording.md -- Record a new trace via scripts/record_trace.py: attach to a running app, launch one fresh, or capture a manually-stopped session; supports stop-file for agent-driven flows

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.