# Macos Development

> Use when building or debugging a macOS app and the request involves — (1) AppKit/SwiftUI interop or modernizing AppKit code, (2) App Sandbox / file-access entitlement errors, especially "works in Xcode, fails in TestFlight", (3) menu bar commands, keyboard shortcuts, or a menu item stuck disabled, (4) multi-window scenes (WindowGroup, Window, MenuBarExtra, openWindow), (5) the Settings/Preference…

- **Type:** Skill
- **Install:** `agentstack add skill-patrickserrano-lacquer-macos-development`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [patrickserrano](https://agentstack.voostack.com/s/patrickserrano)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [patrickserrano](https://github.com/patrickserrano)
- **Source:** https://github.com/patrickserrano/lacquer/tree/main/profiles/ios/skills/macos-development
- **Website:** https://patrickserrano.github.io/lacquer/

## Install

```sh
agentstack add skill-patrickserrano-lacquer-macos-development
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# macOS Development

Platform mechanics for macOS apps — windows, menus, sandboxing, AppKit bridging,
ScreenCaptureKit, and where SwiftUI on macOS diverges from iOS. This complements
narrower macOS skills already in this profile: `macos-ci-recipes` (CI-only) and
`release-macos-spm-packaging` (SwiftPM scaffolding/build/packaging, no Xcode
project). For visual/HIG conventions ("does this look like a real Mac app"),
see the third-party `mac-assed-mac-app-skill` — that skill covers appearance,
this one covers the platform APIs underneath it.

## Agent behavior contract

1. Identify which of macOS's three structural differences from iOS is in play
   before proposing a fix: **multi-window** (state is per-scene, not global),
   **focus-driven** (the menu bar routes through the focused window, not a
   singleton), **keyboard-first** (every action needs a menu-bar path, not
   just a toolbar button). Most "this doesn't feel like a real Mac app" bugs
   trace back to one of these three.
2. Before recommending file access code, confirm whether the app is sandboxed
   (App Store) or Developer-ID direct-distributed — sandbox entitlements and
   security-scoped bookmarks only apply to the former, but debug builds don't
   sandbox by default either way, so "works in Xcode" proves nothing.
3. When bridging AppKit and SwiftUI, determine the host/guest direction first
   (which framework owns the view hierarchy) — the bridging type differs by
   direction, not just by "which framework's API do I need."
4. For distribution questions, first determine whether the project has an
   `.xcodeproj`/`.xcworkspace` or is pure SwiftPM — `release-macos-spm-packaging`
   already owns the SwiftPM scaffold/build/package/notarize pipeline end to
   end; only add net-new distribution guidance here (see
   `references/direct-distribution.md`) rather than duplicating it.
5. Prefer this skill's `references/` over recalling WWDC session content from
   memory — API availability and gotchas below are the source of truth.

## Triage template

- **Clarify the goal**: new feature, porting an iOS view to macOS, a crash/violation to diagnose, or a distribution/packaging question?
- **Collect minimal facts**: deployment target, sandboxed or Developer-ID direct-distributed, SwiftUI-only or mixing AppKit, Xcode project or SwiftPM.
- **Branch immediately**:
  - "works in Xcode, fails in TestFlight/release" → almost always sandbox (debug builds aren't sandboxed) — `references/sandbox-and-file-access.md`
  - menu item stays disabled / wrong window responds → focused-value routing — `references/menus-and-commands.md`
  - "feels like a ported iPad app" → `references/swiftui-differences.md`
  - Gatekeeper/notarization/codesign failure → `references/direct-distribution.md`

## Routing map

| Topic | Reference |
|---|---|
| WindowGroup, Window, UtilityWindow, MenuBarExtra, DocumentGroup, openWindow/dismissWindow, defaultSize | `references/windows.md` |
| Menu bar commands, CommandMenu/CommandGroup, keyboard shortcuts, context menus, focusedSceneValue routing | `references/menus-and-commands.md` |
| Table vs List, NavigationSplitView, Inspector, macOS focus/keyboard APIs, toolbars, SwiftUI-on-macOS gaps that force an AppKit escape hatch | `references/swiftui-differences.md` |
| The Settings scene (⌘,), tabbed preferences, SettingsLink, @AppStorage keys, iOS system-Settings adjacency | `references/settings.md` |
| App Sandbox model, `.fileImporter`/`NSOpenPanel`, security-scoped bookmarks, entitlements, sandbox-violation diagnosis | `references/sandbox-and-file-access.md` |
| Developer ID code signing, notarytool, packaging (dmg/zip/pkg), Sparkle auto-updates, Gatekeeper troubleshooting | `references/direct-distribution.md` |
| NSViewRepresentable/NSViewControllerRepresentable, NSHostingController/NSHostingView, `@Observable` in AppKit, NSHostingMenu, NSToolbar bridging | `references/appkit-interop.md` |
| Replacing `mouseDown` overrides, NSControl.Events, status-item expanded interface sessions, window state restoration, concentric corners/Liquid Glass, touch input | `references/appkit-modernization.md` |
| Screen recording/sharing/screenshots via ScreenCaptureKit, SCStream/SCContentFilter API surface | `references/screencapturekit.md` |

## Common errors → next best move

- **"Operation not permitted" / sandbox violation only outside Xcode** → `references/sandbox-and-file-access.md` (debug builds skip the sandbox)
- **Menu item permanently disabled** → `references/menus-and-commands.md` (missing `.focusedSceneValue` publisher)
- **`SCShareableContent` returns nothing** → `references/screencapturekit.md` (Screen Recording TCC not granted)
- **Notarization rejects with "hardened runtime" or "secure timestamp" error** → `references/direct-distribution.md`
- **`updateNSView` resets the caret / selection while typing** → `references/appkit-interop.md` (guard property writes; use `NSTextView.scrollableTextView()`)
- **Settings window compiles on macOS, fails on iOS** → `references/settings.md` (`Settings { }` needs `#if os(macOS)`)

## Out of scope, deliberately

Cross-platform SwiftUI fundamentals (state, navigation basics, animation),
Swift Concurrency, and Core Data/CloudKit aren't macOS-specific — use
`swiftui-expert-skill`, `swift-concurrency`, and `core-data-expert`
respectively. iOS screen recording is ReplayKit, not ScreenCaptureKit — not
covered here.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [patrickserrano](https://github.com/patrickserrano)
- **Source:** [patrickserrano/lacquer](https://github.com/patrickserrano/lacquer)
- **License:** MIT
- **Homepage:** https://patrickserrano.github.io/lacquer/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-patrickserrano-lacquer-macos-development
- Seller: https://agentstack.voostack.com/s/patrickserrano
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.