gpsaggese/helpers / .claude/skills/system.analyze_disk_space_use
system.analyze_disk_space_use
VerifiedAnalyze disk usage to find the largest space consumers and reclaim options
Goal
- Find what consumes the most disk space. Identify what is safely reclaimable (unused container/VM images, caches, logs) and what needs manual review
- Never delete, move, or modify anything. Analysis only
Workflow
Check Overall Disk Usage
- Run
df -hto see total, used, and available space per volume - On macOS, user data lives on
/System/Volumes/Data, not/. Use itsCapacity/Availcolumns to judge urgency
Survey the Home Directory
-
List top-level home directory usage, largest first:
> du -sh ~/* 2>/dev/null | sort -rh -
Recurse one level at a time into the dominant directory (on macOS, often
~/Library), sorting by size, until you reach the actual large items:> /usr/bin/du -sh ~/Library/* 2>/dev/null | sort -rh | head -30 -
Track every directory measured. They feed the top-10 list in "Rank Findings And Write The Report"
Check Container and VM Engines First
- Container and VM engines are usually the biggest consumer on a dev machine. They cache every pulled or built image and rarely self-prune
- For each installed engine, check its usage report before raw directory sizes:
- Docker: if
dockerexists, rundocker system df -vfor a per-image and per-volume breakdown. Images withCONTAINERS= 0 are unused and reclaimable - Apple
containerCLI (native macOS containers): ifcontainerexists, runcontainer system df. Its data lives under~/Library/Application Support/com.apple.container. Docker's VM disk lives under~/Library/Containers/com.docker.docker - Other engines (
podman,colima,lima,nerdctl): use their equivalentsystem df/ usage-report command
- Docker: if
- The tool can report a builder container (Docker
buildxstate volume, Applebuildkitbuilder) as "active", which excludes it fromRECLAIMABLEeven when it is very large- Size it with
/usr/bin/du -sh <PATH>. Report it as a manual candidate, with the reset command (docker buildx prune --all, orcontainer builder stop && container builder delete)
- Size it with
Check Common Cache/Log Locations
- MacOS:
~/Library/Caches~/Library/Logs- Per-app
Cache/Code Cachefolders under~/Library/Application Support/<App> ~/.Trashtmutil listlocalsnapshots /: flag any entry that is not a normalcom.apple.os.update-*system snapshot
- Linux equivalents:
~/.cache,/var/cache,/var/log, and package-manager caches (apt,dnf,pacman)
Spot-Check Dev Artifacts
- Look for large, likely-stale developer artifacts:
venv/.venvdirectories,node_modules, old or duplicate repo clones, and suspiciously named directories (backups,ancient_*,old_*) - Report these as "needs manual review", never as auto-recommended deletions. They can hold unique, irreplaceable data
Rank Findings and Write the Report
- For each candidate, record: path, size, and whether it is safely reclaimable (rebuildable, re-pullable, re-cacheable) or needs manual review (may hold unique data)
- Fill in
.claude/skills/system.analyze_disk_space_use/report.template.md, formatted per.claude/skills/markdown.rules.md - Save the file in the current dir
- Right after the title, add how the report was generated:
- Generated by `.claude/skills/system.analyze_disk_space_use/SKILL.md` - List the top 10 directories measured in "Survey The Home Directory" and "Check
Container And VM Engines First", largest first. Prefer the most specific directory
that explains the bytes (e.g., the Docker VM disk, not just
~/Library) - Take every reclaim command from the tool's own output (e.g.,
docker system df). Never guess one. Pair each with the size it frees - Lead the report with a summary table of every command and its estimated savings.
Then give the full nested breakdown per
.claude/skills/markdown.rules.md"List of Items": one bold-labeled bullet per reclaimable item, with the command and size nested under it - Rank the breakdown by impact (space freed) first, then by risk
Create a Script to Perform the Cleanup
- Create a Bash script
cleanup.shin the current dir. Do not make it executable, since the user must review it first - Add a comment for each potential saving: how safe it is, how much space it
saves, and the command
# SAFETY: low (cache rebuilds automatically on next use) # SPACE FREED: ~20GB # COMMAND: delete uv package manager cache # rm -rf ~/.cache/uv
Constraints
- Only run read-only commands:
df,du,*system df,*ls,tmutil listlocalsnapshots,find(without-delete) - Never run a destructive command (
docker system prune,docker image rm,container image rm,rm -rf,container builder delete, etc.). List them in the report only, as candidates for the user to run - If a read-only command fails with an unexpected
usage:message, suspect a shell-hook rewrite. Retry with the full binary path (e.g.,/usr/bin/du) - Do not enumerate every file. Stop recursing once a directory's largest child no longer meaningfully explains the space gap
Verification
- The report accounts for most of the gap between disk size and free space (the sum of reported items roughly explains where the used space went)
- No file was created, deleted, or modified other than the report itself
- The report says that it was generated by
.claude/skills/system.analyze_disk_space_use/SKILL.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |