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.

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.

brew install node

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

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, use becomesKeyOnlyIfNeeded
22. Not restoring focus after sheet/alert — focus lost to window instead of returning to original view
23. .focusable() on NSViewRepresentable — creates double focus layer conflicting with AppKit
24. Menu items not checking for nil focusedValue — crashes when no window is key

FAQ

Sources

Built from:

• Apple Developer Documentation (UIFocusEnvironment, UIFocusGuide, FocusState, focusSection, HoverEffect)
• WWDC17: Focus Interaction in tvOS 11
• WWDC21: Direct and reflect focus in SwiftUI + Focus on iPad keyboard navigation
• WWDC23: The SwiftUI cookbook for focus
• WWDC24: Create custom hover effects in visionOS
• WWDC25: Design hover interactions for visionOS
• Production tvOS apps with complex focus requirements
• Community guides (Airbnb, Showmax, Fatbobman, Big Nerd Ranch)

Complementary Skills

Swift FocusEngine Pro pairs well with these skills:

• SwiftUI Pro by Paul Hudson — SwiftUI best practices and patterns
• Swift Concurrency Pro by Paul Hudson — async/await, actors, Sendable
• Swift Concurrency by Antoine van der Lee — Swift 6 migration, data race prevention
• Xcode Build Optimization by Antoine van der Lee — build benchmarking and optimization

See the Swift Agent Skills directory for more.

Changelog

See CHANGELOG.md for release history.

Contributing

Contributions are welcome! Focus on:

• Edge cases — non-obvious focus behaviors that catch developers off guard
• New platform APIs — additions from the latest OS releases (iOS/tvOS/macOS/visionOS/watchOS 26 and newer)
• Real-world patterns — battle-tested solutions from production apps
• Anti-patterns — mistakes LLMs commonly generate

Keep reference files focused and under 300 lines each. Don't repeat things LLMs already know — focus on what they get wrong. All contributions must be MIT licensed.

Please read the Code of Conduct before contributing.

License

Swift FocusEngine Pro was created by Michael Haviv and is licensed under the MIT License.