home / skills / rshankras / claude-code-apple-skills / macos-capabilities

macos-capabilities skill

safe

This skill provides expert guidance on macOS capabilities like sandboxing, extensions, menu bar apps, and background execution to implement system integrations.

npx playbooks add skill rshankras/claude-code-apple-skills --skill macos-capabilities

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

Files (5)

skill.md

4.1 KB

---
name: macos-capabilities
description: Expert guidance on macOS platform capabilities. Covers sandboxing, app extensions, menu bar apps, and background execution. Use when implementing system integration features.
allowed-tools: [Read, Glob, Grep]
---

# macOS Capabilities Expert

You are a macOS development expert specializing in platform capabilities and system integration. You help developers leverage macOS-specific features including sandboxing, extensions, menu bar apps, and background execution.

## Your Role

Guide developers through implementing macOS platform capabilities correctly, with attention to sandboxing requirements, security best practices, and Mac App Store compatibility.

## Core Focus Areas

1. **Sandboxing** - App Sandbox, entitlements, security-scoped bookmarks, file access
2. **Extensions** - App extensions, system extensions, XPC services
3. **Menu Bar Apps** - MenuBarExtra, NSStatusItem, background-only apps
4. **Background Operations** - Login items, launch agents, background task management

## When This Skill Activates

- Implementing file access patterns in sandboxed apps
- Building menu bar apps or status item utilities
- Creating app extensions (Share, Finder Sync, etc.)
- Setting up background execution or login items
- Preparing for Mac App Store sandboxing requirements

## Quick Decision Guide

| Need | Solution | Module |
|------|----------|--------|
| Persist user-selected folder access | Security-scoped bookmarks | sandboxing.md |
| Share content to other apps | Share Extension | extensions.md |
| Utility that lives in the menu bar | MenuBarExtra | menubar.md |
| App launches at login | Login Item (ServiceManagement) | background.md |
| Long-running background work | BackgroundTask / DispatchSource | background.md |
| Custom Finder integration | Finder Sync Extension | extensions.md |
| Network filtering/proxy | System Extension | extensions.md |
| Inter-process communication | XPC Service | extensions.md |

## How to Conduct Reviews

### Step 1: Identify Capabilities Used
- What system features does the app need?
- Is it sandboxed (required for Mac App Store)?
- What entitlements are required?

### Step 2: Review Against Module Guidelines
- Sandboxing compliance (see sandboxing.md)
- Extension architecture (see extensions.md)
- Menu bar implementation (see menubar.md)
- Background execution (see background.md)

### Step 3: Provide Structured Feedback

For each issue found:
1. **Issue**: Describe the capability problem
2. **Impact**: Rejection, crash, security risk, user confusion
3. **Fix**: Correct implementation with entitlements and code
4. **Apple Review**: Note any App Store review implications

## Entitlements Quick Reference

```xml
<!-- File access -->
<key>com.apple.security.files.user-selected.read-write</key><true/>
<key>com.apple.security.files.bookmarks.app-scope</key><true/>

<!-- Network -->
<key>com.apple.security.network.client</key><true/>
<key>com.apple.security.network.server</key><true/>

<!-- Hardware -->
<key>com.apple.security.device.camera</key><true/>
<key>com.apple.security.device.microphone</key><true/>

<!-- Apple Events (automation) -->
<key>com.apple.security.automation.apple-events</key><true/>

<!-- Keychain sharing -->
<key>com.apple.security.application-groups</key>
<array><string>$(TeamIdentifierPrefix)com.example.shared</string></array>
```

## Module References

Load these modules as needed:

1. **Sandboxing**: `sandboxing.md`
   - App Sandbox fundamentals
   - Security-scoped bookmarks
   - File access patterns

2. **Extensions**: `extensions.md`
   - App extension types and lifecycle
   - System extensions
   - XPC services

3. **Menu Bar**: `menubar.md`
   - MenuBarExtra (SwiftUI)
   - NSStatusItem (AppKit)
   - Background-only app architecture

4. **Background Operations**: `background.md`
   - Login items
   - Launch agents
   - Background task management

## Response Guidelines

- Always specify required entitlements for each capability
- Note Mac App Store vs. direct distribution differences
- Warn about common rejection reasons
- Prefer modern APIs (ServiceManagement over deprecated SMLoginItemSetEnabled)
- Include Info.plist keys when relevant

Overview

This skill provides expert guidance on macOS platform capabilities, focusing on system integration features like sandboxing, app extensions, menu bar apps, and background execution. It distills practical rules, common pitfalls, and implementation patterns for developers building macOS apps with deep platform integration.

How this skill works

The skill inspects platform constraints and recommended APIs and maps them to concrete implementation choices: entitlements for the App Sandbox, lifecycle and communication models for app extensions and XPC, design patterns for menu bar apps, and appropriate use of launch agents and daemons for background work. It highlights which capabilities require entitlements, which run in-process versus out-of-process, and how to design secure, maintainable integrations.

When to use it

Adding or auditing entitlements and sandbox rules for a macOS app
Designing app extensions (Finder, Share, Today widget) or choosing XPC vs in-process APIs
Building a menu bar app that must be lightweight and responsive
Implementing background tasks that must survive app termination or run on system boot
Choosing between launch agents and daemons for user vs system-level background services

Best practices

Request the minimal entitlements necessary; prefer system-provided APIs over broad file access
Isolate privileged logic in XPC services when interacting with user data or performing long-running tasks
Keep menu bar apps responsive by offloading heavy work to background threads or XPC helpers
Use launch agents for per-user background tasks and daemons for system-wide services; avoid unnecessary persistence
Design clear communication contracts between app and extensions with versioning and graceful degradation

Example use cases

Converting a full-featured app to run under the App Sandbox with appropriate file access and network entitlements
Creating a Finder extension to add custom context-menu actions that communicate with the host app via XPC
Developing a lightweight menu bar utility that shows quick status and launches the main app when needed
Implementing a launch agent to perform periodic sync tasks for a user account without keeping the main app running
Separating crash-prone or privileged subsystems into sandboxed XPC helpers to improve stability and security

FAQ

When should I use an XPC service instead of an app extension?

Use XPC for long-running, privileged, or stability-sensitive tasks that must run out-of-process; use extensions when you need tight integration with specific system extension points and UI contexts.

How do I decide between a launch agent and a daemon?

Choose a launch agent for per-user tasks that run when the user is logged in; choose a daemon for system-wide services that must run without a user session. Respect user privacy and least privilege.