check-storage

Storage Analysis and Disk Cleanup Workflow

This skill provides a systematic procedure for analyzing disk space, identifying what is consuming storage across the operating system and home directory, and recommending safe cleanup actions.

1. Overview & Partition Inspection

Run a disk filesystem check to determine used, free, and total capacity on all mounted partitions:

df -h

Check system journal logs usage:

journalctl --disk-usage 2>/dev/null || true

2. Deep Dive: High-Level System & Home Directory Breakdown

Identify large directories at root and user home level:

# Check top-level directories under / (exclude virtual mounts)
du -hd 1 / 2>/dev/null | sort -hr | head -n 15

# Check user home directory top consumers
du -hd 1 "$HOME" 2>/dev/null | sort -hr | head -n 20

3. Specific Culprit Diagnostics

A. Docker Containers, Images, and Volumes

Inspect Docker disk usage and reclaimable space:

docker system df 2>/dev/null || true

B. Trash and User Data Caches

Check trash size and user cache directories:

# Trash bin size
du -sh "$HOME/.local/share/Trash" 2>/dev/null || true

# User Cache breakdown
du -hd 1 "$HOME/.cache" 2>/dev/null | sort -hr | head -n 15

# User Local Share breakdown
du -hd 1 "$HOME/.local/share" 2>/dev/null | sort -hr | head -n 15

# User Config breakdown
du -hd 1 "$HOME/.config" 2>/dev/null | sort -hr | head -n 15

C. Package Managers & Runtime Caches

Inspect sizes of common developer runtimes and package caches:

# Node & JS tools
du -sh "$HOME/.npm" "$HOME/.local/share/pnpm" "$HOME/.bun" "$HOME/.yarn" 2>/dev/null || true

# Python / Poetry / UV
du -sh "$HOME/.cache/pip" "$HOME/.cache/pypoetry" "$HOME/.cache/uv" 2>/dev/null || true

# Headless Browsers (Playwright / Puppeteer / Cypress)
du -sh "$HOME/.cache/ms-playwright" "$HOME/.cache/Cypress" 2>/dev/null || true

# Flatpak / Snap
du -sh /var/lib/flatpak /var/lib/snapd /var/cache/apt 2>/dev/null || true

4. Analytical Reporting & Execution Guidelines

When presenting results and executing cleanup:

1. Summary Table / Key Highlights: Current free space vs total space and utilization percentage.
2. Top Consumers Breakdown: List categorized culprits (Docker, Trash, Package Caches, Logs, App Caches).
3. Actionable Recommendations with Pros/Cons:
   • Safe & Instant Wins: Trash cleanup, build cache prune (docker builder prune), dangling images only (docker image prune without -a), package cache prune.
   • Review Required: Tagged docker images, downloads folder, inactive project node_modules/venvs, browser profile caches.
4. CRITICAL SAFETY RULES FOR DOCKER & DESTRUCTIVE CLEANUP:
   • NEVER run docker system prune -a, docker image prune -a, or podman system prune -a automatically without explicit user permission. Tagged images may contain hours of build work or local development environments.
   • For regular cleanup, only use safe non-destructive commands:
     • docker image prune -f (removes only untagged/dangling images, preserves tagged images)
     • docker builder prune -f (removes build cache)
   • If proposing prune -a or mass deletion, ALWAYS ask for explicit user confirmation first, listing what will be affected.