macos-notifications
Skill11 starsChanged 3 months agoMITView on GitHub
Use when adding or reviewing macOS user notifications — UNUserNotificationCenter permission flow, categories and action buttons, click routing through the delegate, foreground presentation, and rules that keep notifications from becoming spam.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- wyattjoh/skillstheir own version, first seen Sep 27, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- wyattjoh/skills★ 3same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository39 other files it gives its agents.
- agent-starter-packSkill
- agent-state-machineSkill
- local-ai-ollamaSkill
- apple-hig-command-paletteSkill
- apple-hig-empty-statesSkill
- apple-hig-feedback-statusSkill
- apple-hig-inspectorsSkill
- apple-hig-macos-window-layoutSkill
- apple-hig-search-filteringSkill
- apple-hig-settingsSkill
- apple-hig-sf-symbolsSkill
- apple-hig-sidebarsSkill
- apple-hig-toolbarsSkill
- apple-hig-typographySkill
- blog-post-publishingSkill
- social-post-kitSkill
- color-principlesSkill
- kika-design-systemSkill
- emergency-switch-appSkill
- product-hunt-polish-reviewSkill
- docs-updateSkill
- project-folder-cleanupSkill
- between-runs-auditSkill
- explain-new-projectSkill
- new-project-gateSkill
- old-project-auditSkill
- project-catch-upSkill
- project-workflowSkill
- project-worth-my-timeSkill
- butterfly-effectSkill
- spreadSkill
- tilSkill
- apple-app-intentsSkill
- macos-app-distribution-dmgSkill
- macos-clipboard-pasteboardSkill
- macos-global-shortcutsSkill
- macos-launch-at-loginSkill
- macos-menubar-swiftuiSkill
- macos-permissions-privacySkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use this skill when the user says:
- Very specific: line 23
Do not use this skill for push/APNs server setup, iOS-specific notification UI, or in-window status banners (those are in-app feedback — …
- Distinctive: line 52
If the app fires more than a handful of notifications an hour, the model is wrong — batch them (one summary notification) or drop the …
- Distinctive: line 84
Pre-explain: Before the system prompt, the UI has already made the value obvious ("Runs can take a while — want a notification when one …
- Very specific: line 85
The system prompt fires once: If the user denies, requestAuthorization won't re-prompt — your only path is Settings, so keep a …
- Distinctive: line 135
Title = what happened; body = the one detail that matters: No app name in the title (the system shows it), no exclamation marks.
- Very specific: line 209
Check the per-type toggles in your own post() path — isAuthorized() handles the system layer, these handle taste.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
macOS Notifications
Notify only when the user benefits from being pulled back — task finished, task failed, something needs their decision — and make every notification click land on the exact screen that resolves it.
When to use
Use this skill when the user says:
- notify when done / notification when the task finishes
- desktop notification / system notification
UNUserNotificationCenter/UserNotifications- notification permission
- notification actions / buttons
- clicking the notification should open …
- background job finished, tell the user
- reminder from a macOS app
Do not use this skill for push/APNs server setup, iOS-specific notification UI, or in-window status banners (those are in-app feedback — see apple-hig-feedback-status).
Core rule
Notify only when being pulled back saves the user something.
Every notification answers: what happened, and what happens
when I click it.When to notify — and when not
Worth a notification (the app is likely in the background):
Completed long task finished → click opens the result
Failed long task failed → click opens the error + retry
Blocked waiting on input/approval → click opens the decision
Needs review output ready to check → click opens the review view
Reminder user-scheduled → click opens the itemNot worth one:
- Progress ticks, intermediate states, "still working…"
- Anything the user is currently looking at (foreground, same screen)
- Marketing, tips, "did you know" — never
- Errors the app can recover from by itself
If the app fires more than a handful of notifications an hour, the model is wrong — batch them (one summary notification) or drop the low-value ones.
Permission
Request at the moment of need, with context, never at first launch:
import UserNotifications
enum Notifier {
// Call right after the user does the thing that will later notify —
// e.g. starts their first long-running task.
static func requestPermission() async -> Bool {
let center = UNUserNotificationCenter.current()
do {
return try await center.requestAuthorization(options: [.alert, .sound, .badge])
} catch {
return false
}
}
// Never assume — settings can change behind the app's back.
static func isAuthorized() async -> Bool {
let settings = await UNUserNotificationCenter.current().notificationSettings()
return settings.authorizationStatus == .authorized
|| settings.authorizationStatus == .provisional
}
}Rules:
- Pre-explain. Before the system prompt, the UI has already made the value obvious ("Runs can take a while — want a notification when one finishes?"). The system dialog should never be a surprise.
- The system prompt fires once. If the user denies,
requestAuthorizationwon't re-prompt — your only path is Settings, so keep a "notifications are off" state in your own Settings pane with a deep link:
// Opens System Settings > Notifications
NSWorkspace.shared.open(
URL(string: "x-apple.systempreferences:com.apple.Notifications-Settings.extension")!)- Consider
.provisionalfor low-stakes apps: notifications deliver quietly to Notification Center without any prompt, and the user promotes or demotes them from there.
Sending, with categories and actions
Define categories once at launch; they give notifications buttons and give clicks a routable identity:
enum TaskNotification {
static let category = "task.finished"
static let retryAction = "task.retry"
static func registerCategories() {
let retry = UNNotificationAction(identifier: retryAction,
title: "Retry",
options: [])
let category = UNNotificationCategory(identifier: category,
actions: [retry],
intentIdentifiers: [])
UNUserNotificationCenter.current().setNotificationCategories([category])
}
static func post(taskID: String, title: String, body: String) async {
guard await Notifier.isAuthorized() else { return }
let content = UNMutableNotificationContent()
content.title = title // "Export failed"
content.body = body // "3 of 120 items didn't convert."
content.sound = .default
content.categoryIdentifier = category
content.userInfo = ["taskID": taskID] // routing payload
content.threadIdentifier = "tasks" // groups related ones
let request = UNNotificationRequest(identifier: taskID, // same ID = replaces
content: content,
trigger: nil) // deliver now
try? await UNUserNotificationCenter.current().add(request)
}
}Details that matter:
- Title = what happened; body = the one detail that matters. No app name in the title (the system shows it), no exclamation marks.
- Reusing the request identifier replaces the previous notification — the right behavior for a task that goes
blocked → completed. threadIdentifierkeeps a burst of task notifications stacked instead of carpeting the screen.- Failure notifications include the recovery path — a Retry action button, and a click target that shows the error.
Click routing — the delegate
Without a delegate, clicks just activate the app and notifications hide while the app is frontmost. Set it early (before any notification can arrive):
import AppKit
import UserNotifications
final class AppDelegate: NSObject, NSApplicationDelegate,
UNUserNotificationCenterDelegate {
func applicationDidFinishLaunching(_ notification: Notification) {
UNUserNotificationCenter.current().delegate = self
TaskNotification.registerCategories()
}
// Route the click to the exact screen that resolves it.
func userNotificationCenter(_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse) async {
let info = response.notification.request.content.userInfo
guard let taskID = info["taskID"] as? String else { return }
switch response.actionIdentifier {
case TaskNotification.retryAction:
await TaskStore.shared.retry(taskID)
default: // plain click
NSApp.activate(ignoringOtherApps: true)
Router.shared.open(.taskDetail(taskID))
}
}
// Decide what happens if the app is frontmost when one arrives.
// Default: show nothing. Menu bar / background-style apps usually
// still want the banner; window apps showing that screen don't.
func userNotificationCenter(_ center: UNUserNotificationCenter,
willPresent notification: UNNotification) async
-> UNNotificationPresentationOptions {
[.banner, .sound]
}
}
// SwiftUI wiring:
@main
struct MyApp: App {
@NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
var body: some Scene { /* … */ }
}Also clean up after yourself — when the user opens the screen a notification points at, remove it from Notification Center:
UNUserNotificationCenter.current()
.removeDeliveredNotifications(withIdentifiers: [taskID])Settings pane
Give users per-type control inside the app, on top of the system switch:
Notifications
Notify me when:
[x] A run completes
[x] A run fails or is blocked
[ ] A daily summary is ready
Notifications are disabled in System Settings. Open Settings… (only when denied)Check the per-type toggles in your own post() path — isAuthorized() handles the system layer, these handle taste.
Checklist
[ ] Permission requested at the moment of need, with a pre-explanation
[ ] Denied state visible in app Settings with a System Settings deep link
[ ] Delegate set in applicationDidFinishLaunching, categories registered
[ ] Every notification click opens the exact relevant screen
[ ] Failure notifications carry a recovery action (Retry / Show error)
[ ] Identifiers reused so state changes replace, not stack
[ ] threadIdentifier groups bursts; no notification-per-tick spam
[ ] Delivered notifications removed once the user has seen the thing
[ ] Per-type toggles in app SettingsManual test
- Fresh install → trigger the notifying action → pre-explanation, then system prompt.
- Background the app, finish a task → notification arrives; click → app opens on that task.
- Fail a task → notification has Retry; Retry works without opening the app.
- Deny permission in System Settings → app Settings shows the off state + working deep link.
- Fire 5 task notifications → they stack as one group, latest state per task wins.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

