macos-pimp
Active router for ALL macOS automation requests — classifies and routes to the correct macos-* skill before any response. Use when anything involves macOS desktop automation, AppleScript, Peekaboo, GUI control, window management, or AI desktop agents.
| Model | Source |
|---|---|
| sonnet | pack: macos-automation |
Full Reference
This is not optional. This is not negotiable. You cannot skip this.
macOS Pimp
Section titled “macOS Pimp”The orchestration layer for all macOS desktop automation. Not documentation — an active router. Every macOS automation request flows through this routing table before any response.
Mandatory Announcement — FIRST OUTPUT before anything else:
┏━ 🖥 macos-pimp ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓┃ [one-line description of what request/routing] ┃┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛No exceptions. Box frame first, then route.
Quick Context
Section titled “Quick Context”The macos-automation pack covers three layers of desktop automation: script execution (AppleScript/JXA), GUI automation (Peekaboo), and AI agent orchestration. 7 skills total — 3 reference skills with deep docs, 2 workflow/utility skills, 1 creative skill, plus this router.
Routing Table
Section titled “Routing Table”Classify the request. Invoke the matching skill. No response before invocation.
| Request Pattern | Skill |
|---|---|
| Screenshot, screen capture, see UI elements, list apps/windows | peekaboo |
| Click, type, press keys, scroll, swipe, drag, move cursor, paste | peekaboo |
| Window management, app launch/quit, menu click, dock, dialog, Spaces | peekaboo |
| Peekaboo MCP server, tool filtering, bridge, daemon | peekaboo |
| Peekaboo install, permissions, config, providers | peekaboo |
| Run AppleScript/JXA via MCP, execute KB script by ID, script search | macos-automator |
| Search scripting knowledge base, browse 492 tips, find scripts | macos-automator |
| Placeholder substitution, parameterized scripts, MCP_INPUT | macos-automator |
| macos-automator-mcp install, Claude Desktop config for scripts | macos-automator |
| AppleScript syntax, tell blocks, handlers, variables, error handling | applescript-reference |
| JXA syntax, ObjC bridge, $.NS* classes, JavaScript for Automation | applescript-reference |
| App dictionary patterns — automate Safari, Chrome, Mail, Calendar, etc. | applescript-reference |
| applescript-mcp raw bridge, osascript pass-through, SSH remote | applescript-reference |
| Generate AppleScript/JXA from description, validate script, test script | applescript-forge |
| Multi-step automation workflow, compose tools, .peekaboo.json scripts | macos-workflow |
| See→Act→Verify loop, automation pipeline, error recovery patterns | macos-workflow |
| Build AI desktop agent, configure agent model, tool chain setup | macos-agent-builder |
| MCP config export for agents, safety/guardrails, agent patterns | macos-agent-builder |
| Compare automation tools, “which tool for this?”, general macOS help | macos-automation-expert agent |
Tool Selection Logic
Section titled “Tool Selection Logic”Three layers, each with distinct strengths:
| Layer | Tool | Best For |
|---|---|---|
| Script | macos-automator / applescript-mcp | App-specific automation via dictionaries, data extraction, system config |
| GUI | Peekaboo | Visual interaction, clicking buttons, reading UI state, screenshots |
| Agent | Peekaboo agent mode | NL-driven tasks, multi-step with verification, unknown UI layouts |
Decision flow:
- Can the app be scripted? (has AppleScript dictionary) → Script layer
- Need to interact with UI elements visually? → GUI layer (Peekaboo)
- Unknown UI, need to explore and decide? → Agent layer
- Multi-step combining script + GUI? →
macos-workflow(composes both)
State Detection
Section titled “State Detection”Before routing, check what’s available:
| Check | Command | Result |
|---|---|---|
| Peekaboo installed? | which peekaboo | If missing, suggest install before GUI tasks |
| Permissions granted? | peekaboo list permissions | Accessibility + Screen Recording needed |
| macos-automator available? | npx -y @steipete/macos-automator-mcp@latest --help | For script execution tasks |
| macOS version? | sw_vers -productVersion | Peekaboo requires macOS 15.0+ |
| Architecture? | uname -m | Peekaboo requires arm64 (Apple Silicon) |
| State | Action |
|---|---|
| Peekaboo missing, GUI task requested | Route to peekaboo setup.md first |
| Permissions missing | Guide permission grant before proceeding |
| Intel Mac + GUI task | Fall back to Script layer (Peekaboo arm64-only) |
| Everything available | Route directly to target skill |
Cross-Cutting Rules
Section titled “Cross-Cutting Rules”- If request spans multiple layers, invoke the PRIMARY skill first (closest to the core question)
- “Automate this app” without specifics → check if app has AppleScript dictionary first
- “Click this button” → always Peekaboo, never script layer
- “Get data from this app” → script layer first (faster, more reliable), GUI fallback
- “Build an agent for X” →
macos-agent-builderfirst, it chains to tool skills
Chaining Patterns
Section titled “Chaining Patterns”| User Says | Chain |
|---|---|
| ”Automate sending emails in Mail” | applescript-reference (app-dictionaries.md) → applescript-forge |
| ”Click the Save button in Photoshop” | peekaboo (interaction.md) |
| “Build a workflow to export Safari tabs to a spreadsheet” | macos-workflow → peekaboo + applescript-reference |
| ”Create an AI agent that fills out forms” | macos-agent-builder → peekaboo (agent.md) |
| “Write a script to resize all Finder windows” | applescript-forge → applescript-reference (app-dictionaries.md) |
| “Set up desktop automation for my project” | Route to peekaboo setup.md + macos-automator setup.md |
Priority Order (when multiple skills apply)
Section titled “Priority Order (when multiple skills apply)”- macos-workflow — if multi-step, composing tools
- peekaboo — if GUI interaction needed
- macos-automator — if running scripts via MCP
- applescript-reference — if writing/understanding scripts
- applescript-forge — if generating scripts
- macos-agent-builder — if building agent configs
What This Skill Does NOT Route
Section titled “What This Skill Does NOT Route”- General coding (even on macOS) → shepherd handles
- iOS/iPadOS automation → not macOS desktop
- Terminal/shell scripting without GUI/AppleScript → not macOS automation
- Homebrew package management → not macOS automation
Hard Rules
Section titled “Hard Rules”- Never respond about macOS automation before invoking the target skill
- No summarizing, planning to invoke, or explaining what you’re about to do
- If two skills apply, invoke the FIRST one — it chains to the next
- If unclear, ask ONE clarifying question, then route
- The skill’s content has the verified facts — always defer to it
- ALWAYS check State Detection before routing GUI tasks