project-folder-cleanup
/project-folder-cleanup
Safely clean regenerable clutter from a project folder by scanning for build artifacts and caches, backing up every removed path into a timestamped archive with a BACKUP.md manifest, zipping the backup to save space, and only deleting originals after explicit confirmation. Use when the user asks to clean a project directory, remove node_modules, clear build output, reclaim disk space, or tidy a repo before archiving.
- Author
- aka-kika ↗
- Repository
- akakika-skills ↗
- Licence
- MIT
- Last repository change
- 12.09.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 3
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 3 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/cleanup-with-backup.mjs, scripts/render-backup-readme.mjs, scripts/scan-cleanup-candidates.mjs
What it does and when to use it
Safely clean regenerable clutter from a project folder by scanning for build artifacts and caches, backing up every removed path into a timestamped archive with a BACKUP.md manifest, zipping the backup to save space, and only deleting originals after explicit confirmation. Use when the user asks to clean a project directory, remove node_modules, clear build output, reclaim disk space, or tidy a repo before archiving.
Original author description
Safely clean regenerable clutter from a project folder by scanning for build artifacts and caches, backing up every removed path into a timestamped archive with a BACKUP.md manifest, zipping the backup to save space, and only deleting originals after explicit confirmation. Use when the user asks to clean a project directory, remove node_modules, clear build output, reclaim disk space, or tidy a repo before archiving.
How it works
- When to Use
- Core Rules
- Workflow
- Scripts
- References
- Assets
- Backup layout
- Options reference
- Edge cases
- After fixing skill output
SKILL.md preview
---
name: project-folder-cleanup
description: Safely clean regenerable clutter from a project folder by scanning for build artifacts and caches, backing up every removed path into a timestamped archive with a BACKUP.md manifest, zipping the backup to save space, and only deleting originals after explicit confirmation. Use when the user asks to clean a project directory, remove node_modules, clear build output, reclaim disk space, or tidy a repo before archiving.
version: 1.0.0
---
# Project Folder Cleanup
Remove regenerable clutter from a project folder without losing data. Every targeted path is copied into a backup first, documented in `BACKUP.md`, compressed into a zip archive, and only then removed from the project when explicitly confirmed.
## When to Use
- Clean `node_modules`, build folders, caches, or logs from a project
- Reclaim disk space before archiving or zipping a repo
- Reset a project to a fresh-build state
- Tidy a workspace after switching branches or experiments
Do **not** use it for general file organization across the whole computer — that's out of scope for this skill.
## Core Rules
1. **Backup before delete** — no exceptions
2. **Scan and confirm** — show paths and sizes; get approval before destructive steps
3. **Dry-run first** — always run with `--dry-run` until the plan is approved
4. **Zip the backup** — keep disk use small; retain the `.zip`, drop uncompressed folder by default
5. **Document everything** — `BACKUP.md` inside the backup explains what, why, and how to restore
Read [Safety Rules](references/safety-rules.md) before every run.
## Workflow
### Step 1: Choose the project
Confirm the project root path. Do not run from `$HOME` unless the user explicitly wants home-level cleanup.
### Step 2: Scan candidates
```bash
node scripts/scan-cleanup-candidates.mjs /path/to/project --json
```
Or human-readable:
```bash
node scripts/scan-cleanup-candidates.mjs /path/to/project
```
Review output with the user. Compare against [Default Cleanup Targets](references/cleanup-targets.md). Add or remove paths based on user preference.
### Step 3: Check git status
```bash
git -C /path/to/project status --short
```
Warn if targeted paths overlap with uncommitted work the user may care about.
### Step 4: Dry-run backup + cleanup plan
```bash
node scripts/cleanup-with-backup.mjs --project /path/to/project --dry-run
```
Optional custom manifest:
```bash
node scripts/cleanup-with-backup.mjs \
--project /path/to/project \
--targets /tmp/cleanup-targets.json \
--dry-run
```
`cleanup-targets.json` example:
```json
{
"items": [
{ "path": "node_modules", "category": "JavaScript deps", "reason": "npm install" },
{ "path": ".next", "category": "Next.js build", "reason": "npm run build" }
]
}
```
Present the dry-run summary and wait for explicit approval.
### Step 5: Execute backup + zip
Run **without** `--dry-run`. Omit `--confirm` on the first execution pass so originals stay in place until backup is verified:
```bash
node scripts/cleanup-with-backup.mjs --project /path/to/project
```
This creates:
```
/path/to/project/.project-cleanup-backups/
2026-05-25T12-30-00-000Z-my-app.zip # contains BACKUP.md + files/
2026-05-25T12-30-00-000Z-my-app-SUMMARY.md
```
Open the zip and confirm `BACKUP.md` lists every path correctly.
### Step 6: Delete originals (confirmed)
Only after the user verifies the archive:
```bash
node scripts/cleanup-with-backup.mjs --project /path/to/project --confirm
```
If backup already exists from step 5, pass the same `--targets` file if used.
### Step 7: Post-cleanup
- Suggest adding `.project-cleanup-backups/` to `.gitignore` if not already ignored
- Tell the user where the zip lives and how to restore (see `BACKUP.md` in the archive)
- Optionally run the project build/install to confirm everything regenerates
## Scripts
- [scan-cleanup-candidates.mjs](scripts/scan-cleanup-candidates.mjs) — Find common cleanup targets and report sizes
- [cleanup-with-backup.mjs](scripts/cleanup-with-backup.mjs) — Backup, render manifest, zip, optionally delete
- [render-backup-readme.mjs](scripts/render-backup-readme.mjs) — Build `BACKUP.md` from template (do not paste template into chat)
## References
- [Default Cleanup Targets](references/cleanup-targets.md) — What to remove, ask about, or never touch
- [Safety Rules](references/safety-rules.md) — Backup ordering, failure handling, git awareness
## Assets
- [backup-readme.template.md](assets/backup-readme.template.md) — Manifest template rendered by script
## Backup layout
Inside the zip:
```
2026-05-25T...-project-name/
├── BACKUP.md # What was removed, why, restore commands
└── files/ # Mirror of removed paths relative to project root
├── node_modules/
└── .next/
```
## Options reference
| Flag | Purpose |
|------|---------|
| `--dry-run` | Show plan only |
| `--confirm` | Delete originals after successful backup + zip |
| `--targets <json>` | Custom manifest instead of default scan |
| `--backup-root <path>` | Store backups outside the project |
| `--keep-uncompressed` | Keep folder after zipping |
## Edge cases
- **Path already missing** — skipped silently; noted in scan output
- **Backup copy fails** — stop immediately; do not delete anything
- **Zip fails** — keep uncompressed backup; do not delete originals
- **User wants `.venv` removed** — add to manifest explicitly; warn about reinstall time
- **Monorepo** — scan from repo root; paths are relative to that root
## After fixing skill output
If a cleanup run produces wrong targets, bad manifest text, or restore instructions that fail, update this skill (not just the one-off output) when the fix is general and durable.
Files in this package (7)
- SKILL.md 6 KB
- assets/backup-readme.template.md 1 KB
- references/cleanup-targets.md 2 KB
- references/safety-rules.md 2 KB
- scripts/cleanup-with-backup.mjs 9 KB
- scripts/render-backup-readme.mjs 2 KB
- scripts/scan-cleanup-candidates.mjs 6 KB
Versions
The database has no other skills named project-folder-cleanup.
Database snapshot: 13.11.2026 · package version bde8d482ba7d (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
- 100scan
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… - 100cleanup
Reclaim disk space and prune branches left behind by AI coding agents - merged or abandoned git worktrees, merged branches, stale build artifacts (node_modules, .venv, target), old archives and backups, package caches, and old agent session logs. Use when the user runs /cleanup,… - 100cleanup
Safely analyze and clean up Claude Code git worktrees with Bonsai. Use when the user asks to clean, prune, remove, audit, or reclaim disk space from Claude Code worktrees, stale agent worktrees, or .claude/worktrees directories. - 100clean-targets
Reclaim disk space by deleting cargo target/ build directories across the main checkout and every git worktree of this repo. Use whenever the user wants to clean up build artifacts, free disk space, run "cargo clean" everywhere, prune worktree build caches, or complains that the… - 100clean-dev-caches
Free disk space on a developer machine by clearing regenerable caches (npm, Bun, Yarn, pnpm, Homebrew, pip, uv, Go, Gradle, CocoaPods, Xcode DerivedData, old Playwright/Puppeteer browsers, VS Code and JetBrains caches, Docker build cache), stale project build outputs (.next,… - 100go-cache
Reclaim Go disk by clearing the build, test, fuzz, and module caches. Measures each cache first, then cleans the user-chosen scope after approval. TRIGGER when the user wants to free Go cache space ("clean go cache", "почисти go кеши", "reclaim GOMODCACHE"). DO NOT trigger for…