macos-app-skills: agent skills for native macOS app work

What macos-app-skills is for

The repository collects AI coding agent skills aimed at native macOS development with SwiftUI and AppKit. The README describes them as encoding "hard-won patterns for building production macOS apps", specifically the parts that are underdocumented, spread across WWDC sessions, and easy to get wrong. The target user is someone who already prompts an agent such as OpenCode, Claude Code or Cursor against a real Xcode project and keeps getting plausible Swift that does not compile or does not behave like a Mac app.

The problem is narrower than "help me write Swift". An agent trained largely on web material will reach for a browser-shaped solution: a settings screen built with a plain SwiftUI Window scene, a floating panel treated like a DOM overlay, a keyboard shortcut handled with a JavaScript-style event listener. The README lists these as the recurring failures. Settings windows look wrong because the Window scene does not support fullSizeContentView, which the liquid glass chrome on macOS 26 needs. Notch overlays need specific NSPanel configuration and screen geometry math. Native patterns such as NSPanel versus NSWindow, activation policy toggling and Carbon hotkeys have no web equivalent, so the model defaults to something that will not work.

That framing matters when you decide whether to install it. This is not a library you link against. It is reference text an agent reads before writing code.

The five skill directories and what each contains

Each skill is a self-contained directory holding a SKILL.md file plus an optional references/ folder. There are five.

build/ covers building an Xcode project from the command line with xcodebuild, including project discovery, scheme detection, beta toolchains and common build failures. settings-ui/ builds a preferences window with liquid glass support for macOS 26 (Tahoe), using NSWindowController with .fullSizeContentView, a NavigationSplitView sidebar, grouped Forms with transparent backgrounds, and back/forward toolbar navigation. auto-update/ wires in Sparkle for apps distributed outside the Mac App Store, covering the SPM dependency, an UpdaterManager singleton, Info.plist configuration, EdDSA key generation and a settings toggle plus menu bar button. macos-patterns/ is the broad reference: menu bar apps (MenuBarExtra versus NSStatusItem versus NSPopover), activation policy, NSPanel versus NSWindow, window levels and collection behaviors, screen geometry with frame versus visibleFrame and the Y-axis flip, keyboard shortcuts in three tiers, file pickers, pasteboard, drag and drop, launch at login, Quick Look, NSWorkspace, ScreenCaptureKit and UserDefaults. notch-ui/ builds a Dynamic Island style overlay from the hardware notch, using a borderless NSPanel at CGShieldingWindowLevel with a custom NotchShape that has concave Bezier ear curves, spring animations, and a fallback pill mode for Macs without a notch.

Three of the five ship reference Swift files meant to be copied into a project. The README names UpdaterManager.swift, NotchWindow.swift and NotchShape.swift explicitly, and says settings-ui includes complete reference files as well. That is the practical difference between this and a prose guide: there is code to diff against.

Installing the skills and a first run

The README gives a one-line install through the skills CLI:

npx skills add fayazara/macos-app-skills

For OpenCode, the documented route is a manual copy into a per-project directory. Copy everything, or only the skill you need:

cp -r build settings-ui auto-update release notch-ui /path/to/your/project/.agents/skills/
cp -r settings-ui /path/to/your/project/.agents/skills/

A global install for OpenCode copies into the user config directory instead:

cp -r build settings-ui auto-update release notch-ui ~/.config/opencode/skills/

Other agents are handled by adapting the file format. The README states that each SKILL.md is markdown with YAML frontmatter, and that you should adapt it to your agent's skill format. So the install step for Cursor or Claude Code is not a command in this repository; it is a copy plus a frontmatter edit.

The release skill has a second component: a Go CLI under release/cli/ that runs the whole pipeline. It reads a release.json at your project root, and the README gives this invocation:

go run github.com/fayazara/macos-app-skills/release/cli@latest

The go.mod at the repository root declares module github.com/fayazara/macos-app-skills with go 1.22, which is consistent with that import path. A first real use would be to copy settings-ui into your project, ask your agent for a preferences window, and compare what it produces against the reference files in that directory.

The release CLI and its eight-step pipeline

The release/ skill is the one place where this repository does more than supply reading material. The README describes the manual pipeline as version bump, archive, notarize, export, DMG creation via create-dmg, EdDSA signing via Sparkle's sign_update, appcast.xml updates, and GitHub release creation via gh. That is eight steps, and the README calls them error-prone and tedious to re-explain.

The Go CLI collapses them into one command driven by release.json. Two details are worth noting before you rely on it. First, the CLI lives in the same repository as the skills, so running it with go run against the module path fetches the latest commit rather than a tagged release; the repository shows no releases in the information available. Second, the pipeline assumes a specific distribution model: notarization, DMG packaging and a Sparkle appcast all point at an app shipped outside the Mac App Store. If you ship through the App Store, most of this skill does not apply to you, because Sparkle auto-update is explicitly framed for apps distributed outside the store.

The appcast and signing steps also imply you hold an EdDSA key pair and a Developer ID certificate. The skill covers generating the keys; it cannot remove the account and certificate requirements around them.

Where the skills stop being useful

The requirements section sets a floor of macOS 14, Xcode 15 and Swift 5.9, with macOS 26 and Xcode 26 beta needed for the liquid glass work. The README says liquid glass features have graceful fallbacks, but it does not document what those fallbacks look like in the reference files, so if you target macOS 14 or 15 you should read settings-ui/SKILL.md and the Swift files before assuming the window chrome degrades the way you want.

The larger limitation is scope. Every skill assumes a native Xcode project built with SwiftUI and AppKit. There is nothing here for Mac Catalyst, nothing for Electron or Tauri shells, and nothing for iOS or iPadOS targets that share a codebase. The macos-patterns skill exists precisely because those platforms diverge, so applying it to a cross-platform project will produce advice that fights your architecture.

A second limit is that the skills are text, not enforcement. Nothing verifies that the agent followed the pattern. If your agent ignores a SKILL.md, or loads it after it has already written the settings window, you get the same broken output as before. The repository offers no test harness, no lint rule and no build-time check for conformance.

Finally, the licence line in the README says MIT, but the repository metadata available for this project lists the licence as unknown. Treat the README statement as the project's own claim and confirm the LICENSE file before you vendor the reference Swift files into a commercial product.

How this compares with Apple's own documentation and WWDC sessions

The obvious alternative is the source material itself: Apple's developer documentation plus the WWDC session videos the README points at. The difference is retrieval, not accuracy. Apple's docs are authoritative and current, and a WWDC session on NSPanel behavior will be more complete than a SKILL.md. But an agent does not watch videos, and a documentation page does not tell it which of two APIs is the one that works for a menu bar app.

The skills sit between those two things. They are short, opinionated, and written for a reader that is a language model: macos-patterns/ is explicitly described as the skill to load proactively on any macOS project to stop the agent applying web patterns. That is a different artifact from a reference manual. It is closer to a style guide with code samples.

A second alternative is writing your own project conventions file and pointing the agent at it. That gives you exactly your team's patterns, at the cost of writing them. The value of this repository is that someone already wrote the Sparkle timing rule and the notch shape math down. If your app does not use Sparkle and has no notch overlay, a large share of that value does not transfer to you.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-05-27. That is roughly four months before today, so the repository is not stale, but it is also not being pushed to daily. No releases are available, which means there is no tagged version to pin and no changelog to read before upgrading. Because the skills are copied rather than depended on, an upgrade is a manual diff: pull the repository, compare SKILL.md files and reference Swift files against the copies in your project, and merge by hand. There is no package manager step that updates them in place.

That copy-based model has a consequence worth stating plainly. Once you copy settings-ui into your project, your copy is frozen. Improvements to the upstream skill will not reach you, and a mistake in a reference file will not be corrected for you either. If you use the Go CLI, the opposite applies: go run against the module path always resolves the latest code, so your release pipeline changes without your asking. Those two behaviours point in opposite directions, and it is worth deciding which one you want for each part.

The README states the licence is MIT. That permits reuse and modification with attribution, and it is compatible with vendoring the reference Swift files into a proprietary app, but this is not legal advice and the repository metadata does not corroborate the MIT claim. Check the actual LICENSE file before you rely on it.

Editorial conclusion

Adopt it if you already drive an AI coding agent on a native macOS codebase and keep hitting the same AppKit and xcodebuild mistakes, because the skill directories are plain markdown you can read and copy. Skip it if your app is Catalyst, Electron or iOS-only, since the content assumes SwiftUI plus AppKit targets and a real Xcode project. Before wiring it in, clone the repository and open settings-ui/SKILL.md and release/SKILL.md to confirm the reference files match your deployment path, then check whether your agent reads .agents/skills/ or needs the frontmatter adapted.

Frequently asked questions

Official sources

1. fayazara/macos-app-skills on GitHub
2. Issues
3. README