Skip to content
Skills Library
Programming · Automation

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.

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

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

Licence

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

What to check before installing
  • 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

  1. When to Use
  2. Core Rules
  3. Workflow
  4. Scripts
  5. References
  6. Assets
  7. Backup layout
  8. Options reference
  9. Edge cases
  10. After fixing skill output
Original SKILL.md headings · 163 lines, 719 words
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…

Feedback and reports

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