| name | cleanup |
| description | Clean up temporary files and session artifacts after completing a task. Use when
user says "cleanup", "clean", "tidy up", "清理", or before committing / open-sourcing.
Identifies: one-off node_modules, MCP session logs (.playwright-mcp), generated
documents (demo.docx), empty npm scaffolding, Python __pycache__, OS junk files
(.DS_Store, Thumbs.db), Claude Code artifacts (tmpclaude-*, .claude/plans/), and
other disposable build/test artifacts. Optionally invokes darwin-skill for
self-evolution after each cleanup.
|
| author | Claude Code |
| version | 1.0.0 |
| date | "2026-05-03T00:00:00.000Z" |
| allowed-tools | ["Bash","Read","Write","Edit","Grep","Glob","AskUserQuestion"] |
Cleanup — Session Artifact Cleaner
A Claude Code skill that scans, confirms, and removes temporary files generated
during coding sessions — safely and transparently.
When to Use
YOU MUST invoke this skill when the user says: "cleanup", "clean", "tidy up",
"清理", "删掉临时文件", "提交前清理", "开源前清理".
Also invoke proactively after completing a complex multi-step task that likely
generated scaffolding, test documents, or one-off dependencies.
Core Principles
- Safety first: when in doubt, keep it and ask the user.
- Checkpoint-driven: user confirmation before deletion, self-check after.
- Transparent: every deleted file is explained — what it was and why it's safe to remove.
Step 1: Scan & Catalog
Scan the current directory and list all candidate files for deletion,
grouped by category. For each file, explain its purpose and why it's disposable.
Scan Categories
| # | Category | Match Pattern | Heuristic |
|---|
| 1 | npm one-off deps | node_modules/ + package.json | package.json has no real project logic (only name/version/single utility dep like docx) |
| 2 | Generated documents | *.docx, *.pptx, *.pdf | Filename contains demo, test, output, sample — generated by skills, not hand-written |
| 3 | MCP session logs | .playwright-mcp/, console-*.log, page-*.yml, network-*.json | Browser automation session artifacts — 100% disposable |
| 4 | Empty scaffolding | package.json + package-lock.json | package.json has only name/version/single dep, no scripts with real logic |
| 5 | Orphaned lock files | package-lock.json without package.json | Leftover from deleted scaffolding |
| 6 | Claude Code temp | tmpclaude-*-cwd/, nul files | Known CC bug on Windows (issue #17783) |
| 7 | Python cache | __pycache__/, *.pyc, *.pyo | Bytecode cache — regenerated on next import |
| 8 | OS junk | .DS_Store, Thumbs.db, desktop.ini | OS filesystem metadata — never part of a project |
| 9 | One-off venv | .venv/, venv/ | Only if not in .gitignore and requirements.txt/pyproject.toml absent |
| 10 | Test artifacts | coverage/, .nyc_output/, htmlcov/, .pytest_cache/ | Test runner output — regenerated on next run |
| 11 | Build artifacts | dist/, build/, *.egg-info/ | Only if pyproject.toml/setup.py absent or this is a one-off script |
| 12 | Claude Code plans | .claude/plans/ | Session plan files — regenerated per-session, not reusable |
| 13 | Empty directories | Any empty dir | Check it's not a required mount point or config path |
Output Format
For each candidate, output one of:
[DEPRECATED] path/to/file (size) — what it is, why it can be deleted
[NEEDS REVIEW] path/to/file (size) — what it is, why unsure
Exclusion Rules — NEVER Delete
These are unconditionally protected, regardless of user request:
| Protected | Reason |
|---|
.git/ | Version control history |
.claude/settings.json, .claude/settings.local.json | Project configuration |
.claude/scheduled_tasks.json | May contain active cron jobs — migrate first if needed |
src/, app/, pages/, components/, lib/, utils/ | Source directories |
*.gitignore-listed files | Intentionally ignored = intentionally kept |
README.md, LICENSE, CHANGELOG.md, CONTRIBUTING.md | Project documentation |
requirements.txt, pyproject.toml, Cargo.toml, go.mod | Actual project dependency declarations |
.env, .env.* | Environment files (flag if contains secrets, but never delete) |
Dockerfile, docker-compose.yml | Infrastructure definitions |
Makefile, Justfile | Build system entry points |
Step 2: Confirm
Use AskUserQuestion to confirm deletions. Present options:
"Delete these files?"
Options:
- "Delete All" — remove all [DEPRECATED] files
- "Review Each" — confirm one at a time
- "Cancel" — keep everything
For each [NEEDS REVIEW] file, ask separately with an explanation of the uncertainty.
Step 3: Execute & Verify
Execute
rm -rf [confirmed files and directories]
For nul files on Windows (can't be deleted natively):
wsl rm -f /mnt/c/path/to/nul
Self-Check
Immediately after deletion, verify:
git status — no git-tracked files were deleted- Project integrity — if
package.json remains, npm ls succeeds
- Config integrity —
.claude/ essential files still present
- No broken imports — if source files deleted, check remaining files don't import them
Rollback
If the self-check detects a problem:
- Report immediately:
"Detected [file] was incorrectly deleted — may affect [function]"
- Ask:
"Restore from git?" → git checkout -- [file] or git restore [file]
- If not in git, ask if the user has a backup
Step 4: Self-Evolution (Optional)
If darwin-skill is installed, invoke it after each cleanup to improve this skill.
4a: Log the Cleanup
Append to ~/.claude/skills/cleanup/cleanup_log.jsonl:
{
"date": "ISO-8601",
"project": "project-directory-name",
"deleted": [
{"path": "relative/path", "category": "category-name", "size": "human-readable"}
],
"kept": ["files-user-chose-to-keep"],
"user_notes": "any user feedback"
}
4b: Invoke Darwin
If ~/.claude/skills/darwin-skill/SKILL.md exists:
Skill(darwin-skill, "optimize cleanup skill. This session deleted [N] files
([categories]). User kept [M] files. Review cleanup_log.jsonl for patterns
and improve SKILL.md accordingly.")
If darwin-skill is not installed, skip this step silently.
Step 5: Report
Output a structured summary:
## Cleanup Report
**Before**: [total size]
**After**: [total size]
**Freed**: [delta]
**Deleted**:
- file1 (size) — reason
- file2 (size) — reason
**Kept**:
- file3 — reason kept
**Self-Check**: all-clear / issues-found
**Darwin**: optimized / skipped (not installed)
**Tip**: [any additional optimization suggestion]
Known Issues
Windows: tmpclaude-*-cwd and nul Files
Claude Code has a known bug on Windows where sub-agent worktrees
(tmpclaude-*-cwd/) and literal nul files (from /dev/null not being
translated to NUL) are left behind after sessions.
nul files cannot be deleted by Windows native tools (reserved device name).
Use WSL: wsl rm -f /mnt/c/path/to/nul- Reference: Claude Code issue #17783
- Feature request for auto-cleanup: issue #11963
.claude/plans/ Accumulation
Plans are created per-session and can accumulate over time. They are safe to
delete — Claude Code regenerates them as needed. However, if a plan was
carefully crafted and may be reused, flag it as [NEEDS REVIEW] instead.
Pre-Deletion Checklist
Before executing any deletion, verify:
Examples
Example 1: After generating a Word document
Scan results:
[DEPRECATED] node_modules/ (8.9 MB) — installed only for docx generation
[DEPRECATED] package.json (294 B) — scaffolding for docx, no project logic
[DEPRECATED] package-lock.json (8 KB) — lock file for scaffolding
[DEPRECATED] demo.docx (12 KB) — generated test document
[DEPRECATED] .playwright-mcp/ (12 KB) — browser session logs
→ User confirms "Delete All"
→ Freed: ~9 MB
→ Self-check: git status clean
Example 2: Python project with cache
Scan results:
[DEPRECATED] __pycache__/ (1.2 MB) — Python bytecode cache
[DEPRECATED] .pytest_cache/ (48 KB) — pytest cache
[DEPRECATED] .DS_Store (6 KB) — macOS metadata
→ User confirms "Delete All"
→ Freed: ~1.3 MB
→ Self-check: pytest still passes
