haotianteng/FreeSpace

FreeSpace skill

Help the user reclaim disk space on a Linux machine safely. The user must always see what will be cleaned and how much it will free before anything is deleted.

Hard rules

1. Dry-run is the default. The first invocation in any conversation MUST be --dry-run. Never run a destructive cleanup before showing the user a dry-run report.
2. Never --yes without explicit user request. Do not pass --yes / -y unless the user has clearly opted into it ("just clean everything", "yes do it all", "skip the prompts"). Default to per-task confirmation via --task <name>.
3. Show sizes, then ask. After a dry-run, summarize for the user: each task name, what it targets, and the size it would free. Wait for the user to choose what to actually run.
4. Per-task execution. Prefer --task <name> over running everything in one shot. The user picks.
5. No assumptions about sudo. If a task needs root, tell the user it needs sudo and let them re-run that specific task.
6. Don't pipe output through tools that hide it. The user must see the script's output. Run it foreground.

Detect the distro

Find the script to run:

. /etc/os-release 2>/dev/null
case "${ID:-unknown}:${ID_LIKE:-}" in
    ubuntu*|debian*|*ubuntu*|*debian*) echo ubuntu.sh ;;
    fedora*|rhel*|centos*|*fedora*|*rhel*) echo fedora.sh ;;
    *) echo "unsupported: ID=$ID ID_LIKE=$ID_LIKE" >&2 ;;
esac

The scripts live next to this SKILL.md:

• ubuntu.sh — Ubuntu, Debian, Pop!_OS, Mint, Elementary (apt-based)
• fedora.sh — Fedora, RHEL, CentOS, Rocky, AlmaLinux (dnf/yum)

If the distro isn't supported, tell the user which distros are supported and stop. Don't try to adapt a script on the fly.

Default workflow

1. Detect distro → pick script
2. Run: bash <script> --dry-run
3. Parse the output, show the user a clean summary table:
     - Task name
     - Target path(s)
     - Size that would be freed
     - Whether it needs sudo
4. Ask: "Which tasks would you like me to actually run?"
5. For each task the user picked:
     - If user-level: bash <script> --task <name>
     - If sudo-needed: tell the user the exact command to run and let them run it
6. After all selected tasks are done, run `df -h /` and report the freed space.

Argument cheat sheet

The scripts accept the same flags:

Flag	Effect
--dry-run	Preview only, no changes. Use this first.
--list	List available task names
--task <name>	Run only one task
--yes / -y	Skip per-task confirmation. Don't use unless the user explicitly asks.
--help	Show script help

Available task names are common across scripts: pip, npm, trash, docker_builder, journal, oldlogs, cuda_repos, cuda_old, crash. Distro-specific tasks: apt (Ubuntu/Debian), dnf (Fedora/RHEL), abrt (Fedora/RHEL).

Run bash <script> --list to get the authoritative list for the host.

Sudo handling

User-level tasks (pip, npm, trash, docker_builder) run as the user.

System-level tasks need sudo. Do not invoke sudo on behalf of the user without asking. Instead, tell them:

Task journal needs sudo. Run this yourself: sudo bash <path>/<script> --task journal

If they're already inside a sudo bash session and explicitly asked you to run all sudo-needing tasks, you can chain them with --task for each.

Reporting back

After every cleanup run, show the user:

• Which tasks ran successfully.
• Which were skipped and why.
• The before/after df -h / so they see the actual freed space.

When things go wrong

• If the dry-run reports Size: 0 for a task, mention it but don't pester them about it.
• If du errors on a path (permission denied), surface that to the user — it usually means they need sudo.
• If a task fails mid-run, stop the batch and report which task failed before continuing.

What NOT to do

• Don't edit the scripts to add rm -rf /something/else based on the user's situation. If the script doesn't cover their use case, tell them and let them decide.
• Don't run cleanup on directories outside the script's defined targets.
• Don't suggest more aggressive cleanup (deleting /tmp, snap caches, kernels, etc.) unless the user asks for it specifically — and even then, prefer pointing them to safer alternatives (apt autoremove --purge for kernels, etc.).
• Don't suppress the script's output. The whole point is visibility.