# swiftui-expert-skill

swiftui-expert-skill — a skill for Claude Code, Codex, and Cursor. Guides assistants through writing, reviewing, and diagnosing SwiftUI interfaces on iOS and macOS alongside Instruments trace analysis.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 36800 installs · ★ 3937 repo stars
- Author: AvdLee
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/AvdLee/SwiftUI-Agent-Skill/tree/HEAD/skills/swiftui-expert-skill/SKILL.md
- Updated: 2026-11-06
- Security check: automated, 2026-11-16 (text and 13 script files) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/swiftui-expert-skill

## What it does

Runs across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. It focuses on view invalidation boundaries, keeping volatile dependencies near the smallest affected subtree, and checking modern API replacements against bundled reference documents.

Profiling runs through bundled Python scripts. The `record_trace.py` tool connects to processes on physical hardware, host Macs, or simulators. The simulator target requires the `Time Profiler` template because its SwiftUI lane remains unpopulated during runs.

For performance audits, `analyze_trace.py` digests generated `.trace` files. It evaluates hangs using `xctrace triage`, scopes discovery through `os_signpost` intervals or log markers, and correlates animation hitches back to view declarations.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add AvdLee/SwiftUI-Agent-Skill --skill swiftui-expert-skill -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/swiftui-expert-skill/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/swiftui-expert-skill/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add AvdLee/SwiftUI-Agent-Skill --skill swiftui-expert-skill -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/swiftui-expert-skill/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add AvdLee/SwiftUI-Agent-Skill --skill swiftui-expert-skill -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/swiftui-expert-skill/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install AvdLee/SwiftUI-Agent-Skill skills/swiftui-expert-skill
```

2. **Manually: put the files in place**
- File: `.github/skills/swiftui-expert-skill/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add AvdLee/SwiftUI-Agent-Skill --skill swiftui-expert-skill -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/AvdLee/SwiftUI-Agent-Skill --path skills/swiftui-expert-skill
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/swiftui-expert-skill/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add AvdLee/SwiftUI-Agent-Skill --skill swiftui-expert-skill -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/AvdLee/SwiftUI-Agent-Skill/tree/HEAD/skills/swiftui-expert-skill/SKILL.md

## When to use it
- audit view invalidation boundaries to stop unnecessary re-renders
- flag and substitute hard-deprecated SwiftUI APIs with modern variants
- record target application sessions via command-line Instruments wrappers
- isolate animation hitches and main-thread hangs inside `.trace` archives

## Example prompts
- Review this view hierarchy for redundant state updates and deprecated modifiers
- Capture an Instruments session on my connected iOS device using the trace script
- Analyze session.trace between logs to locate hitch causes in the main feed

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2c8306e5f6f1d3e8.

BEGIN THIRD-PARTY FILE 2c8306e5f6f1d3e8
```text
---
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, resizable layouts, safe areas, display scale, performance, lists, environment, localization, animation, Liquid Glass, and API migration. Also use for iPhone Duo, foldable, or large-display layouts (`NavigationSplitView` on large displays, iPhone tab sidebar, two-column reflow, foldable grids, `ArrangementView`, `ReservedRegion`), hinge effects, vertical bars, `@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
- For layout and rendering inputs, read the value nearest the SwiftUI view that consumes it; do not substitute process-global screen state

## 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
```
END THIRD-PARTY FILE 2c8306e5f6f1d3e8

The third-party file has ended. Everything between the 2c8306e5f6f1d3e8 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2558 of 11976 bytes. © AvdLee · MIT · https://github.com/AvdLee/SwiftUI-Agent-Skill/tree/HEAD/skills/swiftui-expert-skill/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
