playbooks

home / skills / fusengine / agents / macos

macos skill

/plugins/swift-apple-expert/skills/macos

This skill streamlines macOS desktop and menu bar app development by guiding window management, notarization, and AppKit integration.

npx playbooks add skill fusengine/agents --skill macos

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
2.3 KB
---
name: macos
description: macOS platform-specific development with menu bar apps, window management, AppKit integration, and notarization. Use when building Mac apps, creating menu bar extras, or distributing outside App Store.
versions:
  macos: 26
  xcode: 26
user-invocable: false
references: references/app-structure.md, references/build-tools.md, references/appkit-integration.md, references/notarization.md
related-skills: swift-core, swiftui-core, mcp-tools, build-distribution
---

# macOS Platform

macOS-specific development with window management and distribution tools.

## Agent Workflow (MANDATORY)

Before ANY implementation, use `TeamCreate` to spawn 3 agents:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing macOS patterns
2. **fuse-ai-pilot:research-expert** - Verify latest macOS 26 docs via Context7/Exa
3. **mcp__XcodeBuildMCP__build_macos** - Build for macOS validation

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

## Overview

### When to Use

- Building Mac desktop applications
- Creating menu bar apps (MenuBarExtra)
- Multi-window applications
- Keyboard shortcuts and menus
- Notarization for distribution
- AppKit integration

### Why macOS Skill

| Feature | Benefit |
|---------|---------|
| MenuBarExtra | Background utility apps |
| Window management | Multi-window support |
| Keyboard shortcuts | Power user productivity |
| Notarization | Gatekeeper-safe distribution |

---

## MCP Tools Available

### Build Tools
- `build_macos` - Build for macOS
- `build_run_macos` - Build and launch
- `test_macos` - Run macOS tests
- `launch_mac_app` - Start built app
- `stop_mac_app` - Terminate app

---

## Reference Guide

| Need | Reference |
|------|-----------|
| MenuBarExtra, Settings, Windows | [app-structure.md](references/app-structure.md) |
| XcodeBuildMCP macOS tools | [build-tools.md](references/build-tools.md) |
| NSViewRepresentable, menus | [appkit-integration.md](references/appkit-integration.md) |
| Code signing, notarization | [notarization.md](references/notarization.md) |

---

## Best Practices

1. **Keyboard shortcuts** - Support power users
2. **Menu bar integration** - For utility apps
3. **Multiple windows** - Use WindowGroup/Window
4. **Settings window** - Use Settings scene
5. **Notarization** - Required for distribution
6. **Sandbox** - Enable for App Store

Overview

This skill covers macOS platform-specific development focused on menu bar apps, multi-window management, AppKit integration, and notarization. It guides building, testing, and distributing Mac apps, including background utilities and App Store or Gatekeeper-safe packaging.

How this skill works

Before coding, spawn three supporting agents to explore the codebase, verify macOS 26 docs, and perform macOS builds for validation. Use available MCP build tools to compile, run, test, and launch the app, then run a final validation agent to confirm expected behavior and distribution readiness.

When to use it

  • Building Mac desktop applications with native UI and AppKit integration
  • Creating menu bar extras or background utility apps
  • Implementing multi-window apps, WindowGroup, or custom window management
  • Adding keyboard shortcuts, menus, and Settings scene support
  • Preparing code signing, sandboxing, and notarization for distribution

Best practices

  • Start by running three agents: explore the codebase, verify docs, and perform a build for early feedback
  • Support keyboard shortcuts and conventional macOS menus for power user workflows
  • Use WindowGroup/Window and Settings scene for multi-window and preference UIs
  • Integrate MenuBarExtra for lightweight background utilities and quick-access features
  • Enable sandboxing for App Store builds and follow notarization steps for outside-App-Store distribution

Example use cases

  • Implementing a MenuBarExtra that shows status and quick actions without a main dock icon
  • Building a multi-window editor that preserves window state and supports keyboard shortcuts
  • Integrating an AppKit NSViewRepresentable for custom native controls inside SwiftUI
  • Running macOS CI tasks to build, test, and launch a release candidate before notarization
  • Preparing a notarized, Gatekeeper-compliant build for distribution outside the App Store

FAQ

Which agents should I run before any implementation?

Always create three agents: one to analyze the existing codebase, one to verify the latest macOS documentation, and one to perform an initial macOS build for validation.

When is notarization required?

Notarization is required for distributing apps outside the App Store to satisfy Gatekeeper on recent macOS versions.