JordanCoin/ios-skills-collection / skills/avdlee--swiftui-expert
swiftui-expert-skill
VerifiedWrite, review, or improve SwiftUI code following best practices for state management, view composition, performance, macOS-specific APIs, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 4.9 KB |
| SKILL.md | skill md | 5.7 KB |
| references/accessibility-patterns.md | markdown | 5.9 KB |
| references/animation-advanced.md | markdown | 10.1 KB |
| references/animation-basics.md | markdown | 6.7 KB |
| references/animation-transitions.md | markdown | 7.4 KB |
| references/charts-accessibility.md | markdown | 6.1 KB |
| references/charts.md | markdown | 16.8 KB |
| references/image-optimization.md | markdown | 7.2 KB |
| references/latest-apis.md | markdown | 15.2 KB |
| references/layout-best-practices.md | markdown | 6.8 KB |
| references/liquid-glass.md | markdown | 11.2 KB |
| references/list-patterns.md | markdown | 12.3 KB |
| references/macos-scenes.md | markdown | 9.1 KB |
| references/macos-views.md | markdown | 10.6 KB |
| references/macos-window-styling.md | markdown | 8.6 KB |
| references/performance-patterns.md | markdown | 11.6 KB |
| references/scroll-patterns.md | markdown | 8.3 KB |
| references/sheet-navigation-patterns.md | markdown | 10.6 KB |
| references/state-management.md | markdown | 13.7 KB |
| references/view-structure.md | markdown | 12.7 KB |
AGENTS.md
View on GitHub# Agent Guidelines for SwiftUI Expert Skill
This document provides guidance for AI agents working with this skill to ensure consistency and avoid common pitfalls.
## Core Principles
### 1. SwiftUI Focus Only
**This is a SwiftUI skill.** Do not include:
- Swift concurrency patterns (use `.task` for SwiftUI-specific needs only)
- General Swift language features unrelated to SwiftUI
- Backend or server-side Swift patterns
- UIKit patterns (except when bridging is necessary)
### 2. No Code Formatting or Linting
**Do not include formatting/linting rules.** Avoid:
- Property ordering requirements (environment, state, body, etc.)
- Code organization mandates
- Whitespace or indentation rules
- Naming convention enforcement
- File structure requirements
**Exception**: Mention organization patterns as *optional suggestions* for readability, never as requirements.
### 3. No Architectural Opinions
**Stick to facts, not architectures.** Avoid:
- Enforcing MVVM, MVC, VIPER, or any specific architecture
- Mandating view model patterns
- Requiring specific folder structures
- Dictating dependency injection patterns
- Prescribing router/coordinator patterns
**Exception**: Suggest separating business logic for testability without enforcing how.
### 4. No Tool-Specific Instructions
**Agents cannot use external tools.** Do not include:
- Xcode Instruments profiling instructions
- Debugging tool usage
- IDE-specific features
- Command-line tool usage beyond basic git
**Exception**: Mention that users can profile with Instruments if performance issues arise, but don't provide detailed instructions.
## Content Guidelines
### Suggestions vs Requirements
**Use "suggest" or "consider" for optional optimizations:**
- ✅ "Consider downsampling images when using `UIImage(data:)`"
- ❌ "Always downsample images"
**Use "always" or "never" only for correctness issues:**
- ✅ "Never use `.indices` for dynamic ForEach content"
- ✅ "Always mark `@State` as `private`"
### Performance Optimizations
**Present performance optimizations as optional improvements:**
- Image downsampling: Suggest when `UIImage(data:)` is encountered
- POD view wrappers: Mention as advanced optimization technique
- Equatable conformance: Suggest for expensive views
**Do not automatically apply optimizations.** Let developers decide based on their performance needs.
## What to Include
### ✅ Include These Topics:
- Property wrapper selection (`@State`, `@Binding`, `@Observable`, etc.)
- View composition and extraction patterns
- Performance patterns (stable identity, lazy loading, etc.)
- Common pitfalls and how to avoid them
- Sheet, navigation, and list patterns
- Liquid Glass API usage (iOS 26+)
- Accessibility best practices
### ❌ Exclude These Topics:
- Swift concurrency deep dives (actors, sendable, etc.)
- Code formatting and style rules
- Architectural patterns and mandates
- Tool usage instructions (Instruments, debuggers)
- File organization requirements
- Testing frameworks and patterns
- Build system configuration
- Project structure mandates
## Language and Tone
### Use Clear, Direct Language:
- "Consider X when Y" (for optimizations)
- "Avoid X because Y" (for anti-patterns)
- "X is preferred over Y" (for best practices)
### Avoid Prescriptive Language:
- ❌ "You must organize properties in this order"
- ❌ "Always use MVVM architecture"
- ❌ "Profile with Instruments following these steps"
- ❌ "Structure your project like this"
## Examples
### Good Example:
```markdown
## ForEach Identity
**Always provide stable identity for `ForEach`.** Never use `.indices` for dynamic content.
When you encounter `UIImage(data:)`, consider suggesting image downsampling as a performance optimization.
```
### Bad Example:
```markdown
## View Organization
**Always organize view properties in this order:**
1. Environment
2. State
3. Body
4. Helpers
**Use Instruments to profile:**
1. Open Instruments
2. Select SwiftUI template
3. Record and analyze...
```
## Updating the Skill
When adding new content:
1. Ask: "Is this SwiftUI-specific?"
2. Ask: "Is this a fact or an opinion?"
3. Ask: "Can agents actually use this?"
4. Ask: "Is this about correctness or style?"
If unsure, err on the side of excluding content. It's better to have a focused, factual skill than a comprehensive but opinionated one.
## Maintenance Skills
This repository includes a maintenance skill for keeping API guidance up to date:
- **`.agents/skills/update-swiftui-apis/SKILL.md`** — Scan Apple's SwiftUI documentation via the Sosumi MCP, identify deprecated APIs and their modern replacements, and update `swiftui-expert-skill/references/latest-apis.md`. Use after new iOS/Xcode releases or when you want to refresh the deprecated API reference.
## Summary
**Focus**: SwiftUI APIs, patterns, and correctness
**Avoid**: Formatting, architecture, tools, Swift language features
**Tone**: Factual, helpful, non-prescriptive
**Goal**: Make agents SwiftUI experts without enforcing opinions
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |