axiom-macos

Guides macOS app development covering windows, menus, sandboxing, distribution, and AppKit-SwiftUI bridging.

2|Updated Sep 8, 2026
One-click install
npx skills add https://github.com/hanshi-notes/hanshi --skill axiom-macos-hanshi-notes
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: axiom-macos
Source: https://github.com/hanshi-notes/hanshi/tree/main/.agents/skills/axiom-macos
Command: npx skills add https://github.com/hanshi-notes/hanshi --skill axiom-macos-hanshi-notes

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? macOS development involves platform-specific concerns that cross-platform SwiftUI knowledge does not cover: window and scene management, menu bar command routing, App Sandbox entitlements, Developer ID signing and notarization, and bridging between AppKit and SwiftUI. This Skill provides decision trees, anti-pattern warnings, and canonical code patterns for each of these areas. ## Core Features & Use Cases - Window, Menu, and Command Patterns: Implement WindowGroup scenes, CommandMenu/CommandGroup menus, keyboard shortcuts, and focus-based command routing with @FocusedValue and focusedSceneValue. - Sandbox and File Access: Configure App Sandbox entitlements, use fileImporter/NSOpenPanel correctly, and persist file access across launches with security-scoped bookmarks. - Distribution and AppKit Interop: Sign inside-out, notarize with notarytool, staple tickets, add Sparkle auto-updates, and bridge AppKit and SwiftUI via NSViewRepresentable, NSHostingController, and NSHostingMenu. - Use Case: You are shipping a SwiftUI markdown notebook app outside the App Store. Use this Skill to wire up menu commands to the focused window, add sandbox file-access entitlements with bookmarks, then sign, notarize, and staple a DMG with Sparkle updates. ## Quick Start Ask the assistant to help you add a sandboxed file-open workflow with security-scoped bookmarks to your macOS SwiftUI app.

Frequently Asked Questions about axiom-macos

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I connect macOS menu bar commands to the focused window in SwiftUI?▼

Publish window state from a view using .focusedSceneValue, then read it in your Commands struct with @FocusedValue or @FocusedBinding. Commands are scene-level and cannot access a window's @State directly, so this focus-based routing is required.

How do I notarize a macOS app for direct distribution?▼

Sign all components inside-out with codesign using a Developer ID identity, hardened runtime, and secure timestamp, then submit with xcrun notarytool and staple the ticket with xcrun stapler. The older altool is no longer accepted by Apple's notary service.

Why does my macOS app work in debug but fail in release?▼

Xcode debug builds do not enable the App Sandbox by default, so file and network operations succeed during development but are denied in sandboxed release builds. Enable the App Sandbox capability in debug or test release and TestFlight builds.

When should I use NSViewRepresentable versus NSHostingController?▼

Use NSViewRepresentable when SwiftUI is the host and you need to embed an AppKit view inside it. Use NSHostingController or NSHostingView when AppKit is the host and you need SwiftUI content in split views, sheets, popovers, or collection cells.

How do I persist file access across app launches in a sandboxed macOS app?▼

Create a security-scoped bookmark with bookmarkData(options: .withSecurityScope) when the user picks the file, store the data in a file in your container, then resolve it later and call startAccessingSecurityScopedResource. Always balance access with stopAccessingSecurityScopedResource.

Should I use codesign --deep when signing a macOS app?▼

No. The --deep flag applies identical entitlements and options to every nested component, which breaks components needing different entitlements such as XPC services. Sign each component individually from the innermost framework outward to the main app bundle.