# macos-patterns

Guides native macOS app work with menu bar UI, windows, focus behaviour and platform-specific APIs.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 670 installs · ★ 681
- Author: fayazara
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/fayazara/macos-app-skills/tree/HEAD/macos-patterns/SKILL.md
- Updated: 2026-05-27
- HTML: https://affpapa.org/en/nevibecode/skills/macos-patterns

## What it does

macos-patterns gives the agent native macOS guidance for application code across SwiftUI and AppKit. It covers `MenuBarExtra`, `NSStatusItem`, `NSPopover`, application activation policy, `NSPanel`, window levels and Spaces behaviour.

The skill addresses cases where web assumptions produce incorrect macOS code: window ordering is not just `z-index`, and screen coordinates start at the bottom left. It also covers focus settings, click-through floating panels and screen-capture exclusion with `sharingType`. If your design starts from a web window model, that is a reason to check it before writing the implementation.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add fayazara/macos-app-skills --skill macos-patterns -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/macos-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/macos-patterns/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add fayazara/macos-app-skills --skill macos-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/macos-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add fayazara/macos-app-skills --skill macos-patterns -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/macos-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install fayazara/macos-app-skills macos-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/macos-patterns/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add fayazara/macos-app-skills --skill macos-patterns -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/fayazara/macos-app-skills --path macos-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/macos-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add fayazara/macos-app-skills --skill macos-patterns -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/fayazara/macos-app-skills/tree/HEAD/macos-patterns/SKILL.md

## When to use it
- build a menu bar app with `MenuBarExtra`
- configure `NSStatusItem` for a custom menu
- show a floating panel without taking focus
- toggle Dock visibility for an app
- keep a window visible over full-screen apps

## Example prompts
- “Create a macOS menu bar app with a settings window.”
- “Add a floating macOS panel that does not take focus and lets clicks pass through.”
- “Explain how to set window levels and show a window across all Spaces on macOS.”

## Similar
- [macos-design-guidelines](https://affpapa.org/en/nevibecode/skills/macos-design-guidelines.md) — skill · 4300 installs
- [macos-golden-gate-design](https://affpapa.org/en/nevibecode/skills/macos-golden-gate-design.md) — skill · 23 installs
- [macos-development](https://affpapa.org/en/nevibecode/skills/macos-development.md) — skill · 1600 installs
- [axiom-macos](https://affpapa.org/en/nevibecode/skills/axiom-macos.md) — skill · 1300 installs
- [build-macos-apps](https://affpapa.org/en/nevibecode/plugins/build-macos-apps.md) — plugin · ★ 7596
- [appkit-interop](https://affpapa.org/en/nevibecode/skills/appkit-interop.md) — skill · 60 installs

From the same set: [fayazara/macos-app-skills](https://affpapa.org/en/nevibecode/by/fayazara/macos-app-skills.md) — 6 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md