agentleFS
Sign inStart free
narenaryannarenaryan/agent-skills/skills/engineering/macos-disk-space-recovery/SKILL.md

macos-disk-space-recovery

Skill0 starsChanged 39 days agoMITView on GitHub

Use when a Mac is low on disk space or Finder/System Data is vague - measures APFS usage, ranks real offenders, separates safe cache cleanup from risky data deletion, stops apps that recreate files, and re-measures reclaimed space

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    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:

    Treat Finder storage bars as hints.

    line 8
  2. Distinctive:

    Run these first and report both used and free space:

    line 12
  3. Distinctive:

    Ask before deleting anything that can remove user content or reset app state.

    line 45
  4. Distinctive:

    When asked to remove an app family, clarify whether the scope is:

    line 51
  5. Distinctive:

    Before deleting app data, stop recreating processes:

    line 57
  6. Very specific:

    If files reappear or deletion reports Directory not empty, the app or helper is still running.

    line 63
  7. Distinctive:

    Prefer measured facts over generic advice.

    line 67
  8. Very specific:

    Do not manually delete swap, sleep, or other /private/var/vm files.

    line 68
  9. Very specific:

    Treat tmutil snapshots as a special case.

    line 69

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

macOS Disk Space Recovery

Treat Finder storage bars as hints. Start with APFS free space, then rank real directories by size before deleting anything.

First measurements

Run these first and report both used and free space:

df -h /
diskutil info "/System/Volumes/Data"
tmutil listlocalsnapshots /

Then rank likely offenders instead of guessing:

du -hd 1 "$HOME" 2>/dev/null | sort -h
du -hd 1 "$HOME/Library" 2>/dev/null | sort -h
du -hd 1 /private/var 2>/dev/null | sort -h

Offender map

Path familyTypical contentsDeletion risk
~/Library/Caches, app cache folders, logsrebuildable cache and logslow
~/Downloads, large project folders, archivesuser filesask first
~/Library/Application Supportapp state, downloads, modelsmedium to high
~/Library/Group Containers, ~/Library/Containerssandboxed app datahigh
~/.cache, ~/.local, ~/.ollamatool caches, package data, local modelsmedium
/private/var/vm, /private/var/dbswap, system databasesdo not delete manually

Commonly missed large paths: ~/.ollama, Docker data, Xcode DerivedData, simulators, Steam libraries, Microsoft app data, JetBrains caches, WhatsApp group containers, and large image-generation app containers.

Cleanup order

  1. Clear low-risk caches and logs first.
  2. Identify one large app or folder family at a time.
  3. Ask before deleting anything that can remove user content or reset app state.
  4. Quit the owning app before deleting its support or container directories.
  5. Re-measure after every significant deletion and report the delta.

App-family removal pattern

When asked to remove an app family, clarify whether the scope is:

  • only caches
  • Library data but not /Applications
  • a full uninstall including app bundles

Before deleting app data, stop recreating processes:

pgrep -ifl 'Brave|Steam|Docker|WhatsApp|OneDrive|JetBrains'

If files reappear or deletion reports Directory not empty, the app or helper is still running. Quit it, then retry.

Decision rules

  • Prefer measured facts over generic advice.
  • Do not manually delete swap, sleep, or other /private/var/vm files.
  • Treat tmutil snapshots as a special case; remove them only if they actually exist and are materially large.
  • Separate "space used by app data" from "app installed in /Applications".
  • Quote paths with spaces such as Library/Group Containers.

Pitfalls

  • Blaming Apple update caches without checking sizes first.
  • Deleting large sandbox folders while the app is still running, then assuming the cleanup failed.
  • Reporting only df output and missing APFS container free space from diskutil.
  • Removing browser or editor support folders without warning that profiles, sessions, or settings may be lost.
  • Deleting many categories at once and losing the ability to say which action reclaimed the space.

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.

Check your setup, free