Skip to content
Skills Library
Programming · Building & coding

programming-osx

/programming-osx

macOS app practices: window and command ownership, AppKit and SwiftUI, sandboxed file access, distribution. Use when building or reviewing Mac apps.

Author
Muvon ↗
Licence
Apache-2.0
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

macOS app practices: window and command ownership, AppKit and SwiftUI, sandboxed file access, distribution. Use when building or reviewing Mac apps.

Original author description

macOS app practices: window and command ownership, AppKit and SwiftUI, sandboxed file access, distribution. Use when building or reviewing Mac apps.

How it works

  1. Overview
  2. Mental model
  3. Platform gate
  4. Windows, commands, and UI
  5. Files and sandbox boundaries
  6. Helpers, lifecycle, and distribution
  7. Example
  8. Checklist
  9. References
Original SKILL.md headings · 80 lines, 879 words
SKILL.md preview
---
name: programming-osx
title: "macOS App Development Best Practices"
description: "macOS app practices: window and command ownership, AppKit and SwiftUI, sandboxed file access, distribution. Use when building or reviewing Mac apps."
license: Apache-2.0
compatibility: "Requires Xcode and the project's supported macOS SDK/deployment target; signing tools for distribution."
capabilities: programming-swift
domains: developer
rules:
  - content(macos)
  - content(osx)
  - content(appkit)
  - content(cocoa)
  - match(mac.+app|macos.+app|osx.+app|desktop.+app)
---

## Overview

Use for native macOS app implementation and review. Focus on windows, commands, files, sandbox boundaries, and distribution; preserve the application's SwiftUI/AppKit architecture and deployment contract.

## Mental model

A Mac app may have many independently focused windows and continue running with none visible. Model document, scene, and process lifetimes separately. File access and helper execution depend on explicit user/system authority, not just a path or process-wide singleton.

## Platform gate

As of 2026-10: Xcode 27 (Swift 6.4 compiler, macOS 27 SDK, runs on macOS Tahoe 26.6+) is the stable release; Xcode 27.1 is at release candidate and 27.2 in beta. Bundled helpers built with non-Apple toolchains carry their own minimum macOS (for example, Go 1.27 binaries require macOS 13+); check it against the app's deployment target. Apple's compatibility table distinguishes compiler, build SDK, host OS, and deployment target. Check these independently before adopting APIs; use actual symbol availability, not the installed machine's OS, as the minimum-version contract.

MenuBarExtra, NavigationSplitView, and SMAppService are available from macOS 13; Observation and SwiftData from macOS 14. Keep a supported AppKit implementation when it fits. Avoid speculative compatibility layers or raising deployment targets just to use a newer spelling.

## Windows, commands, and UI

- Use WindowGroup for independently instantiable windows, Window for a unique utility window, and DocumentGroup when document ownership fits. Keep window-specific selection, navigation, and drafts out of a process-global model.
- Route commands to the focused scene/selection using focused values or the established responder chain. Disable unavailable actions and provide keyboard shortcuts; don't locate a target with `NSApplication.shared.windows.first`.
- Store scene restoration values separately from documents. `@SceneStorage` is for lightweight restoration, not durable user content. Validate restored identifiers against current files and permissions.
- Use native Table, sidebar, toolbar, Settings, and menu patterns where suitable. Preserve keyboard focus, selection, undo/redo, VoiceOver labels, and resizing; don't port touch-only interaction unchanged.
- Use system controls/materials for macOS 26 styling, applying Liquid Glass to navigation/control surfaces deliberately. Test contrast and reduced transparency instead of layering decorative effects over content.
- Bridge AppKit with representables or hosting views/controllers at a clear boundary. Update existing native objects rather than recreating them on every render; remove observers and break callback ownership cycles during teardown.
- A menu-bar app needs explicit open/settings/quit behavior. `LSUIElement` controls Dock presence; it does not define the entire window-activation policy. Use MenuBarExtra or NSStatusItem according to actual behavior required.

## Files and sandbox boundaries

- Separate App Sandbox from Hardened Runtime: sandbox entitlements constrain resource access; hardened runtime and signing govern execution protections. Direct distribution does not require the same sandbox policy as the Mac App Store.
- Let users select external files through supported panels/document APIs. Persist security-scoped bookmarks when access must survive relaunch; resolve stale bookmarks and refresh them through the documented flow.
- For a security-scoped URL, balance each successful `startAccessingSecurityScopedResource()` with `stopAccessingSecurityScopedResource()`. Keep access active for the whole operation; denial is an error, not a reason to retry through an unrestricted path.
- Use coordinated/document-aware access for externally managed documents. Preserve file contents and surface save conflicts; don't replace an unreadable document with an empty one or delete data to recover from migration failure.
- Store credentials in Keychain. Grant only entitlements needed by the feature; a broadly permissive entitlement is not a fix for an unexplained access failure.

## Helpers, lifecycle, and distribution

- Keep UI state on its intended actor and long-running work outside the UI execution path. Closing a window and quitting the process are distinct events; explicitly own tasks, observers, and subprocesses.
- Use SMAppService for supported login-item/helper registration. Handle enabled, disabled, and approval-required states explicitly; don't repeatedly register to defeat a user's choice. Give XPC services and extensions narrow interfaces and validate requests.
- Don't add privileged helpers or system extensions unless the requested feature requires their privileges. Entitlement eligibility and approval flow must be verified for the actual extension type.
- For direct distribution, follow Developer ID signing, hardened runtime, notarization, and ticket stapling requirements for the artifact. Sign nested code correctly and test the delivered package on a clean machine; local development launch does not prove Gatekeeper behavior.
- Preserve the existing update channel. If updates are part of the task, verify authenticity, compatibility, and recoverable failure; don't add an updater dependency solely as a best-practice recommendation.

## Example

Keep authority alive and guarantee balanced cleanup for a resolved security-scoped URL:

```swift
import Foundation

enum FileAccessError: Error { case denied }

func withFileAccess<T>(
    to url: URL, perform operation: (URL) throws -> T
) throws -> T {
    guard url.startAccessingSecurityScopedResource() else {
        throw FileAccessError.denied
    }
    defer { url.stopAccessingSecurityScopedResource() }
    return try operation(url)
}
```

This helper is for security-scoped URLs; ordinary container URLs use their normal access path. Keep large synchronous I/O out of UI execution.

## Checklist

- [ ] Symbol availability and deployment target agree; beta APIs are identified.
- [ ] Window focus, scene restoration, and document ownership are explicit.
- [ ] File access, cleanup, denial, and save conflicts are handled.
- [ ] Helpers and distribution use the intended entitlements and lifecycle.
- [ ] Relevant sandbox, UI, and distribution checks ran when authorized; limits are stated.

## References

- [Xcode/SDK matrix](https://developer.apple.com/xcode/system-requirements)
- [Security-scoped access](https://developer.apple.com/documentation/foundation/url/startaccessingsecurityscopedresource())
- [SMAppService](https://developer.apple.com/documentation/servicemanagement/smappservice)
- [Notarization](https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution)
- [Distribution testing](https://developer.apple.com/documentation/xcode/packaging-mac-software-for-distribution)
- [Liquid Glass](https://developer.apple.com/videos/play/wwdc2025/219/)

Versions

The database has no other skills named programming-osx.

Database snapshot: 13.11.2026 · package version 7be5ead3a81d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90desktop-swiftui
    Use when the user asks about SwiftUI for macOS, SwiftUI desktop patterns, AppKit bridging, SwiftUI app lifecycle, or SwiftUI multiplatform apps. Do NOT use for: AppKit-only (desktop-appkit), or iOS SwiftUI (mobile skill).
  • 90macos
    Use when building Mac apps — menu bar extras, window management, AppKit integration, or notarized distribution outside the App Store.
  • 90desktop-appkit
    Use when the user asks about macOS app development with AppKit, Cocoa, Objective-C, Swift AppKit, macOS UI framework, or native Mac application architecture. Do NOT use for: SwiftUI (desktop-swiftui), or cross-platform desktop (desktop-electron, desktop-tauri).
  • 100macos-apps
    Build professional native macOS apps in Swift with SwiftUI and AppKit. Full lifecycle - build, debug, test, optimize, ship. CLI-only, no Xcode. Use when asked to: create macOS apps, build Swift apps, develop SwiftUI interfaces, fix macOS app issues, add macOS app features, or…
  • 91macos-design-guidelines
    Apple Human Interface Guidelines for Mac. Use when building macOS apps with SwiftUI or AppKit, implementing menu bars, toolbars, window management, or keyboard shortcuts. Triggers on tasks involving Mac UI, desktop apps, or Mac Catalyst.
  • 100appkit-app-architecture-workflow
    Guide AppKit app-structure decisions for macOS apps across app delegates, status-item menu bar apps, responder-chain menus, windows, controllers, restoration, archiving, Observation, and mixed AppKit/SwiftUI composition. Use when the user wants help deciding where AppKit…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.