Project folder cleanup

Skill aka-kika/akakika-skills/skills/maintenance/project-folder-cleanup

Curated, polished agent skills for building calm native apps and running AI coding agents well. Works with Claude Code, Codex, and Cursor.

Install

npx -y skills add aka-kika/akakika-skills --skill project-folder-cleanup

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

5.7 KB, as published. Nobody here has run it

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

Backup before delete — no exceptions
Scan and confirm — show paths and sizes; get approval before destructive steps
Dry-run first — always run with --dry-run until the plan is approved
Zip the backup — keep disk use small; retain the .zip, drop uncompressed folder by default
Document everything — BACKUP.md inside the backup explains what, why, and how to restore

Read Safety Rules 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

node scripts/scan-cleanup-candidates.mjs /path/to/project --json

Or human-readable:

node scripts/scan-cleanup-candidates.mjs /path/to/project

Review output with the user. Compare against Default Cleanup Targets. Add or remove paths based on user preference.

Step 3: Check git status

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

node scripts/cleanup-with-backup.mjs --project /path/to/project --dry-run

Optional custom manifest:

node scripts/cleanup-with-backup.mjs \
  --project /path/to/project \
  --targets /tmp/cleanup-targets.json \
  --dry-run

cleanup-targets.json example:

{
  "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:

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:

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 — Find common cleanup targets and report sizes
cleanup-with-backup.mjs — Backup, render manifest, zip, optionally delete
render-backup-readme.mjs — Build BACKUP.md from template (do not paste template into chat)

References

Default Cleanup Targets — What to remove, ask about, or never touch
Safety Rules — Backup ordering, failure handling, git awareness

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.