# update-swiftui-apis

Adopt this skill: https://proskills.md/skills/other/avdlee-swiftui-agent-skill-agents-skills-update-swiftui-apis

Page: https://proskills.md/skills/other/avdlee-swiftui-agent-skill-agents-skills-update-swiftui-apis
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/update-swiftui-apis/SKILL.md
size: 4616
sha: 871d82cfd435db99d7b47ad7e5c656e9cbf63e58
upstream: https://github.com/avdlee/swiftui-agent-skill/blob/main/.agents/skills/update-swiftui-apis/SKILL.md

````text
---
name: update-swiftui-apis
description: Scan Apple's SwiftUI documentation for deprecated APIs and update the SwiftUI Expert Skill with modern replacements. Use when asked to "update latest APIs", "refresh deprecated SwiftUI APIs", "check for new SwiftUI deprecations", "scan for API changes", or after a new iOS/Xcode release. Requires the Sosumi MCP to be available.
---

# Update SwiftUI APIs

Systematically scan Apple's developer documentation via the Sosumi MCP, identify deprecated SwiftUI APIs and their modern replacements, and update `skills/swiftui-expert-skill/references/latest-apis.md`.

## Prerequisites

- **Sosumi MCP** must be enabled and available (provides `searchAppleDocumentation`, `fetchAppleDocumentation`, `fetchAppleVideoTranscript`, `fetchExternalDocumentation`)
- Write access to this repository (or a fork)

## Workflow

### 1. Understand current coverage

Read `skills/swiftui-expert-skill/references/latest-apis.md` to understand:
- Which deprecated-to-modern transitions are already documented
- The version segments in use (iOS 15+, 16+, 17+, 18+, 26+)
- The Quick Lookup Table at the bottom

### 2. Load the scan manifest

Read `references/scan-manifest.md` (relative to this skill). It contains the categorized list of API areas, documentation paths, search queries, and WWDC video paths to scan.

### 3. Scan Apple documentation

For each category in the manifest:

1. Call `searchAppleDocumentation` with the listed queries to discover relevant pages.
2. Call `fetchAppleDocumentation` with specific documentation paths to get full API details.
3. Look for deprecation notices, "Deprecated" labels, and "Use ... instead" guidance.
4. Note the iOS version where the modern replacement became available.
5. Optionally call `fetchAppleVideoTranscript` for WWDC sessions that announce API changes.

Batch related searches together for efficiency. Focus on finding **new** deprecations not yet in `latest-apis.md`.

### 4. Compare and identify changes

Compare findings against existing entries. Categorize results:
- **New deprecations**: APIs not yet documented in `latest-apis.md`
- **Corrections**: Existing entries that need updating (wrong version, better replacement available)
- **New version segments**: If a new iOS version introduces deprecations, add a new section

### 5. Update latest-apis.md

Follow the established format exactly. Each entry must include:

**Section placement** -- place under the correct version segment:
- "Always Use (iOS 15+)" for long-deprecated APIs
- "When Targeting iOS 16+" / "17+" / "18+" / "26+" for version-gated changes

**Entry format:**

```markdown
**Always use `modernAPI()` instead of `deprecatedAPI()`.**

\```swift
// Modern
View()
    .modernAPI()

// Deprecated
View()
    .deprecatedAPI()
\```
```

**Quick Lookup Table** -- add a row at the bottom of the file:

```markdown
| `deprecatedAPI()` | `modernAPI()` | iOS XX+ |
```

Keep the attribution line at the top of the file:
> Based on a comparison of Apple's documentation using the Sosumi MCP, we found the latest recommended APIs to use.

### 6. Open a pull request

1. Create a branch from `main` named `update/latest-apis-YYYY-MM` (use current year and month).
2. Commit changes to `skills/swiftui-expert-skill/references/latest-apis.md`.
3. Open a PR via `gh pr create` with:
   - **Title**: "Update latest SwiftUI APIs (Month Year)"
   - **Body**: Summary of new/changed entries, attribution to Sosumi MCP

## Sosumi MCP Tool Reference

| Tool | Parameters | Returns |
|------|-----------|---------|
| `searchAppleDocumentation` | `query` (string) | JSON with `results[]` containing `title`, `url`, `description`, `breadcrumbs`, `tags`, `type` |
| `fetchAppleDocumentation` | `path` (string, e.g. `/documentation/swiftui/view/foregroundstyle(_:)`) | Markdown documentation content |
| `fetchAppleVideoTranscript` | `path` (string, e.g. `/videos/play/wwdc2025/10133`) | Markdown transcript |
| `fetchExternalDocumentation` | `url` (string, full https URL) | Markdown documentation content |

## Tips

- Start broad with `searchAppleDocumentation` queries, then drill into specific paths with `fetchAppleDocumentation`.
- Apple's deprecation docs typically say "Deprecated" in the page and link to the replacement.
- WWDC "What's new in SwiftUI" sessions are the best source for newly introduced replacements.
- When unsure about the exact iOS version for a deprecation, verify by checking the "Availability" section in the fetched documentation.
- If an API is deprecated but no direct replacement exists, note this rather than suggesting an incorrect alternative.
````

## File: .agents/skills/update-swiftui-apis/references/scan-manifest.md
size: 6121
sha: 4271c1ef31cff963e96765128aa310695d3a904f
upstream: https://github.com/avdlee/swiftui-agent-skill/blob/main/.agents/skills/update-swiftui-apis/references/scan-manifest.md

```text
# SwiftUI API Scan Manifest

Categorized list of API areas to scan via the Sosumi MCP. For each category: search queries to run, documentation paths to fetch, and WWDC sessions to check.

Add new categories or paths as Apple introduces new APIs.

---

## Navigation

**Search queries:**
- `SwiftUI NavigationStack`
- `SwiftUI NavigationSplitView`
- `SwiftUI navigationTitle`
- `SwiftUI toolbar`
- `SwiftUI NavigationLink deprecated`

**Documentation paths:**
- `/documentation/swiftui/navigationstack`
- `/documentation/swiftui/navigationsplitview`
- `/documentation/swiftui/navigationlink`
- `/documentation/swiftui/view/navigationtitle(_:)-avgj`
- `/documentation/swiftui/view/toolbar(content:)-5w0tj`
- `/documentation/swiftui/view/toolbarvisibility(_:for:)`

---

## Appearance & Styling

**Search queries:**
- `SwiftUI foregroundStyle`
- `SwiftUI foregroundColor deprecated`
- `SwiftUI tint modifier`
- `SwiftUI preferredColorScheme`
- `SwiftUI clipShape`

**Documentation paths:**
- `/documentation/swiftui/view/foregroundstyle(_:)`
- `/documentation/swiftui/view/foregroundcolor(_:)`
- `/documentation/swiftui/view/tint(_:)-93mfq`
- `/documentation/swiftui/view/preferredcolorscheme(_:)`
- `/documentation/swiftui/view/clipshape(_:style:)`

---

## State Management

**Search queries:**
- `SwiftUI Observable macro`
- `SwiftUI ObservableObject deprecated`
- `SwiftUI Bindable`
- `SwiftUI State`
- `SwiftUI Entry macro`

**Documentation paths:**
- `/documentation/observation/observable()`
- `/documentation/swiftui/observableobject`
- `/documentation/swiftui/bindable`
- `/documentation/swiftui/state`
- `/documentation/swiftui/entry()`
- `/documentation/swiftui/environmentvalues`

---

## Presentation & Alerts

**Search queries:**
- `SwiftUI alert modifier`
- `SwiftUI confirmationDialog`
- `SwiftUI actionSheet deprecated`
- `SwiftUI sheet modifier`
- `SwiftUI fullScreenCover`

**Documentation paths:**
- `/documentation/swiftui/view/alert(_:ispresented:actions:message:)-8dvt8`
- `/documentation/swiftui/view/confirmationdialog(_:ispresented:titlevisibility:actions:message:)-43f72`
- `/documentation/swiftui/view/sheet(ispresented:ondismiss:content:)`

---

## Text Input

**Search queries:**
- `SwiftUI TextField onSubmit`
- `SwiftUI textInputAutocapitalization`
- `SwiftUI autocorrectionDisabled`
- `SwiftUI focused modifier`

**Documentation paths:**
- `/documentation/swiftui/view/onsubmit(of:_:)`
- `/documentation/swiftui/view/textinputautocapitalization(_:)`
- `/documentation/swiftui/view/autocorrectiondisabled(_:)`
- `/documentation/swiftui/focusstate`

---

## Layout

**Search queries:**
- `SwiftUI ignoresSafeArea`
- `SwiftUI containerRelativeFrame`
- `SwiftUI visualEffect`
- `SwiftUI GeometryReader`
- `SwiftUI coordinateSpace`

**Documentation paths:**
- `/documentation/swiftui/view/ignoressafearea(_:edges:)`
- `/documentation/swiftui/view/containerrelativeframe(_:alignment:_:)`
- `/documentation/swiftui/view/visualeffect(_:)`
- `/documentation/swiftui/geometryreader`
- `/documentation/swiftui/view/coordinatespace(_:)`

---

## Gestures

**Search queries:**
- `SwiftUI MagnifyGesture`
- `SwiftUI RotateGesture`
- `SwiftUI MagnificationGesture deprecated`
- `SwiftUI RotationGesture deprecated`

**Documentation paths:**
- `/documentation/swiftui/magnifygesture`
- `/documentation/swiftui/rotategesture`
- `/documentation/swiftui/magnificationgesture`
- `/documentation/swiftui/rotationgesture`

---

## Accessibility

**Search queries:**
- `SwiftUI accessibilityLabel`
- `SwiftUI accessibility deprecated`
- `SwiftUI accessibilityRepresentation`

**Documentation paths:**
- `/documentation/swiftui/view/accessibilitylabel(_:)-1d7jv`
- `/documentation/swiftui/view/accessibilityvalue(_:)-7a2ql`
- `/documentation/swiftui/view/accessibilityhint(_:)`
- `/documentation/swiftui/view/accessibilityrepresentation(representation:)`

---

## Animations

**Search queries:**
- `SwiftUI animation value deprecated`
- `SwiftUI withAnimation`
- `SwiftUI phaseAnimator`
- `SwiftUI keyframeAnimator`

**Documentation paths:**
- `/documentation/swiftui/view/animation(_:value:)`
- `/documentation/swiftui/view/phaseanimator(_:content:animation:)`
- `/documentation/swiftui/view/keyframeanimator(initialvalue:repeating:content:keyframes:)`

---

## Tabs

**Search queries:**
- `SwiftUI Tab API`
- `SwiftUI tabItem deprecated`
- `SwiftUI TabView`

**Documentation paths:**
- `/documentation/swiftui/tab`
- `/documentation/swiftui/tabview`
- `/documentation/swiftui/view/tabitem(_:)`

---

## Previews

**Search queries:**
- `SwiftUI Previewable`
- `SwiftUI Preview macro`

**Documentation paths:**
- `/documentation/swiftui/previewable()`
- `/documentation/swiftui/preview(_:body:)`

---

## Liquid Glass (iOS 26+)

**Search queries:**
- `SwiftUI glassEffect`
- `SwiftUI GlassEffectContainer`
- `SwiftUI glassProminent`
- `SwiftUI backgroundExtensionEffect`

**Documentation paths:**
- `/documentation/swiftui/view/glasseffect(_:in:isenabled:)`
- `/documentation/swiftui/glasseffectcontainer`
- `/documentation/swiftui/view/backgroundextensioneffect()`
- `/documentation/swiftui/view/scrolledgeeffectstyle(_:for:)`
- `/documentation/swiftui/view/tabbarminimizebehavior(_:)`

---

## Scroll & Lists

**Search queries:**
- `SwiftUI ScrollViewReader`
- `SwiftUI scrollPosition`
- `SwiftUI scrollTargetBehavior`
- `SwiftUI ForEach`

**Documentation paths:**
- `/documentation/swiftui/scrollviewreader`
- `/documentation/swiftui/view/scrollposition(id:)`
- `/documentation/swiftui/view/scrolltargetbehavior(_:)`
- `/documentation/swiftui/foreach`

---

## WWDC Sessions

Key "What's new in SwiftUI" sessions to check for API announcements:

- `/videos/play/wwdc2026/269` - What's new in SwiftUI (WWDC26)
- `/videos/play/wwdc2024/10144` - What's new in SwiftUI (WWDC24)
- `/videos/play/wwdc2024/10145` - SwiftUI essentials (WWDC24)
- `/videos/play/wwdc2025/232` - What's new in SwiftUI (WWDC25)
- `/videos/play/wwdc2023/10148` - What's new in SwiftUI (WWDC23)
- `/videos/play/wwdc2022/10052` - What's new in SwiftUI (WWDC22)

When a new WWDC occurs, add the latest "What's new in SwiftUI" session path here.
```

## File: README.md
upstream: https://github.com/avdlee/swiftui-agent-skill/blob/main/README.md

````text
# SwiftUI Expert Skill
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/AvdLee/SwiftUI-Agent-Skill/blob/main/LICENSE)
[![Weekly Installs](https://img.shields.io/badge/weekly%20installs-31.4k-brightgreen)](https://skills.sh/avdlee/swiftui-agent-skill/swiftui-expert-skill)
[![GitHub Release](https://img.shields.io/github/v/release/AvdLee/SwiftUI-Agent-Skill)](https://github.com/AvdLee/SwiftUI-Agent-Skill/releases)
[![GitHub Stars](https://img.shields.io/github/stars/AvdLee/SwiftUI-Agent-Skill?style=flat)](https://github.com/AvdLee/SwiftUI-Agent-Skill/stargazers)

Expert guidance for any AI coding tool that supports the [Agent Skills open format](https://agentskills.io/home) — SwiftUI state management, view composition, performance, SDK 27 changes, and Liquid Glass adoption.

This repository distills practical SwiftUI best practices into actionable, concise references for agents and code review workflows.

This repository is packaged as a portable [Agent Plugin](https://agent-plugins.org) (spec 1.0.0): compatible clients discover the skill automatically from the root `plugin.json` manifest and the `skills/` directory. Client-specific manifests for Claude Code, Cursor, Codex, and pi are included as well.

## Who this is for
- Teams adopting modern SwiftUI APIs who want quick, correct defaults
- Developers reviewing or refactoring SwiftUI views and data flow
- Anyone shipping performant lists, scrolling, sheets, and navigation in SwiftUI

## See also my other skills:
- [Swift Concurrency Expert](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill)
- [Core Data Expert](https://github.com/AvdLee/Core-Data-Agent-Skill)
- [Swift Testing Expert](https://github.com/AvdLee/Swift-Testing-Agent-Skill)
- [Xcode Build Optimization Agent Skill](https://github.com/AvdLee/Xcode-Build-Optimization-Agent-Skill)
- [Xcode Simulator AI Control Agent Skill](https://www.rocketsim.app/docs/features/agentic-development/agent-skill/)

## How to Use This Skill

### Option A: Using skills.sh (recommended)
Install this skill with a single command:

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

For more information, [visit the skills.sh platform page](https://skills.sh/avdlee/swiftui-agent-skill/swiftui-expert-skill).

Installed before the Agent Plugins migration? Run `npx skills@latest update` using skills CLI 1.5.24 or newer. It migrates the saved skill path without treating the skill as deleted.

Then use the skill in your AI agent, for example:
> Use the swiftui expert skill and review the current SwiftUI code for state-management and performance improvements

### Option B: ChatGPT & Codex (OpenAI Plugins Directory)

This plugin is distributed through the universal OpenAI Plugins Directory shared by ChatGPT and Codex:

1. In the ChatGPT desktop app, select **Codex** (or ChatGPT with **Work** enabled), or use the plugin browser in Codex CLI.
2. Open **Plugins** and search for "SwiftUI Expert".
3. Install the plugin. The skill becomes available in new chats and sessions.

### Option C: Claude Code Plugin

#### Personal Usage
To install this Skill for your personal use in Claude Code:

1. Add the marketplace:

```bash
/plugin marketplace add AvdLee/SwiftUI-Agent-Skill
```

2. Install the Skill:

```bash
/plugin install swiftui-expert@swiftui-expert-skill
```

#### Project Configuration
To automatically provide this Skill to everyone working in a repository, configure the repository's `.claude/settings.json`:

```json
{
  "enabledPlugins": {
    "swiftui-expert@swiftui-expert-skill": true
  },
  "extraKnownMarketplaces": {
    "swiftui-expert-skill": {
      "source": {
        "source": "github",
        "repo": "AvdLee/SwiftUI-Agent-Skill"
      }
    }
  }
}
```

When team members open the project, Claude Code will prompt them to install the Skill.

### Option D: Cursor Plugin

Load the plugin from a local clone by placing it in `~/.cursor/plugins/local`, or install it from the Cursor Marketplace once listed. Cursor supports both the portable Agent Plugins manifest (`plugin.json`) and the Cursor Plugin manifest (`.cursor-plugin/plugin.json`) included in this repository.

### Using another tool?

See [INSTALLATION.md](INSTALLATION.md) for all other installation options: pi, Gemini CLI, Autohand Code, and manual installation.

**How to verify**:

Your agent should reference the workflow/checklists in `skills/swiftui-expert-skill/SKILL.md` and jump into the relevant reference file for your task.

## What's Inside

This skill covers the full surface of SwiftUI development -- from state management and view composition to Swift Charts, macOS multi-window scenes, animations, SDK 27 changes, and Liquid Glass -- without bloating your agent's task context. Reference files load on demand, so your agent gets deep guidance only for the topic at hand.

- **State management** -- property wrapper selection, `@Observable`, data flow patterns
- **Environment** -- `@Entry`, stable defaults, and invalidation-aware propagation
- **View composition** -- extraction patterns, container views, identity stability
- **Modifiers** -- conditional identity, no-effect values, and `AnyShapeStyle`
- **Performance** -- hot-path optimization, lazy loading, `@Observable` granularity
- **Lists & ForEach** -- stable identity, Table, inline filtering pitfalls
- **Navigation & sheets** -- NavigationStack, NavigationSplitView, Inspector, enum-based sheets
- **Swift Charts** -- marks, axes, selection, styling, accessibility, Chart3D
- **Animations** -- implicit/explicit, transitions, phase/keyframe, `@Animatable` macro
- **macOS** -- scenes, window styling, Table, HSplitView, AppKit interop
- **Liquid Glass** -- iOS 26+ glass effects, containers, fallback patterns
- **SDK 27** -- `@State` and `@ContentBuilder` migrations, reordering, AsyncImage caching, swipe actions, dialogs, and toolbars
- **Accessibility** -- VoiceOver, Dynamic Type, grouping, traits
- **Image optimization** -- AsyncImage, downsampling, caching
- **Latest APIs** -- deprecated-to-modern migration guide (iOS 15+ through iOS 27+)
- **Instruments trace recording & analysis** -- bundled `xctrace` toolchain for diagnosing hangs, hitches, and expensive SwiftUI view updates (see below)

Non-opinionated: focuses on correctness and performance, not architecture or code style.

## Recording & Analysing Instruments Traces

Unlike the other reference files — which are text guidance — this part of the skill ships an executable Python toolchain that wraps `xctrace`. It lets the agent **record** a new `.trace` and **analyse** an existing one end-to-end: the parser reads the Time Profiler, Hangs, Animation Hitches, SwiftUI updates, and SwiftUI cause-graph lanes, correlates hangs/hitches with main-thread samples, and emits JSON + markdown so the agent can reason over structured data instead of the raw `xctrace export` firehose.

**When it triggers:**

- A `.trace` path appears in the prompt (analysis).
- The user asks to record, profile, or capture a session (recording).

**What the agent can then ask:**

```text
Analyse ~/Desktop/MyApp.trace and tell me what's wrong.

Focus analysis on what happens right after the 'feed loaded' log.

Which of my SwiftUI views is responsible for the hang around 6s?

Record a new trace: attach to MyApp on my iPhone — I'll tell you when I'm done.
```

**Under the hood:**

- `scripts/record_trace.py` — wraps `xctrace record`. Supports attach / launch / all-processes, stop-file for agent-driven sessions, time-limits, JSON device & template discovery.
- `scripts/analyze_trace.py` — runs the five-lane analysis. Discovery modes `--list-logs`, `--list-signposts`, `--fanin-for` let the agent scope to a time window or trace a specific view back to its invalidation sources. `--window START_MS:END_MS` restricts every lane to a slice.
- `scripts/instruments_parser/` — one module per lane (`time_profiler`, `hangs`, `hitches`, `swiftui`, `cau
````
