Skip to content
Skills Library
DevOps & cloud · Analysis

linux-disk-usage

/linux-disk-usage

Linux disk-usage forensics and space recovery. Use when a Linux disk is near-full, finding what eats space, or clearing caches, build dirs and model stores.

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/scan-suspects.sh, scripts/tests/test-scan-suspects.sh

What it does and when to use it

Linux disk-usage forensics and space recovery. Use when a Linux disk is near-full, finding what eats space, or clearing caches, build dirs and model stores.

Original author description

Linux disk-usage forensics and space recovery. Use when a Linux disk is near-full, finding what eats space, or clearing caches, build dirs and model stores.

How it works

  1. When to Use This Skill
  2. Platform Guard
  3. Core Facts
  4. Step 1: Measure every filesystem
  5. Step 1.5: The usual-suspects scan
  6. Step 2: Clean by tier
  7. Step 3: Data drives and model stores
  8. Step 4: Archive, verify, then delete
  9. Agentic Optimizations
Original SKILL.md headings · 90 lines, 1,017 words
SKILL.md preview
---
name: linux-disk-usage
description: Linux disk-usage forensics and space recovery. Use when a Linux disk is near-full, finding what eats space, or clearing caches, build dirs and model stores.
user-invocable: false
allowed-tools: Bash, Read, Grep, Glob, TodoWrite
created: 2026-10-30
modified: 2026-10-30
reviewed: 2026-10-30
---

# Linux Disk Usage & Space Recovery

## When to Use This Skill

| Use this skill when... | Use something else when... |
|------------------------|----------------------------|
| `df` reports a Linux filesystem near-full | The machine is a Mac — `macos-plugin:macos-disk-usage` (APFS, snapshots, OrbStack) |
| Hunting what is eating root or a data drive | Downloading Hugging Face models without filling root — `tools-plugin:hf-downloads` |
| Clearing dev caches, build dirs, CI-runner workspaces, model stores | Deleting a whole git checkout — run `git-plugin:git-repo-delete-check` first |
| Moving bulky data to another drive before deleting it | |

## Platform Guard

```bash
test "$(uname -s)" = "Linux" || { echo "linux-plugin: not Linux, refusing"; exit 1; }
```

## Core Facts

1. **Look at every mount before deciding anything.** Root is often full while a data drive has terabytes free; that turns "delete" into "move". `df -h` alone hides unmounted and secondary disks.
2. **`du` over-counts reflinked copies on XFS and btrfs.** uv installs into a `.venv` by cloning from its cache when the filesystem supports reflinks (an installed file shows `shared` in `filefrag -v`; `xfs_info /` shows `reflink=1`). `du`, `dust` and the scanner bill each clone at full size, so a `.venv` delete frees less than reported. Cargo `target/` dirs are real per-project copies and free what they show. When a size gates a decision, measure a `df` delta (`macos-plugin:macos-disk-usage` covers the same effect for APFS clones).
3. **A cache relocated by symlink is measured as the link.** `~/.cache/huggingface -> /mnt/data/hf-cache` reads as a few bytes under `du`; the bytes are on the other drive. Scan the target, and clean it with the tool's `--cache-dir` (uv) or by path.

## Step 1: Measure every filesystem

```bash
df -h -x tmpfs -x devtmpfs -x squashfs
lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT
findmnt -no FSTYPE,OPTIONS -T <path>      # reflink-capable? relatime? NTFS (fuseblk)?
swapon --show                              # a swapfile beside zram is a candidate
```

Then the tree. `dust` is the fast lead; run it through `mise exec` so it writes nothing to the global mise config:

```bash
mise exec aqua:bootandy/dust@latest -- dust -x -d 1 -n 20 -b -P /
mise exec aqua:bootandy/dust@latest -- dust -x -d 2 -n 30 -b -P <largest-dir>
```

`-x` stays on one filesystem, so each mount is scanned on its own. Reading `/var` or other users' homes without root under-reports them; say so rather than presenting the figure as complete.

## Step 1.5: The usual-suspects scan

`scripts/scan-suspects.sh` reads `scripts/suspects.tsv` (Linux caches, build dirs, runner workspaces, swap, journal), measures what exists here, and prints a ranked rollup with the cleanup command and safety tier attached:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/scan-suspects.sh" --home-dir "$HOME" --root "$HOME" --min-mb 500
bash "${CLAUDE_SKILL_DIR}/scripts/scan-suspects.sh" --root ~/repos --min-mb 1000
```

Output: `SUSPECT id=… tier=… size_kb=… cmd="…"`, a ranked table, `TIER_*_KB=` totals, and `UNKNOWN` lines for big uncatalogued dirs. Rows with absolute targets (`/swapfile`, `/var/log/journal`, the linuxbrew Cellar) read the real host whatever `--home-dir` says. A recurring `UNKNOWN` becomes a catalog row, written as a pattern; this repo is public. The scanner is a copy of the macOS one with a different catalog, so a scanner fix lands in both.

## Step 2: Clean by tier

Exhaust `safe` before `decision`; `userdata` needs the user's explicit yes per item. Commands that turned out incomplete in their obvious form:

| Target | Use | Not just | Why |
|--------|-----|----------|-----|
| Homebrew cache | `brew cleanup --prune=all -s` | `brew cleanup -s` | Plain `-s` left 2.5 GB in `downloads/` |
| npm | `npm cache clean --force` **and** `rm -rf ~/.npm/_npx` | the clean alone | The clean leaves the npx cache (437 MB measured) |
| uv cache on another drive | `uv cache clean --cache-dir <dir>` | `uv cache clean` | The default only clears `~/.cache/uv` |
| Rust build output | `cargo clean` in each project | deleting `target/` by hand | Same result, and it respects a custom `target-dir` |
| mise tool versions | `mise prune --dry-run`, then `mise prune` | deleting install dirs | Prune keeps every version a tracked config asks for |
| Go temp build dirs | `rm -rf $TMPDIR/go-build<digits>` older than an hour | `rm -rf ~/.cache/go-build` | That one is the live cache; use `go clean -cache` |

**Self-hosted GitHub Actions runners.** Each runner keeps `externals.<version>` dirs from before an auto-update, about 590 MB each; delete all but the current version. Clear `_work` only while no job runs (`systemctl list-units 'actions.runner.*'`, then the runner's job state).

**Swapfile beside zram.** When `swapon --show` lists zram at a higher priority and the swapfile's `USED` is near zero, the swapfile is spare capacity for memory spikes. Removing it is the user's call: `swapoff`, drop the fstab line, delete.

## Step 3: Data drives and model stores

Model stores (ComfyUI `models/`, Hugging Face, ollama, torch hub) and generated output are the largest items on a workstation data drive, and the least regenerable. Before deleting anything there, open [references/ml-model-stores.md](references/ml-model-stores.md). It covers keeping HF login tokens while wiping the hub, checking workflows for a model's filename, the duplicate-hunt method and its false positives, hardlinking a duplicate that a workflow loads by path, and reading access times before your own scan resets them.

## Step 4: Archive, verify, then delete

For data the user wants kept but not on this drive, copy to a drive with room, verify the copy, and only then delete. A verification that looks clean can still be wrong, especially onto NTFS. Before deleting a git checkout or project directory, follow [references/archive-and-delete.md](references/archive-and-delete.md).

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Every filesystem at once | `df -h -x tmpfs -x devtmpfs -x squashfs` |
| Ranked suspects | `bash "${CLAUDE_SKILL_DIR}/scripts/scan-suspects.sh" --root ~ --min-mb 500` |
| One-level tree, one filesystem | `mise exec aqua:bootandy/dust@latest -- dust -x -d 1 -b -P <dir>` |
| Machine-readable sizes | `dust -j -o b -d1 <dir>` (JSON tree, sizes in bytes) |
| Journal size, no sudo | `journalctl --disk-usage` |
| Prunable mise versions | `mise prune --dry-run` |
| Reflink check | `filefrag -v <file>` (look for `shared`) |
Files in this package (6)
  • SKILL.md 7 KB
  • references/archive-and-delete.md 3 KB
  • references/ml-model-stores.md 5 KB
  • scripts/scan-suspects.sh 9 KB
  • scripts/suspects.tsv 6 KB
  • scripts/tests/test-scan-suspects.sh 11 KB

Versions

The database has no other skills named linux-disk-usage.

Database snapshot: 13.11.2026 · package version 69905e3ffaf1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100macos-disk-usage
    macOS disk-usage forensics and space recovery on APFS. Use when df reports a disk near-full, hunting what's eating space, reclaiming OrbStack/Docker, or pruning caches and local snapshots.
  • 100disk-cleanup
    Use when df says disk is above 80% full or the user wants to reclaim storage space on a VM.
  • 100disk-reclaim
    Diagnose disk usage and reclaim space on a Mac or an SSH-reachable Linux dev host. Use for disk-full errors, storage audits, or cleanup requests. Starts with a bounded read-only survey, protects active development and services, and verifies actual filesystem capacity gained.
  • 100disk-cleanup
    Audit disk usage and reclaim space on macOS and NixOS hosts without losing live or personal data. Use when a disk is full or nearly full, when asked to free space or find what is using it, or before removing build outputs, caches, scratch copies, or agent worktrees in bulk.
  • 100pro-disk-cleanup
    Find and clear reclaimable disk space safely on any macOS, Windows or Linux machine and stack: read-only scan, three tiers (safe, decide, keep), closed-issue worktrees with backup, build output, caches, Docker. Use for 'disk is full', 'free up space'.
  • 90free-up-disk-space
    Free up disk space on the user's Mac safely with DiskSpace AI. Use when the user says their Mac or disk is full, asks what's taking up space, can't install a macOS update, wants to clean caches, Xcode DerivedData, simulators, Docker, node_modules or AI models, or asks whether a…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.