apple-engineer-superpowers

The most comprehensive Apple platform engineering skill for AI coding assistants. ~100KB of production-tested patterns across Swift 6 concurrency, SwiftUI, Metal, RealityKit, and visionOS — areas no other skill covers in depth.

Why This Skill

Existing Swift/iOS skills for AI assistants tend to offer surface-level best practices or focus narrowly on tooling (simulator automation, build scripts). None go deep on the hard parts:

• Swift 6 concurrency — actors, Sendable, AsyncSequence, state machines, task cancellation, reactive patterns. Not just "use async/await" but the full isolation model.
• Metal GPU programming — compute and render pipelines, buffer management, ring buffers, threadgroup sizing, shader patterns. No other skill touches this.
• RealityKit & visionOS — entity-component-system architecture, custom Systems, immersive spaces, hand tracking, multi-window scenes. No other skill covers spatial computing.
• Advanced Swift patterns — interpolation/animation primitives, non-empty collections, enum-keyed tables, async broadcast channels, Combine bridging. The patterns that make production code robust.

This isn't a checklist of tips. It's a detailed reference your AI assistant can use to write correct, modern Swift the way an experienced Apple engineer would.

Example Use Cases

"Build me a network service with retry and cancellation" The agent uses the concurrency reference to produce an actor-isolated service with async throws, structured Task cancellation, and AsyncThrowingStream for progress — not a callback-based wrapper.

"Create a Metal compute shader that processes video frames" The agent follows the Metal reference to set up a MTLComputePipelineState, use a ring buffer for multi-frame pipelining, size threadgroups correctly, and read from an IOSurface-backed texture.

"Add a hand-tracking interaction to my visionOS app" The agent references the RealityKit/visionOS guide to set up an ARKitSession with HandTrackingProvider, read joint positions from HandSkeleton, and wire it into a RealityKit System with proper scene subscriptions.

"Refactor this ViewModel to use @Observable" The agent uses the SwiftUI architecture reference to migrate from ObservableObject with @Published to @Observable, update the View bindings, and keep the ViewModel on @MainActor.

"I need a smooth spring-like animation value tracker" The agent uses the advanced patterns reference to implement an ExponentialDamper with the Lerpable protocol, supporting Float, SIMD3, and quaternion types.

What's Inside

File	Covers
SKILL.md	Core principles, quick-reference tables, entry point for the skill
swift-concurrency.md	Swift 6 concurrency: actors, Sendable, AsyncSequence, task cancellation, synchronization, state machines, reactive patterns, generics, persistence, networking, testing, diagnostics
swiftui-architecture.md	SwiftUI app architecture: MVVM, ViewModel/View guidelines, service layer patterns, data flow, App Intents, file organization
metal-graphics.md	Metal GPU programming: pipelines, buffers, textures, compute dispatch, ring buffers, shaders, frame pacing
realitykit-visionos.md	RealityKit ECS and visionOS: entities, components, systems, scene subscriptions, immersive spaces, windows, hand tracking
advanced-swift-patterns.md	Property wrappers, interpolation/animation, collection types, Combine bridging, advanced async abstractions, @dynamicMemberLookup

Installation

Note: Installation differs by platform. Choose the one that matches your environment.

Claude Code (via Plugin Marketplace)

# Add the marketplace (one-time)
/plugin marketplace add piemonte/apple-engineer-superpowers

# Install the skill
/plugin install apple-engineer-superpowers@apple-engineer-superpowers

Codex

# Clone the repository
git clone https://github.com/piemonte/apple-engineer-superpowers.git ~/.codex/apple-engineer-superpowers

# Create symlink
ln -s ~/.codex/apple-engineer-superpowers ~/.agents/skills/apple-engineer-superpowers

See .codex/INSTALL.md for Windows instructions and more details.

Cursor (via Plugin Marketplace)

/plugin install piemonte/apple-engineer-superpowers

Verify Installation

Ask your AI assistant:

"What concurrency primitive should I use for a shared stateful component in Swift?"

It should recommend using an actor — referencing the skill's concurrency guidelines.

Updating

Claude Code / Cursor:

/plugin update apple-engineer-superpowers

Codex:

cd ~/.codex/apple-engineer-superpowers && git pull

Core Principles

1. No Force Unwrapping (!) — Use guard let, if let, nil coalescing (??), or optional chaining
2. Actor-First Concurrency — Use actors as the default for stateful components
3. Async/Await Always — Never use completion handlers in new code
4. Sendable Everything — All shared types must conform to Sendable
5. Swift 6 Strict Concurrency — Enable StrictConcurrency from the start
6. Protocol-Oriented Design — Define contracts through protocols
7. LocalizedError for Errors — Domain-specific error enums conforming to LocalizedError, Sendable

Resources

• Superpowers — The complete development workflow skill system this plugin is built for. Adds brainstorming, TDD, debugging, code review, and parallel subagent orchestration to your AI coding agent.
• Swift Evolution — The proposals behind the concurrency model this skill teaches (SE-0306 actors, SE-0302 Sendable, SE-0414 region-based isolation, and more).
• swift-async-algorithms — Apple's open-source AsyncSequence utilities that complement the concurrency patterns here.
• Metal Best Practices Guide — Apple's official guide to Metal performance, pairs well with the Metal reference.
• Apple Sample Code — Official sample projects, especially useful for RealityKit and visionOS.
• WWDC Sessions — The primary source for Metal, RealityKit, and visionOS content this skill distills.

Contributing

1. Fork this repository
2. Add or improve reference content in the relevant .md file
3. Ensure all APIs referenced are from public Apple SDKs or open-source Swift
4. Open a pull request with a clear description of what changed

License

MIT License — see LICENSE file for details.