ReddRadar
Agent skill
macos-app-design
Use when designing or building native macOS applications with SwiftUI or AppKit. Triggers on menu bar structure, keyboard shortcuts, multi-window behavior, Liquid Glass design system, macOS Tahoe/Sequoia, sidebar navigation, toolbar design, app icons, SF Symbols, or making an app feel like a "good Mac citizen."
Install this agent skill to your Project
npx add-skill https://github.com/petekp/agent-skills/tree/main/skills/macos-app-design
SKILL.md
macOS App Design & Development
Guide for designing and implementing native-feeling, "good Mac citizen" apps: fast, elegant, accessible, and deeply integrated with macOS workflows.
Two Rules That Beat Everything Else
- Prefer system components and conventions over bespoke UI—fastest path to "feels right on Mac"
- If you customize bars, backgrounds, borders, or control chrome: stop and justify it
Quick Reference: Mac Citizen Checklist
| Area | Requirement |
|---|---|
| Menu Bar | Standard layout (App/File/Edit/View/Window/Help), ⌘, for Settings |
| Keyboard | Every primary command reachable via keyboard, standard shortcuts work |
| Windows | Resize fluidly, support multiple windows, respect fullscreen/minimize |
| Sidebars | Top-level navigation, scannable items, content extends behind |
| Toolbars | Group by function/frequency, demote secondary to "more" menu |
| Text | Use system text components, standard editing behaviors |
| Accessibility | VoiceOver labels, full keyboard navigation, Reduced Motion support |
Liquid Glass Quick Rules
Do:
- Use for navigation/controls layer (toolbars, sidebars, bars)
- Let system components provide built-in behaviors
Don't:
- Apply to content layer (tables, lists, document content)
- Stack "glass on glass"
App Archetypes
Identify your app type first:
- Document-based: Files as primary units (open/save/duplicate)
- Library + editor: Sidebar lists items, detail in main area
- Utility: Single window, optional menu bar
- Menu-bar app: Lives in menu bar, minimal UI
- Pro tool: Dense, power-user workflows
Deliverables Before Building
- App archetype identified
- Information architecture (sidebar structure, navigation, window model)
- Command map (menus + keyboard shortcuts for every major feature)
- State + data model (persistence, undo/redo, concurrency)
- Accessibility plan (VoiceOver, keyboard, contrast, reduce motion)
Full Reference
For complete design system details, Icon Composer workflow, SF Symbols guidance, evaluation rubrics, and Definition of Done checklist:
See: references/macos-design-guide.md
Common Mistakes
| Mistake | Fix |
|---|---|
| Missing menu bar commands | Every feature in menus with keyboard shortcuts |
| Settings outside App menu | Always ⌘, opening from App menu |
| Custom text components | Use system text for Mac editing ecosystem |
| Toolbar overload | Demote secondary actions, group by function |
| Glass on content | Reserve Liquid Glass for navigation layer only |
| Breaking standard shortcuts | Never override ⌘C, ⌘V, ⌘Z, etc. |
| Single-window only | Support multiple windows when it benefits workflows |
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
petekp/agent-skills
multi-model-meta-analysis
Synthesize outputs from multiple AI models into a comprehensive, verified assessment. Use when: (1) User pastes feedback/analysis from multiple LLMs (Claude, GPT, Gemini, etc.) about code or a project, (2) User wants to consolidate model outputs into a single reliable document, (3) User needs conflicting model claims resolved against actual source code. This skill verifies model claims against the codebase, resolves contradictions with evidence, and produces a more reliable assessment than any single model.
petekp/agent-skills
capture-learning
Analyze recent conversation context and capture learnings to project knowledge files (for project-specific insights) or skills/commands/subagents (for cross-project patterns). Use when the user asks to "capture this learning", "update the docs with this", "remember this for next time", "document this issue", "add this to CLAUDE.md", "save this knowledge", or "update project knowledge". Also triggers after resolving build/setup issues, discovering non-obvious patterns, or completing debugging sessions with valuable insights.
petekp/agent-skills
optimize-agent-docs
Build a retrieval-optimized knowledge layer over agent documentation in dotfiles (.claude, .codex, .cursor, .aider). Use when asked to "optimize docs", "improve agent knowledge", "make docs more efficient", or when documentation has accumulated and retrieval feels inefficient. Generates a manifest mapping task-contexts to knowledge chunks, optimizes information density, and creates compiled artifacts for efficient agent consumption.
petekp/agent-skills
agent-changelog
Compile an agent-optimized changelog by cross-referencing git history with plans and documentation. Use when asked to "update changelog", "compile history", "document project evolution", or proactively after major milestones, architectural changes, or when stale/deprecated information is detected that could confuse coding agents.
petekp/agent-skills
literate-guide
Create a narrative guide to a codebase or feature in the style of Knuth's Literate Programming — code and prose interwoven as a single essay, ordered for human understanding rather than compiler needs. Use when the user asks to 'explain this codebase as a story', 'write a literate guide', 'create a narrative walkthrough', 'tell the story of this code', 'Knuth-style documentation', 'weave a guide for this feature', or when they want deep, readable documentation that treats the program as literature. Also trigger when someone wants a document that a thoughtful reader could follow from start to finish and come away understanding both WHAT the code does and WHY every design choice was made.
petekp/agent-skills
autonomous-agent-readiness
Assess a codebase's readiness for autonomous agent development and provide tailored recommendations. Use when asked to evaluate how well a project supports unattended agent execution, assess development practices for agent autonomy, audit infrastructure for agent reliability, or improve a codebase for autonomous agent workflows. Triggers on requests like "assess this project for agent readiness", "how autonomous-ready is this codebase", "evaluate agent infrastructure", or "improve development practices for agents".
Didn't find tool you were looking for?