跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

os-integrations

Deep macOS integrations for a native app, such as global hotkeys, menu bar items, floating panels, window control with Accessibility, screen capture and recording, clipboard, Shortcuts and Spotlight, URL schemes, login items, a CLI, and the permissions each one needs. Use when an app must reach outside its own window or control other apps.

daveebbelaar · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add daveebbelaar/bama --skill os-integrations

技能说明


name: os-integrations description: Deep macOS integrations for a native app, such as global hotkeys, menu bar items, floating panels, window control with Accessibility, screen capture and recording, clipboard, Shortcuts and Spotlight, URL schemes, login items, a CLI, and the permissions each one needs. Use when an app must reach outside its own window or control other apps.

macOS integrations

A Mac app is a set of entry points around the system, not one window. This skill picks the API for each entry point and the permission it costs. Code for every row is in recipes.md.

Pick the API

WantAPIPermission
Global shortcut (key combo)Carbon RegisterEventHotKeyNone
Hold-to-show (hold Option, press Tab) or key remappingCGEvent.tapCreate event tapAccessibility
Watch keys without changing them (keystroke overlay)Listen-only event tapInput Monitoring (CGRequestListenEventAccess)
List other apps' windowsCGWindowListCopyWindowInfoNone (titles need Screen Recording)
Menu bar itemMenuBarExtra (SwiftUI) or NSStatusItemNone
Live status in the menu bar (a timer, a sync)MenuBarExtra with a changing label. Live Activities on a Mac only mirror a paired iPhoneNone
Desktop and Notification Center widgetsWidgetKit extension target (Xcode build, like App Intents)None
Find the app's content in SpotlightCore Spotlight CSSearchableIndexNone
Preview the app's own file type in Finder (Space)Quick Look preview extensionNone
Menu-bar-only app, no Dock iconLSUIElement = YES in Info.plistNone
Spotlight-style panel that keeps the other app in frontNSPanel with .nonactivatingPanelNone
Move and resize other apps' windowsAXUIElement (kAXPositionAttribute, kAXSizeAttribute)Accessibility
Paste into the front appWrite NSPasteboard, then post Command-V with CGEventAccessibility
ScreenshotScreenCaptureKit SCScreenshotManagerScreen Recording
Window thumbnailsSCScreenshotManager with an SCContentFilter per windowScreen Recording
Screen recording to MP4SCStream + SCRecordingOutput (AVAssetWriter when you edit frames)Screen Recording, Microphone
Clipboard historyPoll NSPasteboard.general.changeCountNone
Text in imagesVision RecognizeTextRequestNone
Launch at loginSMAppService.mainApp.register()User approves once
Links from scripts, Stream Deck, RaycastCFBundleURLTypes + .onOpenURLNone
Shortcuts app and Spotlight actionsAppIntent (App Shortcuts are not supported on macOS). A result or confirmation view is a snippetNone
Agent or script reads and changes dataThe app binary as a CLI, talking to the running app (agent-cli skill)None
A CLI that writes plain files or its own SQLite tells the app to reloadDarwin notification (notify_post)None
Keep the Mac awakeIOPMAssertionCreateWithNameNone
System statshost_statistics64, proc_pid_rusage, IOPSCopyPowerSourcesInfoNone
Audio devicesCoreAudio AudioObjectGetPropertyDataNone
Toggle dark mode and other system settingsApple Events to System EventsAutomation
NotificationsUNUserNotificationCenterUser approves once
Dock menuapplicationDockMenu(_:) in the app delegateNone
Services and Share menuNSServices in Info.plist, ShareLinkNone

Prefer the row with no permission when two rows solve the same job.

Permissions

  • Ask at the moment of use. Explain in one line what breaks without it. The exception: an app whose core job needs the permission (a window manager needs Accessibility) shows its permissions page on first launch.
  • Show the state of every permission on one Settings page, with a button that opens the right pane: x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility (or Privacy_ScreenCapture, Privacy_AllFiles).
  • The user grants it in System Settings, and nothing calls your app back. Check every 1 to 2 seconds while a permission is missing or a view that shows it is open. Otherwise check every 20 seconds, with a timer tolerance. Check once more right when such a view opens.
  • Every NS...UsageDescription key (camera, microphone, Apple Events) must be in Info.plist before the first request, or the app crashes.

Menu bar items, widgets, and snippets

  • A menu bar item shows a menu, unless the feature is too complex for one. Its icon is a template image (an SF Symbol works). People can turn it off in Settings, and nothing is reachable only through it: the Dock menu and the main window offer the same actions. MenuBarExtra already works with keyboard navigation; an NSStatusItem that opens a custom window must too (WWDC26-289).
  • A widget shows one idea from the app's purpose, with content that changes through the day. Sizes small, medium, large, and extra large. On the desktop it renders vibrant and nearly gray, so it must read without color. Standard margins 16 pt. A click deep-links to the exact place; buttons and toggles in it run App Intents. Never a whole app squeezed into a widget.
  • A snippet is the view an App Intent shows in Spotlight, Siri, or Shortcuts: a result (with Done) or a confirmation (Cancel plus a button that names the action, never "OK"). At most 400 pt tall, readable in light and dark, and clear without the spoken text.
  • Badge the Dock icon only with a count of unread notifications.

Signing keeps grants

macOS stores Accessibility and Screen Recording grants per code signature and path. To keep them across rebuilds:

  • Sign with one stable "Apple Development" certificate. Ad hoc signing asks again after every build.
  • Install to the same path every time (/Applications/<App>.app or ~/Applications/<App>.app).
  • No App Sandbox for apps that use Accessib
阅读完整来源 ↗