swift-focusengine-pro

Agent skill for focus management across all Apple platforms

Swift FocusEngine Pro is a free, open-source agent skill that helps AI coding assistants write correct focus management code for tvOS, iOS/iPadOS, watchOS, visionOS, and macOS. It covers SwiftUI, UIKit, AppKit, and RealityKit — targeting the mistakes LLMs actually make with Apple's focus engine.

Built from real-world experience shipping production tvOS apps, Apple developer documentation, WWDC sessions (2017-2025), and community best practices from Airbnb, Showmax, and others.

Works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and any tool supporting the Agent Skills format.

Table of Contents

• Who This Is For
• Why Use an Agent Skill for Focus?
• Installing
• Using
• What It Covers
• Anti-Patterns It Catches
• FAQ
• Sources
• Complementary Skills
• Changelog
• Contributing
• License

Who This Is For

• tvOS developers — building apps where every interaction depends on the focus engine working correctly
• iOS/iPadOS developers — adding keyboard, game controller, or external display support with focus groups
• visionOS developers — navigating the differences between gaze, hover, and focus in spatial computing
• macOS developers — building keyboard-navigable apps with key view loops, focus rings, and menu commands

Why Use an Agent Skill for Focus?

Focus management on Apple platforms is one of the hardest things to get right — and one of the hardest things to debug when it breaks.

The focus engine is geometric, not hierarchical. It doesn't follow your view tree. When a user swipes right and focus jumps two rows away instead of to the next item, there's no error, no crash, no log — it just looks broken. The item wasn't perfectly vertically aligned, so the engine picked a different candidate. You'll spend hours in UIFocusDebugger before you figure out why.

Apple's documentation covers the APIs but not the real-world edge cases: what happens when you reload data and focus resets to the top, why .disabled() silently removes views from the focus chain on tvOS, why .focusSection() is the difference between a usable scroll view and chaos, or why onHover doesn't fire from eye gaze on visionOS.