avdlee__swiftui-agent-skill/README.md

SwiftUI Expert Skill

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.

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
• Core Data Expert
• Swift Testing Expert

How to Use This Skill

Option A: Using skills.sh (recommended)

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: 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

2. 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 C: Manual install

1. Clone this repository.
2. Install or symlink the swiftui-expert-skill/ folder following your tool’s official skills installation docs (see links below).
3. Use your AI tool as usual and ask it to use the “swiftui-expert” skill for SwiftUI tasks.

Where to Save Skills

Follow your tool’s official documentation, here are a few popular ones:

• Codex: Where to save skills
• Claude: Using Skills
• Cursor: Enabling Skills

How to verify:

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

What This Skill Offers

This skill gives your AI coding tool practical SwiftUI guidance. It can:

Guide Your SwiftUI Decisions

• Choose the right state management tool (@State, @Binding, @Observable, @Bindable)
• Provide clear guidance for sheets, navigation, scrolling, and lists
• Advise on iOS 26+ Liquid Glass usage with safe availability fallbacks

Write Better SwiftUI Views

• Keep view identity stable (e.g. avoid common ForEach pitfalls)
• Improve view composition for readability and efficient diffing
• Avoid common update/refresh pitfalls that cause unnecessary re-renders

Improve Performance

• Reduce redundant state updates in hot paths
• Improve list performance via stable identity and consistent row structure
• Suggest image downsampling when UIImage(data:) is encountered (as an optional optimization)

What Makes This Skill Different

Non-Opinionated: Focuses on SwiftUI correctness, not forcing an architecture, project structure, or code style.

Practical & concise: Treats the agent as capable; provides the checklists and pitfalls that actually matter in day-to-day SwiftUI work.

Skill Structure

swiftui-expert-skill/
  SKILL.md
  references/
    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
    image-optimization.md - AsyncImage usage, downsampling, caching
    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
    performance-patterns.md - Hot-path optimizations and update control
    scroll-patterns.md - ScrollViewReader and programmatic scrolling
    sheet-navigation-patterns.md - Sheets and type-safe navigation
    state-management.md - Property wrapper selection and data flow
    view-structure.md - View extraction and composition patterns

Contributing

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

Please read CONTRIBUTING.md for:

• How to contribute improvements to SKILL.md and the reference files
• Format requirements and quality standards
• Pull request process

Acknowledgments

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

• Skills by Thomas Ricouard — a collection of SwiftUI-focused Codex skills covering UI patterns, performance auditing, and Liquid Glass.

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

• Story behind this skill

License

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