A small, portable Agent Skill for auditing and safely reclaiming disk space on Linux. It is designed for Claude Code, Codex, Cursor, and other clients that support the Agent Skills specification.
The skill is intentionally instruction-only: there is no universal cleanup script and no direct deletion of managed storage. Its operating contract is:
audit → propose → approve → execute one → verify
Broad requests stay non-mutating until the user selects an exact operation. Personal files, configuration, backups, snapshots, application data, stopped-container writable layers, and container volumes are preserved by default.
- filesystem space and inode diagnosis, including snapshot-aware Btrfs accounting
- APT, DNF 4, DNF 5, and pacman package cleanup
- systemd journal and
logrotate-managed log retention - Snap revision and data-snapshot inventory; removal remains high-risk
- Flatpak unused runtimes and extensions, in an explicit installation
- Docker and Podman objects, one category and local daemon/store at a time
- application caches, only through an identified owner's documented cleaner
Unsupported or ambiguous tools fall back to audit and explanation; the agent must not guess a cleanup command.
Clone the repository:
git clone https://github.com/Lucenx9/linux-cleanup-skill.gitFor Codex or Cursor, copy the skill into the user skill directory:
mkdir -p ~/.agents/skills
cp -R linux-cleanup-skill/skills/linux-cleanup ~/.agents/skills/For Claude Code:
mkdir -p ~/.claude/skills
cp -R linux-cleanup-skill/skills/linux-cleanup ~/.claude/skills/You can instead copy skills/linux-cleanup into a project's .agents/skills/ or .claude/skills/ directory. Cursor also supports .cursor/skills/.
My root filesystem is almost full. Audit it and show me safe cleanup options.
Inspect Docker disk use, but do not prune anything yet.
Run only the approved APT cache cleanup, then show the before/after disk space.
The format and authoring choices follow primary documentation:
- Agent Skills specification
- OpenAI: Build skills
- Anthropic: Skill authoring best practices
- Claude Code skills
- Cursor Agent Skills
The workflow adapts the strongest ideas from pstack—authoritative audit, boundary discipline, idempotent retries, small verifiable units, and evidence after mutation—without copying its worktree-specific deletion assumptions:
Cleanup semantics are grounded in upstream manuals for GNU df, GNU du, Btrfs, APT, DNF 4, DNF 5, paccache, journalctl, logrotate, Snap, Flatpak, Docker, and Podman.
Distribution guidance was checked against a local, versioned copy of ArchWiki and current Debian, Ubuntu, Fedora, Gentoo, and openSUSE documentation. When a wiki passage conflicts with a current upstream command reference, the upstream project documentation and the installed command's help take precedence. See the upstream audit and the distribution-wiki follow-up.
MIT