Workspace Hygiene
Keep this skill quiet, cheap, and user-friendly. It is for cleaning the workspace around the project, not rewriting the project.
Default Flow
Stay silent unless cleanup is explicit. Do not interrupt normal development just because a few files exist. Mention cleanup only when the user directly asks to inventory, remove, or archive workspace artifacts, or asks to reduce disk usage from generated files.
Find the workspace root. Prefer the current repo root. Do not scan the user's home directory or sibling projects unless the user names them.
Take a cheap inventory first. If Python is available, run the read-only helper:
python <skill-dir>/scripts/workspace_inventory.py --root . --summary-json --max-entries 40 --recent-hours 24
Use python3 if that is the local convention. If Python is unavailable, inspect manually with the same categories below.
If no intervention is needed, say so briefly. Do not produce a long report.
If cleanup is useful, show a compact plan. Group findings into:
- safe to remove or archive
- needs user review
- protected or skipped
Ask before changing files. Default to a dry run. Before deletion or archiving, show the exact paths and actions.
Prefer recoverable archive over delete. Move approved files to .codex-cleanup/archive/<timestamp>/ and write a manifest with original path, size, modified time, and action. Permanent deletion should require explicit user wording.
Verify after cleanup. Re-check git status or file inventory. Report only the meaningful result.
If the user wants recurring project-specific cleanup rules, suggest a small .workspace-hygiene.yml with keep/skip patterns. Do not create config files unless asked.
Categories
Safe cleanup candidates are usually untracked or ignored generated artifacts:
- cache directories such as
__pycache__, .pytest_cache, .mypy_cache, .ruff_cache, .parcel-cache, .turbo, .next/cache, node_modules/.cache
- build/test outputs such as
dist, build, coverage, htmlcov, test-results, playwright-report
- temporary files such as
*.tmp, *.bak, *.orig, *.rej, *.pyc, .coverage, log files in obvious log/output folders
- agent/eval scratch outputs when the user confirms they are no longer needed
Needs review:
- untracked source files, docs, spreadsheets, PDFs, notebooks, archives, local databases, datasets, screenshots, reports, and anything under
data/
- files modified recently, especially during the current task
- large files with unclear provenance
Protected or skipped:
.git.codex/skills and installed skill files- tracked files with modifications
.env, private keys, token files, credential stores, and secret-looking files- user-named keep paths
Safety Rules
- Never delete or rewrite tracked changes unless the user explicitly asks for that exact action.
- Never clean outside the resolved workspace root.
- Never echo secret values. Report secret-looking paths only by path and category.
- Treat databases, datasets, and archives as review-required even when they look generated.
- Keep output in the user's language when possible.
- Avoid large directory listings. Show counts and the top few largest or most relevant paths.
User-Facing Output
Use a short report by default:
Workspace cleanup plan
Root: <path>
Safe candidates: <count>, <size>
Needs review: <count>, <size>
Skipped/protected: <count>
Recommended action:
- Archive safe candidates to .codex-cleanup/archive/<timestamp>/
- Review these paths before touching them: ...
If the user wants action, ask for one concise confirmation unless they already gave explicit approval for the exact paths and action.
1---2name: workspace-hygiene3description: Use this skill only when the user explicitly asks for a dry-run cleanup inventory, disk-space cleanup, deletion review, or recoverable archiving of generated workspace artifacts in a coding repo, such as caches, logs, test reports, screenshots, temporary databases, eval outputs, build outputs, or agent scratch files. Do not trigger just because the user says a repo is messy, asks for code review, asks for git status, wants README/docs cleaned up, requests memory cleanup, or asks for ordinary coding/testing/refactoring. If cleanup or archive/removal of workspace artifacts is not the main request, do not use this skill.4---56# Workspace Hygiene78Keep this skill quiet, cheap, and user-friendly. It is for cleaning the workspace around the project, not rewriting the project.910## Default Flow11121. **Stay silent unless cleanup is explicit.** Do not interrupt normal development just because a few files exist. Mention cleanup only when the user directly asks to inventory, remove, or archive workspace artifacts, or asks to reduce disk usage from generated files.132. **Find the workspace root.** Prefer the current repo root. Do not scan the user's home directory or sibling projects unless the user names them.143. **Take a cheap inventory first.** If Python is available, run the read-only helper:1516 ```bash17 python <skill-dir>/scripts/workspace_inventory.py --root . --summary-json --max-entries 40 --recent-hours 2418 ```1920 Use `python3` if that is the local convention. If Python is unavailable, inspect manually with the same categories below.214. **If no intervention is needed, say so briefly.** Do not produce a long report.225. **If cleanup is useful, show a compact plan.** Group findings into:23 - safe to remove or archive24 - needs user review25 - protected or skipped266. **Ask before changing files.** Default to a dry run. Before deletion or archiving, show the exact paths and actions.277. **Prefer recoverable archive over delete.** Move approved files to `.codex-cleanup/archive/<timestamp>/` and write a manifest with original path, size, modified time, and action. Permanent deletion should require explicit user wording.288. **Verify after cleanup.** Re-check git status or file inventory. Report only the meaningful result.2930If the user wants recurring project-specific cleanup rules, suggest a small `.workspace-hygiene.yml` with keep/skip patterns. Do not create config files unless asked.3132## Categories3334Safe cleanup candidates are usually untracked or ignored generated artifacts:3536- cache directories such as `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.parcel-cache`, `.turbo`, `.next/cache`, `node_modules/.cache`37- build/test outputs such as `dist`, `build`, `coverage`, `htmlcov`, `test-results`, `playwright-report`38- temporary files such as `*.tmp`, `*.bak`, `*.orig`, `*.rej`, `*.pyc`, `.coverage`, log files in obvious log/output folders39- agent/eval scratch outputs when the user confirms they are no longer needed4041Needs review:4243- untracked source files, docs, spreadsheets, PDFs, notebooks, archives, local databases, datasets, screenshots, reports, and anything under `data/`44- files modified recently, especially during the current task45- large files with unclear provenance4647Protected or skipped:4849- `.git`50- `.codex/skills` and installed skill files51- tracked files with modifications52- `.env`, private keys, token files, credential stores, and secret-looking files53- user-named keep paths5455## Safety Rules5657- Never delete or rewrite tracked changes unless the user explicitly asks for that exact action.58- Never clean outside the resolved workspace root.59- Never echo secret values. Report secret-looking paths only by path and category.60- Treat databases, datasets, and archives as review-required even when they look generated.61- Keep output in the user's language when possible.62- Avoid large directory listings. Show counts and the top few largest or most relevant paths.6364## User-Facing Output6566Use a short report by default:6768```text69Workspace cleanup plan70Root: <path>71Safe candidates: <count>, <size>72Needs review: <count>, <size>73Skipped/protected: <count>7475Recommended action:76- Archive safe candidates to .codex-cleanup/archive/<timestamp>/77- Review these paths before touching them: ...78```7980If the user wants action, ask for one concise confirmation unless they already gave explicit approval for the exact paths and action.
Lord1Egypt