Skip to content
Skills Library
Personal productivity · Review & audit

scan

/scan

Break down how much space a project folder or directory uses and which of it can be safely reclaimed (node_modules, build output, caches, logs, git worktrees). Use when asked why a folder or project is huge, how to free up space in it, or whether something in it is safe to delete. Read-only; never deletes without confirmation; git-aware. For the whole machine, use /disk-reclaim:system.

Licence
MIT
Last repository change
05.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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

What it does and when to use it

Break down how much space a project folder or directory uses and which of it can be safely reclaimed (node_modules, build output, caches, logs, git worktrees). Use when asked why a folder or project is huge, how to free up space in it, or whether something in it is safe to delete. Read-only; never deletes without confirmation; git-aware. For the whole machine, use /disk-reclaim:system.

Arguments

/scan [DIR]
Original author description

Break down how much space a project folder or directory uses and which of it can be safely reclaimed (node_modules, build output, caches, logs, git worktrees). Use when asked why a folder or project is huge, how to free up space in it, or whether something in it is safe to delete. Read-only; never deletes without confirmation; git-aware. For the whole machine, use /disk-reclaim:system.

How it works

  1. 1. Run the scanner
  2. 2. Read the result, then add judgment
  3. 3. Purging SAFE items (the built-in purge option)
  4. 4. Other deletions (only after the user says yes)
  5. Notes
Original SKILL.md headings · 52 lines, 642 words
SKILL.md preview
---
name: scan
description: Break down how much space a project folder or directory uses and which of it can be safely reclaimed (node_modules, build output, caches, logs, git worktrees). Use when asked why a folder or project is huge, how to free up space in it, or whether something in it is safe to delete. Read-only; never deletes without confirmation; git-aware. For the whole machine, use /disk-reclaim:system.
argument-hint: "[DIR]"
---

# scan

Plugin root: `${CLAUDE_PLUGIN_ROOT}`. Scripts are in `${CLAUDE_PLUGIN_ROOT}/scripts/`; shared guidance is in `${CLAUDE_PLUGIN_ROOT}/references/`.

Scan the directory in `$ARGUMENTS` (default: the current directory). Answer two questions: **where is the space going**, and **what can be given back without losing anything that cannot be rebuilt**. Analysis is read-only. Deleting is a separate, confirmed step.

**Non-negotiables** (full text in `${CLAUDE_PLUGIN_ROOT}/references/deletion-rules.md`, read it before removing anything):

- Show a dry run first. Remove nothing until the user has approved the items by name.
- Re-check each item immediately before it runs; skip and report any that changed.
- Prefer reversible actions. Never use `--force`, `git clean -x` or `git reset --hard`, and never delete branches, unless the user asks for that exact thing.
- Never propose KEEP items, and never promote a VERIFY item because it is old.

## 1. Run the scanner

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/scan.py [DIR] [--top 15] [--min-mb 20] [--max-depth 6]
```

`DIR` defaults to the current directory. It prints markdown: largest subdirectories, reclaimable items grouped by safety tier and category, git worktrees, large files, and proposed (not executed) commands. Add `--json` if you need to post-process, `--min-mb 0 --top 200` to see small items.

On a very large tree the scan can take a few minutes (it honours `--max-seconds` and says so if it stopped early). If the user points it at a home directory or `/`, narrow it first (for example the projects folder) because a whole-disk scan mostly finds things nobody wants removed.

## 2. Read the result, then add judgment

The script classifies; you decide what to say. Present a short summary first (total, free space, the few biggest wins), then the tables. Keep it compact: sizes human-readable, top N only.

Read `${CLAUDE_PLUGIN_ROOT}/references/tiers-and-gates.md` for what SAFE, VERIFY and KEEP mean and how to treat each. If the result looks surprising (a "SAFE" item you doubt, a huge KEEP), check it yourself rather than repeating the label.

## 3. Purging SAFE items (the built-in purge option)

After the report, offer to purge the SAFE items. Ask which categories (build caches, build output, dependency caches) and confirm the policy, because it is a judgment about the user's workflow, not a fact: by default the purge keeps build output in **high-traffic checkouts** (a normal clone, and any worktree named `main`) so they stay ready to build and run, and clears the same output from linked worktrees and other low-traffic copies, where it only takes up space.

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/scan.py DIR --json > /tmp/scan.json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/reclaim.py /tmp/scan.json --categories "build cache,build output" --exclude some/path   # dry run
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/reclaim.py /tmp/scan.json --categories "build cache,build output" --exclude some/path --execute
```

`reclaim.py` is a dry run unless `--execute` is given. It re-verifies every item at that moment (still git-ignored, no tracked files, no key material, manifest beside it), skips any checkout with a process running in it, removes only directories with known derived-output names, writes a log, and reports the free space gained. Always show the user the dry-run table first, and exclude any single item they are unsure of (a huge `build/` folder can be a packaged deliverable). Use `--no-protect` only if the user asks to clear the high-traffic checkouts too.

## 4. Other deletions (only after the user says yes)

Read `${CLAUDE_PLUGIN_ROOT}/references/deletion-rules.md` and follow it: show the exact commands and the space they free, re-check just before acting, prefer reversible actions, and report what was removed, what was skipped and why.

## Notes

- Sizes are block usage from `du`; hard-linked or copy-on-write files (pnpm stores, APFS clones) can make real savings smaller.
- Works on macOS and Linux with no configuration and no paths baked in. Standard library Python 3 only; needs `du`, and `git` for the repository-aware checks.
- **This tool deletes data** once `reclaim.py --execute` is given, after the dry run and the user's approval. Provided as is, without warranty (MIT licence).

Versions

RepositoryScoreLicence
This page · jwill824/claude-plugins100MIT
tony/skills100MIT
zealynxsecurity/krait100MIT
koda-ai-studio/agent-bom100Apache-2.0
cwinvestments/memstack100MIT
x-cmd/x-cmd100Apache-2.0
duc01226/EasyPlatform100MIT
duc01226/EasyPlatform100MIT
wshobson/agents100MIT

Database snapshot: 13.11.2026 · package version 894b6b368efa (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

  • 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…
  • 100cleanup
    Free up disk space on this computer: list what takes space with its size, why it is safe to delete and what it costs, then delete only what the owner picks. Use when someone says "cleanup", "clean up disk", "free up space", "my disk is full", "out of space", "the Mac is full",…
  • 100safe-disk-cleanup
    Safely diagnose and reclaim disk space on developer machines with explainable deletion decisions, deep read-only inventory, worktree and Docker auditing, active-tool guards, and file-level dry-runs. Use when a disk is full, storage is low, developer resources are large, or the…
  • 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'.
  • 100mac-storage-cleaner
    Safely reclaim disk space on a Mac — the trustworthy, transparent, reversible alternative to CleanMyMac and similar tools. Use whenever the user says their Mac disk or storage is full or nearly full, gets a "startup disk almost full" / low-storage warning, asks to free up space,…
  • 100mac-storage-saver
    Find what is using disk space on a Mac and free it safely. Scans the disk read-only, sorts every large folder into safe to clean, reinstall needed, your call and don't touch, builds an HTML report with an approval checklist, then deletes only the items the user approves. Use…

Feedback and reports

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