agentleFS
lifedeverlifedever/skills-plugin/skills/mac-cleanup-disk/SKILL.md

mac-cleanup-disk

Skill14 starsChanged 6 months agoMITView on GitHub

macOS disk deep-clean and maintenance workflow, built on tw93/mole (brew install mole, CLI name `mo`). Trigger words "clean mac", "clean system", "disk full", "free up disk", "clear caches", "uninstall app", "disk analysis", "mole", "mo clean", "clean node_modules", "clean build artifacts", "mac maintenance", "deep clean mac", "清理 mac", "清理系统", "磁盘空间不足", "磁盘满", "清理缓存", "卸载应用", "磁盘分析", "清理 node_modules", "清项目构建产物", "mac 维护". Safety policy dry-run first + explicit user text confirmation before any deletion. Sister skill mac-cleanup-process (processes, never touches disk).

  • Deletes or force-pushes
  • Installs packages

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
  1. Distinctive:

    Before any workflow, verify mole is installed:

    line 12
  2. Very specific:

    If it isn't installed, don't proactively brew install — report "mole not installed, requires brew install mole.

    line 18
  3. Distinctive:

    Don't jump in just because the user said "clean my Mac".

    line 22
  4. Distinctive:

    If the user already knows which command they want ("I just want to run mo clean"), skip this step and go straight to the safety flow.

    line 31
  5. Distinctive:

    After each step, report freed space and ask "continue to next step?".

    line 76
  6. Very specific:

    If the user just wants to know which project directories are eating space, the AI can use find instead:

    line 82
  7. Very specific:

    After a real deletion, always run df -h / to compare freed space and report "freed X GB, now Y GB available" to the user.

    line 125

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

mac-cleanup-disk

A macOS maintenance workflow based on tw93/mole. Iron rule: preview first, confirm, then execute. Any deletion requires explicit user text confirmation.

0. Pre-flight Check

Before any workflow, verify mole is installed:

which mo && mo --version

If it isn't installed, don't proactively brew install — report "mole not installed, requires brew install mole. Proceed?" and wait for the user to agree before installing.

1. First Step After a Request: Clarify the Mode

Don't jump in just because the user said "clean my Mac". Lay out the 4 modes first:

#ModeWhen to useMain commands
1💨 Daily cleanPeriodic maintenance, clear caches and logsmo clean --dry-run → mo clean
2🔍 Deep cleanDisk space tight, thorough sweepmo analyze + mo clean + mo installer + mo optimize
3💻 Developer cleanClean node_modules / target / venv, etc.mo purge
4🩺 Smart diagnosisNot sure what to clean — look at data firstmo status + mo analyze + mo clean --dry-run

If the user already knows which command they want ("I just want to run mo clean"), skip this step and go straight to the safety flow.

2. TUI Restrictions (important!)

The following mole subcommands are full-screen TUI interactive programs. Running them via Claude Code's Bash tool will hang, show no content, and refuse keypresses:

  • mo (no-args main menu)
  • mo analyze
  • mo uninstall
  • mo purge
  • mo installer
  • mo status

Handling principle: let the user run these in their own terminal. The AI must not run them on the user's behalf, and must not timeout-then-kill. The AI's role is:

  • Help interpret the TUI output (user screenshots or pastes text back)
  • Run non-TUI commands on the user's behalf: mo clean --dry-run, mo clean, mo optimize --dry-run, mo optimize, df -h

3. Safety Rules (non-negotiable)

  1. Destructive operations must be preceded by --dry-run: includes mo clean, mo optimize, mo uninstall, mo purge, mo installer
  2. After the dry-run output, wait for user text reply like "go / continue / confirm / OK" before running the real version — verbal consent counts, silence does not
  3. Before deep clean, ask: "Have you saved important work? Are dev projects committed?" mole won't touch those, but in case the user picked a destructive mode by mistake
  4. Stop on error: any non-zero exit from a mo command — report the error immediately, do not retry / do not work around / do not swap commands. Could be a mole bug or permission issue, needs the user's judgment.
  5. Never proactively run mo uninstall, mo purge — these may delete files the user is actively using; the user must hand-pick items in the TUI

4. Mode Workflows

4.1 Daily Clean

df -h /                      # current disk usage snapshot
mo clean --dry-run           # list cleanable items + total size

Present the dry-run output in full to the user (don't omit file categories). After confirmation → mo clean → run df -h / again to compare freed space.

4.2 Deep Clean (multi-step, confirm each step)

In order, confirm each step independently:

  1. Disk scan: have the user run mo analyze in their own terminal and paste back the top-10 largest directories
  2. Cache clean: AI runs mo clean --dry-run --debug → confirm → mo clean
  3. Installer cleanup: have the user run mo installer themselves (TUI, hand-pick)
  4. System optimization: AI runs mo optimize --dry-run → confirm → mo optimize

After each step, report freed space and ask "continue to next step?". Don't run the whole sequence non-stop.

4.3 Developer Clean

mo purge is a TUI — let the user run it in their terminal; the AI can't help.

If the user just wants to know which project directories are eating space, the AI can use find instead:

# Scan node_modules in common project directories (sorted by size)
find ~/Documents/Dev ~/Projects ~/GitHub -name node_modules -type d -prune 2>/dev/null \
  | xargs -I {} du -sh {} 2>/dev/null \
  | sort -hr | head -20

Hand the result to the user; they decide whether to run mo purge or rm -rf specific directories manually.

4.4 Smart Diagnosis

df -h /                      # overall disk usage
du -sh ~/Library/Caches ~/Downloads ~/.Trash 2>/dev/null   # frequent heavy consumers
mo clean --dry-run           # mole's cleanable items

Recommend based on the data:

  • Disk >85% → recommend deep clean
  • Disk 60-85% → recommend daily clean
  • Found node_modules >5GB → also recommend developer clean

Let the user pick a mode, then proceed via the corresponding workflow.

5. mole Command Cheatsheet

CommandPurposeDestructiveTUI
mo statusSystem monitoring (CPU/mem/disk)-✓
mo analyze [path]Disk-usage visualization△✓
mo clean [--dry-run]Clear caches/logs/trash✓-
mo uninstallUninstall app + residuals✓✓
mo optimize [--dry-run]Rebuild system caches△-
mo purgeClean project build artifacts✓✓
mo installerClean .dmg/.pkg installers✓✓
mo touchidConfigure sudo Touch ID△-

Common flags: --dry-run to preview, --debug for verbose logs (including risk level), --whitelist to manage protected paths.

6. After Cleanup

After a real deletion, always run df -h / to compare freed space and report "freed X GB, now Y GB available" to the user. This step is non-negotiable — it's the sanity check.

7. Common Issues

SymptomAction
mo: command not foundbrew install mole
App slow to launch after cleanupNormal — caches rebuild once, then back to normal
Disk space didn't go downrm -rf ~/.Trash/* to empty trash; reboot to release swap files
mo shows garbled output in iTerm2Known issue — try Alacritty / kitty / WezTerm / Ghostty / Warp

Core mindset: you're an assistant, not a janitor. Persuade the user to run the TUI in their own terminal and paste output back for you to interpret — more reliable than running on their behalf, lower cost on error.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.