Summary

Add a bundled Zeph skill to .zeph/skills/os-automation/ for executing OS-level automation
tasks on macOS and Windows using only built-in OS tools — no third-party binaries.

Motivation

Common developer workflow automations (notifications, screenshots, clipboard management, app
launching, WiFi control, scheduled tasks) currently require dropping to raw shell commands that
the agent has to compose ad-hoc. A dedicated skill provides a structured, discoverable playbook
per platform with proper OS detection.

Structure

Following the existing pattern of network and system-info bundled skills.
crates/zeph-skills/skills is a symlink to .zeph/skills/, so the skill lives at:

.zeph/skills/os-automation/
├── SKILL.md               # frontmatter + body + OS detection
└── references/
    ├── macos.md           # AppleScript / JXA / launchctl / screencapture / networksetup
    ├── windows.md         # PowerShell / COM / Task Scheduler / WinRT
    └── linux.md           # notify-send / xdg-open / cron / xclip

OS detection in SKILL.md body (same pattern as network):

uname -s 2>/dev/null || echo Windows

Then load the matching reference file for platform-specific commands.

Built-In Tools Covered

macOS

Windows

Linux

Permission Tiers (macOS)

Tier 1 — No permissions needed:
Clipboard, volume/mute, notifications, open, screencapture (first-run Screen Recording only)

Tier 2 — One-time TCC consent per app:
tell application "X" — Automation consent for each target app (one-time dialog)

Tier 3 — Accessibility consent:
Keystrokes, clicking UI elements via System Events — requires Accessibility in System Settings

Security Rules to Include in SKILL.md

• Always confirm before modifying scheduled tasks or killing processes
• Never send keystrokes or click UI elements without explicit user request
• Screen captures may contain sensitive data — treat output files as sensitive
• networksetup operations requiring sudo — warn user first
• PowerShell ExecutionPolicy errors handled gracefully with guidance

Known Gaps

• Brightness control (macOS): no built-in CLI — requires Accessibility or third-party
• Window resize/position (macOS): requires Accessibility scripting
• App window focus (Windows): requires P/Invoke user32.dll
• macOS Shortcuts output: no stdout pipe — must use --output-path

Prior Art / Reference

• macos-automator-mcp — 200+ AppleScript/JXA recipes, good reference for macOS capability inventory
• PowerSkills — PowerShell-based Windows automation skill pattern

Research Document

Full report with code examples: .local/research/os-automation-skill.md

MVP Scope (implementation order)

1. Notifications — macOS + Windows + Linux, permission-free
2. Clipboard read/write — all platforms
3. Screenshot — screencapture -x / PowerShell .NET / scrot
4. Open file/URL/app — open / Start-Process / xdg-open
5. Volume control — osascript / COM
6. WiFi status — networksetup / Get-NetAdapter
7. Scheduled task — launchctl plist / Register-ScheduledTask / cron
8. Browser tab — Safari/Chrome via AppleScript (one-time Automation permission)
9. App list/focus — System Events / Get-Process