SwiftUI Expert Skill

Install

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

This is third-party code. Review the repository files before installing.

What it does

The skill gives the agent vetted rules for writing and reviewing SwiftUI code on iOS and macOS. It guides property wrapper and @Observable choice, invalidation-aware view extraction, stable list identity, navigation, sheets, Swift Charts, animations, accessibility and macOS windows. A latest-APIs reference maps deprecated calls to modern ones up to SDK 27, and Liquid Glass is adopted only on request. It also ships Python scripts over xctrace that record and analyze Instruments traces and tie hangs and hitches to specific views.

Who it is for. For iOS and macOS developers building SwiftUI interfaces with an agent.

Example request

Use the swiftui expert skill and review the current views for state and performance issues

Limitations

The skill does not enforce architecture or code style. Trace recording and analysis work only on macOS with Xcode installed. The latest-APIs reference needs updating after Apple releases.

How to disable. Remove the swiftui-expert plugin via /plugin or run npx skills remove swiftui-expert-skill.

Security check

• Mostly instructions and references
• Trace analysis scripts run xctrace locally

README in short

The README lists the audience and topics, from state and navigation to Swift Charts and SDK 27. Install via skills.sh, the OpenAI plugins directory for Codex, the Claude Code marketplace with project-level setup, or the Cursor plugin. It details the Instruments trace recording and analysis scripts, shows the reference layout and credits the sources behind the rules. MIT licensed.

SKILL.md

---
name: swiftui-expert-skill
description: Use when writing, reviewing, or refactoring SwiftUI code for iOS or macOS, including state and `@Observable` data flow, view composition, performance, lists, environment, localization, animation, Liquid Glass, and API migration. Also use for `@State` initialization or synthesized-property diagnostics, `@ContentBuilder` ambiguity, `reorderable` drag/drop, custom `AsyncImage` `URLSession`, swipe actions outside List, item-bound `alert`/`confirmationDialog`, `ToolbarOverflowMenu`, `AnimatableValues`, Document APIs (`Document`/`DocumentReader`), and Instruments `.trace` capture or analysis.
---

# SwiftUI Expert Skill

## Operating Rules

- Treat each `View` type as an invalidation boundary: give it only the data it reads and keep frequently changing dependencies close to the smallest affected subtree
- Search `references/latest-apis.md` when writing, reviewing, or migrating API usage; look up only the APIs relevant to the task
- Replace hard-deprecated APIs with modern equivalents. During feature work, flag soft-deprecated APIs and leave them in place (see `references/soft-deprecation.md`)
- 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`); replace hard-deprecated APIs, and flag soft-deprecated APIs without rewriting them unless the user asked to migrate
- Run the Topic Router below for each relevant topic
- Validate `#available` gating and fallback paths for version-specific features

Related