From 8d5cfb69fd0e0e815449ca61601155d1e7bc0a6f Mon Sep 17 00:00:00 2001 From: Andrew Yim Date: Fri, 13 Mar 2026 22:46:12 +0900 Subject: [PATCH] refactor: convert mac-optimizer from raw skill to proper plugin Restructured 92-mac-optimizer from a CLAUDE.md-based skill into a full Claude Code plugin with .claude-plugin/plugin.json, 6 slash commands (/mac-doctor, /mac-packages, /mac-environment, /mac-security, /mac-cleanup, /mac-resources), and auto-trigger SKILL.md. Co-Authored-By: Claude Opus 4.6 --- .../.claude-plugin/plugin.json | 45 +++++++++ custom-skills/92-mac-optimizer/CLAUDE.md | 98 ------------------- .../92-mac-optimizer/commands/mac-cleanup.md | 53 ++++++++++ .../92-mac-optimizer/commands/mac-doctor.md | 60 ++++++++++++ .../commands/mac-environment.md | 30 ++++++ .../92-mac-optimizer/commands/mac-packages.md | 32 ++++++ .../commands/mac-resources.md | 29 ++++++ .../92-mac-optimizer/commands/mac-security.md | 25 +++++ .../skills/mac-optimizer/SKILL.md | 44 +++++++++ .../references/cleanup-targets.md | 0 .../mac-optimizer}/references/packages.md | 0 .../references/security-checks.md | 0 .../mac-optimizer}/scripts/audit_cleanup.sh | 0 .../scripts/audit_environment.sh | 0 .../mac-optimizer}/scripts/audit_packages.sh | 0 .../mac-optimizer}/scripts/audit_resources.sh | 0 .../mac-optimizer}/scripts/audit_security.sh | 0 .../mac-optimizer}/scripts/cleanup_execute.sh | 0 18 files changed, 318 insertions(+), 98 deletions(-) create mode 100644 custom-skills/92-mac-optimizer/.claude-plugin/plugin.json delete mode 100644 custom-skills/92-mac-optimizer/CLAUDE.md create mode 100644 custom-skills/92-mac-optimizer/commands/mac-cleanup.md create mode 100644 custom-skills/92-mac-optimizer/commands/mac-doctor.md create mode 100644 custom-skills/92-mac-optimizer/commands/mac-environment.md create mode 100644 custom-skills/92-mac-optimizer/commands/mac-packages.md create mode 100644 custom-skills/92-mac-optimizer/commands/mac-resources.md create mode 100644 custom-skills/92-mac-optimizer/commands/mac-security.md create mode 100644 custom-skills/92-mac-optimizer/skills/mac-optimizer/SKILL.md rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/references/cleanup-targets.md (100%) rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/references/packages.md (100%) rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/references/security-checks.md (100%) rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/scripts/audit_cleanup.sh (100%) rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/scripts/audit_environment.sh (100%) rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/scripts/audit_packages.sh (100%) rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/scripts/audit_resources.sh (100%) rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/scripts/audit_security.sh (100%) rename custom-skills/92-mac-optimizer/{ => skills/mac-optimizer}/scripts/cleanup_execute.sh (100%) diff --git a/custom-skills/92-mac-optimizer/.claude-plugin/plugin.json b/custom-skills/92-mac-optimizer/.claude-plugin/plugin.json new file mode 100644 index 0000000..f022091 --- /dev/null +++ b/custom-skills/92-mac-optimizer/.claude-plugin/plugin.json @@ -0,0 +1,45 @@ +{ + "name": "mac-optimizer", + "version": "1.0.0", + "description": "Modular macOS system health toolkit with read-only audits, cleanup, and security checks", + "author": { + "name": "OurDigital" + }, + "keywords": [ + "macos", + "system", + "optimization", + "cleanup", + "security", + "homebrew", + "packages", + "disk-space" + ], + "license": "MIT", + "commands": [ + { + "name": "mac-doctor", + "description": "Full macOS system health check — runs all 5 audit modules and presents unified findings" + }, + { + "name": "mac-packages", + "description": "Audit package managers (Homebrew, npm, pip, pyenv) for outdated packages and issues" + }, + { + "name": "mac-environment", + "description": "Audit shell environment — PATH, symlinks, shell configs, and startup time" + }, + { + "name": "mac-security", + "description": "Security posture assessment — SIP, Gatekeeper, Firewall, FileVault, SSH, ports" + }, + { + "name": "mac-cleanup", + "description": "Scan and clean caches, logs, and clutter — shows sizes first, cleans only with consent" + }, + { + "name": "mac-resources", + "description": "Monitor CPU, memory, disk, battery, and identify resource-hungry processes" + } + ] +} diff --git a/custom-skills/92-mac-optimizer/CLAUDE.md b/custom-skills/92-mac-optimizer/CLAUDE.md deleted file mode 100644 index 9195c3f..0000000 --- a/custom-skills/92-mac-optimizer/CLAUDE.md +++ /dev/null @@ -1,98 +0,0 @@ -# Mac Optimizer - -Modular macOS system health toolkit. Runs read-only audits first, then recommends actions with user consent. - -## Module Routing - -| Keywords | Module | -|---|---| -| brew, homebrew, npm, nvm, pip, pyenv, packages, update, outdated | packages | -| path, shell, zshrc, environment, env, config, symlink | environment | -| security, firewall, sip, gatekeeper, filevault, ports, ssh | security | -| cache, cleanup, clean, logs, clutter, disk space, free space, trash | cleanup | -| cpu, memory, ram, disk, battery, processes, resources, slow | resources | -| doctor, audit, health, full check, everything, system check | doctor (all) | - -Default to **doctor** when the request is ambiguous. - -## Execution Model - -Every module follows this flow: - -1. **Audit** — run the module's script (read-only) -2. **Report** — parse JSON output, present findings as a severity-ranked table -3. **Recommend** — list available actions grouped by risk -4. **Consent** — ask user which actions to approve (per-category, per-item for risky) -5. **Act** — execute only approved actions - -## Running Audit Scripts - -All scripts are in `scripts/` and output JSON lines to stdout: - -```bash -bash scripts/audit_packages.sh -bash scripts/audit_environment.sh -bash scripts/audit_security.sh -bash scripts/audit_cleanup.sh -bash scripts/audit_resources.sh -``` - -Each JSON line has: `{"module":"...","severity":"...","finding":"...","action":"...","details":"..."}` - -Severity levels: `critical` > `warning` > `info` - -If a script exits non-zero, report the error and continue with other modules. - -## Running Cleanup - -```bash -bash scripts/cleanup_execute.sh --help # See all targets -bash scripts/cleanup_execute.sh --dry-run # Preview (default) -bash scripts/cleanup_execute.sh --execute # Actually clean -``` - -**Always run --dry-run first and show the user what will happen before --execute.** - -## Doctor Mode Workflow - -1. Run all 5 audit scripts sequentially, collect all JSON findings -2. Parse and group findings by severity (critical first, then warning, then info) -3. Present unified report table to the user -4. **STOP and ask**: "Which actions would you like me to perform? You can approve by category (e.g., 'update packages and clean caches') or review each item." -5. Execute only approved actions -6. Present final summary of actions taken - -## Safety Rules - -- **Never execute cleanup without explicit user approval** -- **Always show sizes before deleting anything** -- **Security module is read-only** — present findings and remediation guidance only -- **Back up shell configs** before modifying: `cp ~/.zshrc ~/.config/mac-optimizer-backups/.zshrc.$(date +%s)` -- **Process deny-list**: never suggest killing `kernel_task`, `launchd`, `WindowServer`, `loginwindow`, `mds`, `mds_stores`, `opendirectoryd`, `coreaudiod`, `SystemUIServer`, `Finder`, `Dock` -- **No sudo by default** — if an action needs sudo, state why and ask first -- Docker cleanup uses `docker system prune`, never direct file deletion - -## Report Format - -Present findings as a markdown table: - -``` -### Critical -| Module | Finding | Recommended Action | -|---|---|---| -| security | Firewall disabled | Enable in System Settings | - -### Warning -| Module | Finding | Recommended Action | -|---|---|---| - -### Info -| Module | Finding | Recommended Action | -|---|---|---| -``` - -## Reference Files - -- **references/packages.md** — package manager update strategies and commands -- **references/security-checks.md** — security benchmarks and remediation guidance -- **references/cleanup-targets.md** — full list of cleanup paths with risk ratings diff --git a/custom-skills/92-mac-optimizer/commands/mac-cleanup.md b/custom-skills/92-mac-optimizer/commands/mac-cleanup.md new file mode 100644 index 0000000..8c68d79 --- /dev/null +++ b/custom-skills/92-mac-optimizer/commands/mac-cleanup.md @@ -0,0 +1,53 @@ +--- +allowed-tools: Bash(bash *audit_cleanup.sh*), Bash(bash *cleanup_execute.sh*), Bash(du *), Bash(brew *), Bash(npm *), Bash(pip *), Bash(docker *), Bash(rm *) +description: Scan and clean caches, logs, and clutter — shows sizes first, cleans only with consent +--- + +## Your task + +Scan for reclaimable disk space and offer cleanup. + +### Step 1 — Run the audit + +```bash +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_cleanup.sh +``` + +### Step 2 — Report + +Parse JSON output and present as a table sorted by size (largest first): + +| Category | Size | Risk | Target | +|---|---|---|---| + +Show the total reclaimable space. + +### Step 3 — Ask for consent + +Ask which categories to clean. Group by risk level (Safe / Moderate / Risky). + +### Step 4 — Dry run first + +For approved targets, always run dry-run first: + +```bash +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/cleanup_execute.sh --dry-run +``` + +Show the output and ask for final confirmation. + +### Step 5 — Execute + +Only after explicit confirmation: + +```bash +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/cleanup_execute.sh --execute +``` + +### Safety rules + +- Never execute cleanup without explicit user approval +- Always show sizes before deleting anything +- Always run --dry-run before --execute +- Docker cleanup uses `docker system prune`, never direct file deletion +- No sudo by default — if an action needs sudo, state why and ask first diff --git a/custom-skills/92-mac-optimizer/commands/mac-doctor.md b/custom-skills/92-mac-optimizer/commands/mac-doctor.md new file mode 100644 index 0000000..6094efa --- /dev/null +++ b/custom-skills/92-mac-optimizer/commands/mac-doctor.md @@ -0,0 +1,60 @@ +--- +allowed-tools: Bash(bash *audit_*.sh*), Bash(bash *cleanup_execute.sh*), Bash(du *), Bash(df *), Bash(brew *), Bash(npm *), Bash(pip *), Bash(docker *), Bash(cp *) +description: Full macOS system health check — runs all 5 audit modules and presents unified findings +--- + +## Your task + +Run a full macOS system health check using all 5 audit modules. Follow this workflow exactly: + +### Step 1 — Run all audits + +Run these scripts sequentially, collecting all JSON output: + +```bash +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_packages.sh +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_environment.sh +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_security.sh +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_cleanup.sh +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_resources.sh +``` + +If a script exits non-zero, report the error and continue with other modules. + +### Step 2 — Parse and report + +Parse all JSON lines. Each has: `{"module":"...","severity":"...","finding":"...","action":"...","details":"..."}` + +Present findings grouped by severity (critical first, then warning, then info) as markdown tables: + +``` +### Critical +| Module | Finding | Recommended Action | +|---|---|---| + +### Warning +| Module | Finding | Recommended Action | +|---|---|---| + +### Info +| Module | Finding | Recommended Action | +|---|---|---| +``` + +### Step 3 — Ask for consent + +STOP and ask: "Which actions would you like me to perform? You can approve by category (e.g., 'update packages and clean caches') or review each item." + +### Step 4 — Execute approved actions only + +For cleanup actions, always run `--dry-run` first and show what will happen before running `--execute`. + +### Safety rules + +- Never execute cleanup without explicit user approval +- Always show sizes before deleting anything +- Security module is read-only — present findings and remediation guidance only +- Back up shell configs before modifying: `cp ~/.zshrc ~/.config/mac-optimizer-backups/.zshrc.$(date +%s)` +- Process deny-list: never suggest killing kernel_task, launchd, WindowServer, loginwindow, mds, mds_stores, opendirectoryd, coreaudiod, SystemUIServer, Finder, Dock +- No sudo by default — if an action needs sudo, state why and ask first +- Docker cleanup uses `docker system prune`, never direct file deletion diff --git a/custom-skills/92-mac-optimizer/commands/mac-environment.md b/custom-skills/92-mac-optimizer/commands/mac-environment.md new file mode 100644 index 0000000..f462e9c --- /dev/null +++ b/custom-skills/92-mac-optimizer/commands/mac-environment.md @@ -0,0 +1,30 @@ +--- +allowed-tools: Bash(bash *audit_environment.sh*), Bash(echo *), Bash(cp *) +description: Audit shell environment — PATH, symlinks, shell configs, and startup time +--- + +## Your task + +Audit the shell environment on this Mac. + +### Step 1 — Run the audit + +```bash +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_environment.sh +``` + +### Step 2 — Report + +Parse JSON output and present as a severity-ranked markdown table: + +| Severity | Finding | Recommended Action | Details | +|---|---|---|---| + +### Step 3 — Ask for consent + +If there are fixable issues (duplicate PATH entries, broken symlinks, non-existent directories), list them and ask which to fix. + +### Safety rules + +- Back up shell configs before modifying: `cp ~/.zshrc ~/.config/mac-optimizer-backups/.zshrc.$(date +%s)` +- Present PATH consolidation suggestions but don't auto-modify diff --git a/custom-skills/92-mac-optimizer/commands/mac-packages.md b/custom-skills/92-mac-optimizer/commands/mac-packages.md new file mode 100644 index 0000000..692b284 --- /dev/null +++ b/custom-skills/92-mac-optimizer/commands/mac-packages.md @@ -0,0 +1,32 @@ +--- +allowed-tools: Bash(bash *audit_packages.sh*), Bash(brew *), Bash(npm *), Bash(pip *), Bash(nvm *), Bash(pyenv *) +description: Audit package managers (Homebrew, npm, pip, pyenv) for outdated packages and issues +--- + +## Your task + +Audit all package managers on this Mac. + +### Step 1 — Run the audit + +```bash +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_packages.sh +``` + +### Step 2 — Report + +Parse JSON output and present as a severity-ranked markdown table: + +| Severity | Finding | Recommended Action | Details | +|---|---|---|---| + +### Step 3 — Ask for consent + +List available update actions grouped by risk. Ask which actions to perform. + +### Safety notes + +- `brew upgrade` is generally safe but can break projects pinned to specific versions +- Global npm packages are version-independent from project dependencies +- pip upgrades can break dependency chains — suggest `--dry-run` first +- Only audit pyenv-managed environments (not system Python) diff --git a/custom-skills/92-mac-optimizer/commands/mac-resources.md b/custom-skills/92-mac-optimizer/commands/mac-resources.md new file mode 100644 index 0000000..3456845 --- /dev/null +++ b/custom-skills/92-mac-optimizer/commands/mac-resources.md @@ -0,0 +1,29 @@ +--- +allowed-tools: Bash(bash *audit_resources.sh*), Bash(ps *), Bash(kill *), Bash(df *) +description: Monitor CPU, memory, disk, battery, and identify resource-hungry processes +--- + +## Your task + +Check system resource usage on this Mac. + +### Step 1 — Run the audit + +```bash +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_resources.sh +``` + +### Step 2 — Report + +Parse JSON output and present as a severity-ranked markdown table: + +| Severity | Finding | Recommended Action | Details | +|---|---|---|---| + +### Step 3 — Offer actions + +If high-resource processes are found, offer to help. But respect the deny-list: + +**Never suggest killing**: kernel_task, launchd, WindowServer, loginwindow, mds, mds_stores, opendirectoryd, coreaudiod, SystemUIServer, Finder, Dock + +For user processes consuming excessive resources, ask before terminating. diff --git a/custom-skills/92-mac-optimizer/commands/mac-security.md b/custom-skills/92-mac-optimizer/commands/mac-security.md new file mode 100644 index 0000000..5a70cb6 --- /dev/null +++ b/custom-skills/92-mac-optimizer/commands/mac-security.md @@ -0,0 +1,25 @@ +--- +allowed-tools: Bash(bash *audit_security.sh*) +description: Security posture assessment — SIP, Gatekeeper, Firewall, FileVault, SSH, ports +--- + +## Your task + +Run a read-only security posture assessment. + +### Step 1 — Run the audit + +```bash +bash $CLAUDE_PLUGIN_ROOT/skills/mac-optimizer/scripts/audit_security.sh +``` + +### Step 2 — Report + +Parse JSON output and present as a severity-ranked markdown table: + +| Severity | Finding | Recommended Action | Details | +|---|---|---|---| + +### Step 3 — Guidance only + +The security module is **read-only**. Present findings and remediation guidance. Do NOT attempt to change security settings. Explain how the user can fix issues themselves via System Settings or Terminal commands. diff --git a/custom-skills/92-mac-optimizer/skills/mac-optimizer/SKILL.md b/custom-skills/92-mac-optimizer/skills/mac-optimizer/SKILL.md new file mode 100644 index 0000000..a8d9cd0 --- /dev/null +++ b/custom-skills/92-mac-optimizer/skills/mac-optimizer/SKILL.md @@ -0,0 +1,44 @@ +--- +name: mac-optimizer +description: macOS system health toolkit — use when user mentions system optimization, cleanup, packages, security audit, disk space, performance, brew updates, cache clearing, or system health on Mac +version: 1.0.0 +--- + +# Mac Optimizer + +Modular macOS system health toolkit. Runs read-only audits first, then recommends actions with user consent. + +## Module Routing + +| Keywords | Command | +|---|---| +| brew, homebrew, npm, nvm, pip, pyenv, packages, update, outdated | /mac-packages | +| path, shell, zshrc, environment, env, config, symlink | /mac-environment | +| security, firewall, sip, gatekeeper, filevault, ports, ssh | /mac-security | +| cache, cleanup, clean, logs, clutter, disk space, free space, trash | /mac-cleanup | +| cpu, memory, ram, disk, battery, processes, resources, slow | /mac-resources | +| doctor, audit, health, full check, everything, system check | /mac-doctor (all) | + +Default to **/mac-doctor** when the request is ambiguous. + +When the user's request matches a specific module, suggest the appropriate slash command. When the request is broad (e.g., "check my system", "run a health check"), use /mac-doctor. + +## Execution Model + +Every module follows this flow: + +1. **Audit** — run the module's script (read-only) +2. **Report** — parse JSON output, present findings as a severity-ranked table +3. **Recommend** — list available actions grouped by risk +4. **Consent** — ask user which actions to approve +5. **Act** — execute only approved actions + +## Safety Rules + +- **Never execute cleanup without explicit user approval** +- **Always show sizes before deleting anything** +- **Security module is read-only** — present findings and remediation guidance only +- **Back up shell configs** before modifying +- **Process deny-list**: never suggest killing kernel_task, launchd, WindowServer, loginwindow, mds, mds_stores, opendirectoryd, coreaudiod, SystemUIServer, Finder, Dock +- **No sudo by default** — if an action needs sudo, state why and ask first +- Docker cleanup uses `docker system prune`, never direct file deletion diff --git a/custom-skills/92-mac-optimizer/references/cleanup-targets.md b/custom-skills/92-mac-optimizer/skills/mac-optimizer/references/cleanup-targets.md similarity index 100% rename from custom-skills/92-mac-optimizer/references/cleanup-targets.md rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/references/cleanup-targets.md diff --git a/custom-skills/92-mac-optimizer/references/packages.md b/custom-skills/92-mac-optimizer/skills/mac-optimizer/references/packages.md similarity index 100% rename from custom-skills/92-mac-optimizer/references/packages.md rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/references/packages.md diff --git a/custom-skills/92-mac-optimizer/references/security-checks.md b/custom-skills/92-mac-optimizer/skills/mac-optimizer/references/security-checks.md similarity index 100% rename from custom-skills/92-mac-optimizer/references/security-checks.md rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/references/security-checks.md diff --git a/custom-skills/92-mac-optimizer/scripts/audit_cleanup.sh b/custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_cleanup.sh similarity index 100% rename from custom-skills/92-mac-optimizer/scripts/audit_cleanup.sh rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_cleanup.sh diff --git a/custom-skills/92-mac-optimizer/scripts/audit_environment.sh b/custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_environment.sh similarity index 100% rename from custom-skills/92-mac-optimizer/scripts/audit_environment.sh rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_environment.sh diff --git a/custom-skills/92-mac-optimizer/scripts/audit_packages.sh b/custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_packages.sh similarity index 100% rename from custom-skills/92-mac-optimizer/scripts/audit_packages.sh rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_packages.sh diff --git a/custom-skills/92-mac-optimizer/scripts/audit_resources.sh b/custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_resources.sh similarity index 100% rename from custom-skills/92-mac-optimizer/scripts/audit_resources.sh rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_resources.sh diff --git a/custom-skills/92-mac-optimizer/scripts/audit_security.sh b/custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_security.sh similarity index 100% rename from custom-skills/92-mac-optimizer/scripts/audit_security.sh rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/audit_security.sh diff --git a/custom-skills/92-mac-optimizer/scripts/cleanup_execute.sh b/custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/cleanup_execute.sh similarity index 100% rename from custom-skills/92-mac-optimizer/scripts/cleanup_execute.sh rename to custom-skills/92-mac-optimizer/skills/mac-optimizer/scripts/cleanup_execute.sh