Swift-FocusEngine-Agent-Skill

<p align="center"> <img src="assets/logo.svg" height="180" alt="Swift FocusEngine Pro" /> </p> <h3 align="center">Agent skill for focus management across all Apple platforms</h3> <p align="center"> <img src="https://img.shields.io/badge/tvOS-15+-000000?logo=apple" /> <img src="https://img.shields.io/badge/iOS-15+-000000?logo=apple" /> <img src="https://img.shields.io/badge/watchOS-8+-000000?logo=apple" /> <img src="https://img.shields.io/badge/visionOS-1+-000000?logo=apple" /> <img src="https://img.shields.io/badge/macOS-12+-000000?logo=apple" /> <img src="https://img.shields.io/badge/Swift-5.9+-F05138?logo=swift&logoColor=white" /> <img src="https://img.shields.io/badge/License-MIT-blue" /> <img src="https://img.shields.io/badge/version-1.8.1-brightgreen" /> </p> <p align="center"> <a href="https://skills.sh/mhaviv/Swift-FocusEngine-Agent-Skill"> <img src="https://img.shields.io/badge/skills.sh-Listed-6C47FF?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHRleHQgeD0iNCIgeT0iMTgiIGZvbnQtc2l6ZT0iMTYiIGZpbGw9IndoaXRlIj7wn5ugPC90ZXh0Pjwvc3ZnPg==&logoColor=white" /> </a> <a href="https://github.com/twostraws/Swift-Agent-Skills"> <img src="https://img.shields.io/badge/Swift_Agent_Skills-Listed-F05138?logo=swift&logoColor=white" /> </a> <a href="https://www.awesomeskills.dev/en/skill/mhaviv-swift-focusengine-agent-skill"> <img src="https://img.shields.io/badge/awesomeskills.dev-Listed-10B981" /> </a> <a href="https://github.com/mhaviv/Swift-FocusEngine-Agent-Skill/stargazers"> <img src="https://img.shields.io/github/stars/mhaviv/Swift-FocusEngine-Agent-Skill?style=flat&logo=github&label=Stars" /> </a> </p> <p align="center"> <a href="https://x.com/michael_haviv"> <img src="https://img.shields.io/badge/Contact-@michael__haviv-1DA1F2?logo=x&logoColor=white" /> </a> <a href="https://www.linkedin.com/in/michaelhaviv/"> <img src="https://img.shields.io/badge/LinkedIn-Michael_Haviv-0A66C2?logo=linkedin&logoColor=white" /> </a> </p>

---

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.

LLMs generate focus code that compiles and looks reasonable — but breaks in ways you only discover on a real device with a Siri Remote in your hand. This skill is built from my experience getting focus to actually work in a complex, production tvOS app. Every anti-pattern in here is something I hit, debugged, and fixed.

Installing

Claude Code

# Global (all projects)
npx skills add https://github.com/mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro -g -y

# Project-level only
npx skills add https://github.com/mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro -y

Codex

npx skills add https://github.com/mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro --agent codex

Cursor

npx skills add https://github.com/mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro --agent cursor

GitHub Copilot

npx skills add https://github.com/mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro --agent github-copilot

Gemini CLI

npx skills add https://github.com/mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro --agent gemini

Other Agents

Any agent that supports the Agent Skills format can use this skill. See agentskills.io for instructions on adding skills to your agent.

<details> <summary>Don't have Node installed?</summary>

brew install node

Or download from nodejs.org.

</details>

Updating

Skills are installed as local copies — they don't auto-update. To pull the latest version:

# Update all installed skills
npx skills update -g -y

# Or reinstall this skill specifically
npx skills add https://github.com/mhaviv/Swift-FocusEngine-Agent-Skill --skill swift-focusengine-pro -g -y

⭐ Star and Watch this repo to get notified of new releases.

Using

Claude Code

/swift-focusengine-pro Review this view for tvOS focus issues

Codex

$swift-focusengine-pro Check my SwiftUI code for focus anti-patterns

Cursor

/swift-focusengine-pro Review this view for tvOS focus issues

GitHub Copilot

/swift-focusengine-pro Review this view for tvOS focus issues

Gemini CLI

Use the swift-focusengine-pro skill to review my focus handling code

Any Agent

Use the Swift FocusEngine Pro skill to audit my project for focus management problems

Example Prompts

• "Why isn't the first item focused when my view appears?"
• "Focus is jumping to a completely different row when I swipe right — the items aren't perfectly aligned vertically"
• "How do I keep focus position after my data reloads?"
• "I added .disabled() to a button but now focus skips over the entire section"
• "What's the difference between gaze and focus on visionOS?"
• "My Digital Crown rotation stopped working after I reordered my view modifiers"
• "How do I make menu bar commands respond to whichever document window is focused?"

What It Covers

5,000+ lines of focus expertise across 14 reference files

| Reference | Platform | Coverage | |-----------|----------|----------| | anti-patterns.md | All | 30 critical mistakes: 17 original tvOS + 6 production tvOS + 7 macOS-specific | | swiftui-focus.md | tvOS | @FocusState, focusSection, prefersDefaultFocus, AutoFocusManager pattern | | uikit-focus.md | tvOS | UIFocusEnvironment, UIFocusGuide, shouldUpdateFocus, didUpdateFocus | | ios-focus.md | iOS/iPadOS | SwiftUI + UIKit: focus groups, focusGroupIdentifier, UIFocusHaloEffect, keyboard nav, focusedValue, game controller, Stage Manager | | watchos-focus.md | watchOS | SwiftUI: Digital Crown routing, sequential focus, Crown conflicts, .digitalCrownAccessory | | visionos-focus.md | visionOS | SwiftUI + UIKit + RealityKit: gaze vs hover vs focus, HoverEffect, HoverEffectComponent | | focus-styling.md | All | ButtonStyle + isFocused, FocusBorder, CABasicAnimation, CardButtonStyle, macOS focus ring styling | | focus-restoration.md | All | Data reload handling, safe reload pattern, row offset tracking | | layout-patterns.md | tvOS | Table-of-collections, sidebar+content, tab bar, hero+catalog | | macos-focus.md | macOS | AppKit + SwiftUI: key view loop, focus ring, NSView focus APIs, focusedValue for menus, Mac Catalyst, Full Keyboard Access | | realitykit-focus.md | visionOS | RealityKit entity hover, collision shapes, gestures, shader effects, mixed hierarchies | | async-focus.md | All | @MainActor coordination, focus after data load, NavigationStack pop, Task cancellation | | accessibility-focus.md | All | @AccessibilityFocusState, VoiceOver + focus, Full Keyboard Access, Switch Control, Reduce Motion | | debugging.md | All | UIFocusDebugger, _whyIsThisViewNotFocusable, launch arguments, macOS first responder debugging |

Anti-Patterns It Catches

Blocking (must fix before ship)

1. .disabled() removes views from the focus chain on tvOS — gate the action inside the closure instead (.allowsHitTesting(false) is unreliable)
2. Missing .focusSection() on horizontal ScrollViews — causes cross-row focus jumping in vertical layouts
3. Adding .focusable() to Buttons or NavigationLinks — creates double-focus artifacts
4. Mixing SwiftUI and UIKit focus in the same hierarchy — focus environment conflicts
5. Calling reloadData() during animations — focus resets to the top of the screen
6. Using frame.width in focus transform calculations — dimensions change when focused
7. setNeedsFocusUpdate() called from wrong environment — silently fails with no error
8. Setting isUserInteractionEnabled = false on headers/labels — removes them and their children from focus chain
9. remembersLastFocusedIndexPath + offscreen reloadData() — remembered index may no longer exist
10. Using UIView.animate for CALayer properties — animations won't work, use CABasicAnimation

Warning (should fix)

11. Non-optional @FocusState with focused(_:equals:) — can't represent "nothing focused" state
12. Missing prepareForReuse() cleanup for focus state — stale focus styling on reused cells
13. prefersDefaultFocus inside ScrollView — may not work as expected, use defaultFocus instead
14. LazyVStack/LazyVGrid performance on Apple TV HD — A8 chip can't handle lazy layout recalculation during fast scrolling

tvOS production patterns

15. LazyVStack deallocates offscreen rows — rapid upward swipe causes focus to jump to tab bar, skipping content
16. Missing .focusSection() on vertical ScrollView — focus escapes upward to tab bar/nav bar
17. Allocating objects in didUpdateFocus/shouldUpdateFocus — per-frame garbage causes micro-stutters

macOS-specific

18. Not overriding acceptsFirstResponder on custom NSView — view is invisible to Tab navigation
19. Incomplete key view loop — Tab stops working after reaching the last view
20. Calling becomeFirstResponder() directly — bypasses resign/become handshake, use window.makeFirstResponder
21. NSPanel stealing focus — inspector panels take focus from document window, us