{
  "markdown": "# SwiftUI macOS Skill\n\nAn agent skill for writing and reviewing SwiftUI code on macOS — with runtime-level understanding of observation, concurrency, view identity, and platform integration.\n\nBuilt from building a production macOS browser with SwiftUI and from reading the Swift runtime source. Every pattern here was validated against actual framework behavior, not inferred from documentation. Designed for frontier models: skips basics, focuses on the non-obvious traps and deep mechanisms that even experienced developers get wrong.\n\n## What makes this different\n\nMost SwiftUI guidance rewrites Apple's documentation or targets iOS beginners. This skill targets macOS, assumes the model already knows Swift and SwiftUI, and explains *why* things work the way they do — the kind of understanding you'd get from a Swift language contributor, not a tutorial author.\n\n**Runtime-level depth:**\n- **Observation internals** — how `shouldNotifyObservers` overloads resolve via the type system (Equatable vs non-Equatable vs AnyObject), why `_modify` always notifies but `set` checks equality, `Observations {}` for reactive async streams\n- **Scheduling cost hierarchy** — actual allocation costs from reading the Swift runtime: `assumeIsolated` (~0B) vs `MainActor.run` (~0B) vs `DispatchQueue.main.async` (~64B) vs `Task` (~300-500B), and *when each is correct*\n- **View identity graph** — how structural identity creates `_ConditionalContent`, why `.id()` with unstable values destroys state, how `Equatable` conformance short-circuits body evaluation\n\n**Patterns from production:**\n- Version counters to decouple observation from collection mutations\n- `@ObservationIgnored` discipline for internal caches and callbacks\n- `Observations {}` streams for reactive AppKit ↔ SwiftUI bridging\n- Custom `Layout` protocol over `GeometryReader` for arrangement logic\n- `NSHostingView` subclassing for embedding SwiftUI in AppKit hierarchies\n- Debounced SwiftData persistence and background `@ModelActor` operations\n\n**macOS-specific:**\n- Multi-window state architecture with per-window vs global state separation\n- `NSViewRepresentable` + `Equatable` to prevent unnecessary `updateNSView` calls\n- AppKit bridging patterns: window chrome, drag and drop, system blur, menu bar extras\n- `NSBackgroundActivityScheduler` over polling Task loops for periodic work\n\n## Installing\n\n### Claude Code (plugin)\n\nAdd the repo as a plugin marketplace, then install:\n\n```\n/plugin marketplace add kageroumado/swiftui-macos-skill\n/plugin install swiftui-macos\n```\n\n### Claude Code (manual)\n\nClone the repo, then copy the skill folder to the appropriate scope:\n\n**User-wide** (recommended — available across all projects):\n\n```bash\ngit clone https://github.com/kageroumado/swiftui-macos-skill.git\nmkdir -p ~/.claude/skills\ncp -r swiftui-macos-skill/skills/swiftui-macos ~/.claude/skills/\n```\n\n**Per-project** (shared with collaborators via version control):\n\n```bash\ngit clone https://github.com/kageroumado/swiftui-macos-skill.git\nmkdir -p your-project/.claude/skills\ncp -r swiftui-macos-skill/skills/swiftui-macos your-project/.claude/skills/\n```\n\n### Claude.ai\n\n1. Download or clone this repo\n2. Zip the `skills/swiftui-macos` folder\n3. Upload via **Settings > Capabilities > Skills**\n\n## Usage\n\nIn Claude Code:\n\n```\n/swiftui-macos\n```\n\nIn Codex:\n\n```\n$swiftui-macos\n```\n\nThe skill works for both writing and reviewing. Examples:\n\n```\n/swiftui-macos Review observation discipline in the sidebar views\n/swiftui-macos I'm building a multi-window document editor — help me architect the state\n/swiftui-macos Focus on concurrency patterns in the networking layer\n/swiftui-macos Help me bridge this NSCollectionView into SwiftUI\n```\n\n## References\n\n| File | Coverage |\n|---|---|\n| `references/observation.md` | Observation tracking: state capture, `_modify` vs `set`, version counters, scope narrowing, `Observations {}` streams, computed property propagation |\n| `references/concurrency.md` | Scheduling cost hierarchy, actor isolation, SE-0461/0469/0420/0471/0472, `AsyncStream` bridging, `@concurrent`, `sending` |\n| `references/views.md` | View decomposition, `.task(id:)`, preference keys, custom `Layout`, animation, navigation |\n| `references/data.md` | Manager pattern, `@Bindable`, SwiftData, debounced saving, `@ModelActor`, environment injection |\n| `references/platform.md` | `NSViewRepresentable`, `NSHostingView`, multi-window state, `openWindow`, AppKit bridging, macOS scenes |\n| `references/performance.md` | View identity graph, `.id()` dangers, `Equatable` views, `@State` for gestures, `Canvas`, `TimelineView`, `drawingGroup()` |\n| `references/api.md` | Deprecated API replacements, Swift modernisms, `@Previewable`, `@Entry`, Apple open-source Swift packages |\n| `references/accessibility.md` | VoiceOver, Dynamic Type, keyboard navigation, accessibility rotors, `@AccessibilityFocusState`, drag-and-drop a11y, testing |\n\n## Contributing\n\nContributions welcome. Every rule should earn its token cost — if a capable model already knows it, it doesn't belong here. Focus on things that are non-obvious, frequently wrong, or require runtime-level understanding to get right.\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n",
  "bytes": 5214,
  "sha": "dcfa0601cbf2a4d1b22b97a0472eed1fbfd6c129a5be698e8fc261b3fe8fb82e",
  "repo_slug": "kageroumado/swiftui-macos-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_kageroumado_swiftui_macos_skill_swiftui__2442dfb8/readme"
}