| name | analyze-disk-usage |
| description | Analyze disk usage with du (using sudo where needed) to find the largest directories and which ones are safe to empty to free disk space on Ubuntu. Use when a disk/partition is full or the user asks where their space went / what they can delete. |
Claude skill: Analyze disk usage
Find where disk space is going and report which directories can be safely emptied to reclaim it, on
Ubuntu/Debian. The engine is du (with sudo for system-owned paths). This skill analyzes and
recommends; it never deletes anything without the user's explicit, per-run confirmation.
Safety rules (read first)
du, df, and the helper scripts are read-only — run them freely.- Never run a destructive command (
rm, apt clean, journalctl --vacuum-*, docker … prune,
snap remove, emptying Trash, etc.) until you have shown the user the findings and they have
explicitly approved that specific cleanup. Approving one cleanup does not approve the others.
- Prefer the purpose-built cleanup command over
rm -rf when one exists (e.g. sudo apt clean
rather than deleting /var/cache/apt/archives by hand) — see references/cleanable-locations.md.
- Deleting caches is safe (they get rebuilt) but slows the next run of that tool. Say so.
- Never run a
sudo command yourself — not the scans, not the cleanups. sudo's cached
credential is per-terminal, so a password the user types at a ! <command> prompt does not reach
your shell and sudo -n just fails. For every sudo step below, hand the user the exact command,
ask them to run it in shell mode (a ! <command> prompt line), and read the output they paste
back. Never pipe a password (sudo -S) or rely on passwordless sudo to get around this.
When to use
The user says the disk is full, a partition is at 100%, an install/build failed for lack of space,
or asks "where did my space go" / "what can I delete to free space".
Context: the user's regular maintenance script
The user regularly runs Bash+/apps/upgrade_linux.sh (in this same repo), which updates packages and
already performs some of these cleanups as a side effect: sudo apt autoremove -y,
python -m pip cache purge / python3 -m pip cache purge, flatpak uninstall --unused -y, and
sudo truncate -s 0 /var/log/syslog /var/log/kern.log. So the apt-orphan, pip-cache, unused-flatpak,
and syslog/kern.log offenders may already be small. It does not clean ~/.cache, Trash,
/var/lib/docker, snap revisions, browser/IDE caches, or build caches (Gradle/Maven/npm), so those
are the more likely culprits. Re-running that script is itself a low-effort first step you can suggest.
Steps
-
See which filesystem is full. Run df -h -x tmpfs -x devtmpfs and identify the mount point(s)
that are (nearly) full and the device backing them. All later du work targets that mount point,
not blindly /. If several partitions exist (e.g. separate /home), focus on the full one.
-
Drill down from the top with du. Use the helper (it passes -x so it stays on one
filesystem and won't descend into other mounts):
scripts/du_top.sh <mount-point> # largest immediate children, biggest first
Then drill into the biggest child, repeat, until you reach the specific directories responsible
for the bulk of the usage:
scripts/du_top.sh <that-big-subdir>
Anything under /var, /usr, /opt, /root, or another user's home needs sudo to measure
accurately — and per the safety rules you never run sudo yourself, so hand the user the exact
! sudo scripts/du_top.sh <path> line and read back what they paste. A user's own home needs no
sudo, so run those directly. Stop drilling once a directory is clearly a leaf offender or a
known location from step 3.
-
Scan known safe-to-empty locations. In parallel with (or instead of) the manual drill-down,
get the cleanable sizes. This needs sudo to read system and other-user paths, so ask the user
to run it and paste the output (without sudo it silently reports 0 for those, e.g. missing a
53G /var/lib/docker):
! sudo scripts/scan_cleanable.sh # sizes of well-known cleanable dirs, biggest first
This measures package/build/browser caches, logs, Trash, crash dumps, core dumps, snap/docker
leftovers, etc. Cross-reference every large directory found in step 2 against
references/cleanable-locations.md (read it now) to decide whether it is safe to empty and what
the correct cleanup command is. Anything large that is not in that reference is real user data
— surface it for the user to judge, never propose deleting it yourself.
-
Report. Print a single Markdown table sorted by size, then a one-line summary of total
reclaimable space. Columns:
Helper scripts and reference
Run the scripts; don't read their source to answer questions — their contracts are documented above.
scripts/du_top.sh <path> [depth] [count] — largest directories under <path> (default depth 1,
top 25), staying on one filesystem (du -x), permission errors suppressed. Prefix with sudo for
system paths.scripts/scan_cleanable.sh — sizes of the curated safe-to-clean locations, largest first; resolves
the human user's home even under sudo (via $SUDO_USER). Run under sudo so system and
other-user paths are readable.references/cleanable-locations.md — the catalog of known-cleanable Ubuntu locations with the
correct, least-destructive reclaim command for each; read it at step 3.
