SwiftUI-Agent-Skill README

The project's README from github.com/AvdLee/SwiftUI-Agent-Skill. As one markdown file: README.md.

SwiftUI Expert Skill

License: MIT Weekly Installs GitHub Release GitHub Stars

Expert guidance for any AI coding tool that supports the Agent Skills open format — SwiftUI state management, view composition, performance, and iOS 26+ 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 (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

See also my other skills:

How to Use This Skill

Install this skill with a single command:

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

For more information, visit the skills.sh platform page.

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:
/plugin marketplace add AvdLee/SwiftUI-Agent-Skill
  1. Install the Skill:
/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:

{
  "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 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, and iOS 26+ 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.

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:

What the agent can then ask:

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:

Key diagnostic: main_running_coverage_pct on each hang/hitch correlation. < 25 % → main thread was blocked (I/O, lock, sync await); ≥ 75 % → CPU-bound. This single metric separates two radically different fix paths.

Full guidance: skills/swiftui-expert-skill/references/trace-analysis.md and skills/swiftui-expert-skill/references/trace-recording.md.

Skill Structure

skills/swiftui-expert-skill/
  SKILL.md
  references/
    accessibility-patterns.md - Accessibility traits, grouping, Dynamic Type, and VoiceOver
    animation-advanced.md - Performance, interpolation, and complex animation chains
    animation-basics.md - Core animation concepts, implicit/explicit animations, timing
    animation-transitions.md - View transitions, matchedGeometryEffect, and state changes
    charts-accessibility.md - Charts accessibility, fallback strategies, and WWDC sessions
    charts.md - Swift Charts marks, axes, selection, styling, composition, and Chart3D
    focus-patterns.md
    image-optimization.md - AsyncImage usage, downsampling, caching
    latest-apis.md
    layout-best-practices.md - Layout patterns and GeometryReader alternatives
    liquid-glass.md - iOS 26+ glass effects and fallback patterns
    list-patterns.md - ForEach identity and list performance
    localization.md
    macos-scenes.md - Scene lifecycle, multi-window setups, and menu bar scenes on macOS
    macos-views.md - macOS-specific SwiftUI views and platform differences from iOS
    macos-window-styling.md - Window chrome, toolbar, and title bar styling in SwiftUI
    performance-patterns.md - Hot-path optimizations and update control
    previews.md
    scroll-patterns.md - ScrollViewReader and programmatic scrolling
    sheet-navigation-patterns.md - Sheets and type-safe navigation
    soft-deprecation.md
    state-management.md - Property wrapper selection and data flow
    text-patterns.md
    trace-analysis.md
    trace-recording.md
    view-structure.md - View extraction and composition patterns

Maintenance

The repository includes a maintenance skill for keeping API guidance current:

.agents/skills/update-swiftui-apis/
  SKILL.md               - Workflow for scanning Apple docs and updating latest-apis.md
  references/
    scan-manifest.md     - Categorized API areas, doc paths, and search queries to scan

Use this skill after new iOS or Xcode releases to refresh the deprecated API reference. It requires the Sosumi MCP to be available. See AGENTS.md or CONTRIBUTING.md for details.

Note: only swiftui-expert-skill is intended to be published in the Cursor plugin. The maintenance skill remains a repository workflow utility.

Contributing

Contributions are welcome! This repository follows the Agent Skills open format, which has specific structural requirements.

Please read CONTRIBUTING.md for:

Acknowledgments

Several SwiftUI guidelines in this skill were inspired by or derived from the following works:

About the authors

Created by Antoine van der Lee and Omar Elsayed. With years of experience in Swift & SwiftUI, this skill distills practical knowledge into actionable guidance for AI assistants. Antoine published tens of articles on SwiftUI on his blog called SwiftLee.

Resources

License

This skill is open-source and available under the MIT License. See LICENSE for details.

SwiftUI-Agent-Skill (AvdLee/SwiftUI-Agent-Skill)

Searching Database…

3.7K ·GitHub
SwiftUI-Agent-Skill
Что это такое?Готовый экспертный навык, который даёт ИИ-инструментам для программирования глубокие рекомендации по лучшим практикам SwiftUI — управление состоянием, композиция view, производительность и внедрение iOS 26+ Liquid Glass — в открытом формате Agent Skills.
Так это Swift-библиотека, которую я добавлю в своё приложение, или что-то другое?Ни то ни другое: это переносимый Agent Plugin (спецификация 1.0.0) из markdown-справочников, которые ИИ-агент подгружает по мере необходимости, плюс встроенный набор Python-утилит для анализа трассировок Instruments. Совместимые клиенты находят его автоматически.
Как установить его в мой ИИ-инструмент для программирования?Четыре описанных способа: установка одной командой через skills.sh (рекомендуется), каталог OpenAI Plugins Directory в ChatGPT или Codex (поищите 'SwiftUI Expert'), маркетплейс Claude Code или локальный клон для Cursor. В INSTALLATION.md описаны pi, Gemini CLI и ручная установка.
Какие ИИ-инструменты для программирования реально могут работать с этим навыком?Любой клиент с поддержкой открытого формата Agent Skills: отдельные манифесты поставляются для Claude Code, Cursor, Codex и pi, а INSTALLATION.md добавляет Gemini CLI, Autohand Code и ручную установку.
Всё ли в этом навыке работает на любой машине?Инструменты для Instruments работают только на macOS, потому что xctrace поставляется вместе с Xcode; всё остальное — чистый Python 3 на стандартной библиотеке плюс текстовые рекомендации. Навык намеренно не навязывает opinions — он про корректность и производительность, а не про архитектуру и стиль кода.
Кому это принесёт больше всего пользы?Командам, внедряющим современные API SwiftUI и желающим быстрых и корректных решений по умолчанию, разработчикам, которые ревьюят или рефакторят SwiftUI-views и поток данных, и всем, кто выпускает производительные списки, скроллинг, sheets и навигацию.
Какие темы реально охватывают эти рекомендации?Весь диапазон SwiftUI: выбор property wrapper и состояние на @Observable, композиция view, производительность и ленивую загрузку, идентичность в Lists и ForEach, NavigationStack и sheets на enum, Swift Charts, анимации и макрос @Animatable, сцены macOS, iOS 26+ Liquid Glass, доступность, оптимизацию изображений, а также руководство по миграции с устаревших API на современные от iOS 15+ до iOS 26+.
Не раздует ли все эти рекомендации контекстное окно моего агента?Нет — файлы-справочники подгружаются по мере необходимости, поэтому агент достаёт подробные рекомендации только по теме, с которой работает в данный момент. В README прямо подчёркивается: покрытие всего диапазона SwiftUI без раздувания контекста задач агента.
Что делает встроенные инструменты для Instruments?Они оборачивают xctrace от начала до конца: recordtrace.py записывает новый .trace (подключение к процессу, запуск или все процессы, лимиты времени, файл остановки по сигналу агента), а analyzetrace.py разбирает дорожки Time Profiler, Hangs, Animation Hitches, обновления SwiftUI и cause-graph в JSON и markdown. Ключевая метрика, mainrunningcoveragepct, отличает заблокированный главный поток (<25%) от загруженного процессором (≥75%).
Как навык не отстаёт от новых релизов iOS?В репозитории есть maintenance-навык, который обновляет справочник устаревших API после каждого нового релиза iOS или Xcode; ему требуется доступность Sosumi MCP. Для плагина Cursor предназначен только основной swiftui-expert-skill — maintenance-навык остаётся служебной утилитой репозитория.
What are similar projects?vibe-coding-cn, pstack-claude, SwiftUI-Agent-Skill, pstack, open-steps, claude-code-infrastructure-showcase, agent-skills, superpowers-zh
Which topics is it in?profiling, pi-coding-agent, codex-cli, swiftui, gemini-cli, xcode, code-review, best-practices, accessibility, claude-skills, apple, prompt-engineering
Creator
AvdLee
Size
1 MB
Stars
3.7K
Updated
CommitOct 06Release5.2.1Oct 02
Age
8mo
Commits · 90 Days