What does Tidy Skill do?
Stop AI agents from littering your repo with
plan.md,todo.md,summary.md, and throwaway artifacts. Don't let AI agents turn your project root into a Markdown landfill.
This is not a Markdown deleter. This Skill governs the local environment where agents work: repository artifacts, workspace caches, WSL2/Docker storage, package-manager caches, model caches, and agent/IDE state.
A file or cache is not garbage just because it is large. It becomes a hygiene risk when it has no intent, no owner, no reader, no lifecycle, and no recovery path. The goal is not to delete aggressively — it is to ensure every artifact, cache, and local environment footprint has a purpose, a place, and a safe next action.
1. Hygiene Model
Use a three-layer model:
| Layer | Scope | Examples | Default action |
|---|---|---|---|
| Repository | Agent-created artifacts | plan.md, todo.md, .agent_tmp/, .agent_reports/ | classify, report, DryRun cleanup |
| Workspace | Development caches across projects | node_modules, .venv, target, build caches | audit, score, recommend |
| Local machine | Toolchains and virtualized environments | WSL2, Docker Desktop, package caches, model caches, agent/IDE state | read-only map, risk bucket, manual guidance |
Reports should separate:
Findings— facts observed locally.Safe Suggestions— low-risk next steps such as running DryRun or moving future reports into.agent_reports/.Manual / Risky Operations— migration, VHDX compaction, Docker data relocation, model cache relocation, or config edits. Never perform these automatically.
2. When to Use This Skill
Invoke this Skill when the user asks about:
| Trigger | Examples |
|---|---|
| Tidy / organize | "tidy up project directory", "clean up this repo", "organize my project" |
| Generate artifacts | "write a plan", "generate a report", "create a plan/todo/summary/report/audit" |
| Audit | "audit project files", "scan for agent artifacts", "list suspicious files" |
| Clean up | "clean agent files", "clean agent temp files", "delete temporary files" |
| Decide | "should I create this file or keep it in chat?" |
| Score | "repo hygiene score", "how clean is my repo?" |
| Workspace audit | "scan workspace", "audit my workspace", "find agent artifacts across repos" |
| Local environment audit | "audit my local environment", "inspect local agent environment", "where are my dev caches" |
| Create rules | "create AGENTS.md / CLAUDE.md / Cursor Rules" |
| Task completion | Wrap-up hygiene check before exiting |
| Pollution | "multiple agents writing files haphazardly", "project root is a mess of markdown" |
| Complaint | "stop generating junk documents", "clean up plan.md / todo.md" |
| Env Inspect | "inspect my coding environment", "where is node/python/go installed?" |
| Drive Growth | "why is my C drive growing?", "find package/model caches" |
| WSL2 / Docker | "WSL2 is taking too much space", "Docker Desktop disk is huge", "where is ext4.vhdx" |
| Model caches | "Ollama/Hugging Face models on C drive", "AI model cache audit" |
| Agent state | "Claude/Codex/Cursor state locations", "agent config/cache footprint" |
3. When NOT to Use This Skill (Never Do)
Stop and ask the user or strictly avoid if the request involves:
- Deleting formal project documentation
- Modifying user-written notes
- Cleaning source code (
src/,lib/,app/) - Touching tool state directories (
.codex/,.claude/,.cursor/,.vscode/,*.sqlite,state.json,session.json,workspaceStorage,globalStorage,auth-token) - Unconfirmed mass Markdown deletion
- Force-deleting Git-tracked files
- Cleaning unknown Markdown in personal/user folders
- Modifying system settings or registry
- Registering scheduled tasks
- Uploading logs, reports, credentials, or environment data
- Scanning the whole computer without an explicit user-specified root scope
- Reading auth tokens, session files, sqlite databases, or private logs
- Deleting tool or model caches just because they are large
- Moving tools or rewriting environment variables without a separate explicit migration request
- Compacting WSL/Docker VHDX files
- Exporting/importing WSL distributions
- Editing
.wslconfig, Docker settings, shell profiles, or package manager config
4. Artifact Classification
Every file an agent creates belongs to one of five classes. Class — not extension — determines treatment.
| Class | Examples | Home | Lifecycle | Auto-delete? |
|---|---|---|---|---|
| A — Formal Documentation | README.md, CHANGELOG.md, LICENSE, docs/**, CONTRIBUTING.md, user notes | docs/, project root | Permanent | Never |
| B — User-requested Deliverables | audit report, migration plan, research write-up (user explicitly asked) | .agent_reports/ | 30 days | After retention |
| C — Temporary Working Artifacts | plan, todo, notes, scratch, progress, task_list | .agent_tmp/ | 7 days | After retention |
| D — Self-congratulatory | summary, final_report, work_summary, lessons, changes_summary | Do not create | N/A | N/A |
| E — Tool State (out of scope) | .codex/, .claude/, .cursor/, *.sqlite, state files | Tool dirs | N/A | Never |
Key rules:
- Class A → never auto-delete, never auto-rewrite
- Class B → specific filename
<task>_<date>.md, never in project root - Class C →
.agent_tmp/only, never committed, clean at task end - Class D → do not create. The chat is the summary.
- Class E → completely ignore, never mark as suspicious
5. Artifact Intent Check (MANDATORY)
Before creating any new file, fill out this check. If you cannot answer every field, do not create the file.
Artifact Intent Check
─────────────────────
1. User requested a file? yes / no
2. Purpose:
3. Reader:
4. Expected lifetime: session / days / persistent / formal-doc
5. Destination path:
6. Why a chat response is not enough:
7. Class: temporary / persistent / formal-documentation
8. Should this be in .gitignore? yes / no
Decision rules:
| Scenario | Action |
|---|---|
| #1 = no, class ≠ A | Do not create. Answer in chat. |
| Purpose = plan/todo/summary/progress, reader = this user | Chat only. No file. |
| Must create, class = C | .agent_tmp/<specific-name>.md |
| Must create, class = B | .agent_reports/<task>_<YYYY-MM-DD>.md |
| Class = A (formal doc) | docs/ path, user explicitly requested |
| File restates this chat | Do not create |
| No clear reader | Do not create |
| No clear lifecycle | Do not create |
| No follow-up use | Do not create |
6. Hard Rules for File Generation
- Default: do not write files.
- Plans, todos, summaries, progress → answer in chat.
- Project root is forbidden for generic process Markdown unless the user explicitly names a file.
- Forbidden in project root (unless user explicitly asks for that exact file):
todo.md, plan.md, notes.md, lessons.md, summary.md, report.md, final_report.md, implementation_plan.md, migration_plan.md, audit_report.md, cleanup_report.md, task_list.md, progress.md, work_summary.md, changes_summary.md, *_summary.md, *_report.md, *_plan.md - Temporary files →
.agent_tmp/ - Persistent reports →
.agent_reports/ - Formal docs →
docs/(only when explicitly requested) - Do not generate reports to "look professional."
- Do not auto-create end-of-task summary files.
- Do not duplicate chat into files.
- Use specific filenames:
<task>_<context>_<date>.md - If user asks for a file, propose path + filename first.
- If user says "tell me" / "summarize" / "plan it" → answer in chat.
7. Allowed and Forbidden Locations
Allowed
| Content | Allowed location |
|---|---|
| Temporary working files | .agent_tmp/ |
| User-requested reports | .agent_reports/ |
| Formal documentation | docs/ (explicit request required) |
| User-specified path | Any path the user explicitly named |
Forbidden
| Location | Why |
|---|---|
| Project root (generic process Markdown) | Reserved for formal repo files |
src/, lib/, app/ | Source directories |
.codex/, .claude/, .cursor/, .vscode/ | Tool state — do not touch |
8. Protected Files (Never Auto-delete)
README.md, README.*.md
CHANGELOG.md
LICENSE, LICENSE.*
CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md
Everything under docs/
Any Git-tracked file outside .agent_tmp/ or .agent_reports/
User hand-written notes
9. Lifecycle
| Location | Default retention | Cleanup |
|---|---|---|
.agent_tmp/ | 7 days | Agent should clean its own at task end |
.agent_reports/ | 30 days | Move to docs/ for long-term keeping |
docs/ | Permanent | No auto-lifecycle |
10. Repo Hygiene Score
When asked for a repo hygiene score, prefer ${CLAUDE_SKILL_DIR}/scripts/score_repo_hygiene.py when Python is available. On Windows-only environments, use ${CLAUDE_SKILL_DIR}/scripts/score-repo-hygiene.ps1.
| Score | Rating (en) |
|---|---|
| 90–100 | Clean |
| 70–89 | Mostly clean |
| 50–69 | Needs tidy-up |
| 0–49 | Artifact landfill |
Dimensions: root cleanliness, artifact placement, protected docs clarity, Git hygiene, agent state isolation, cleanup readiness. Optional weight factors: --weights references/score-weights.example.json.
Optional project policy: place .tidy-skill.json (or tidy-skill.policy.json) at the repo root, or pass --policy. Schema example: references/tidy-skill.policy.example.json. Policy can extend forbidden/protected root patterns, set min_score, require .agent_tmp/ + .agent_reports/, and opt intentional planning-layout root names via planning_root_globs (see references/tidy-skill.policy.pwf.example.json for planning-with-files coexistence). .planning/** is recognized as intentional Class C working memory without a policy.
Doctor, repair, classify, snapshots
| Need | Script |
|---|---|
| One-shot install + hygiene doctor / CI gate | ${CLAUDE_SKILL_DIR}/scripts/tidy_doctor.py |
| DryRun-first safe repairs (layout dirs; optional root moves) | ${CLAUDE_SKILL_DIR}/scripts/tidy_repair.py |
| DryRun host hook config emitter | ${CLAUDE_SKILL_DIR}/scripts/tidy-install-hooks.py |
Classify a path before writing (Classes A–E); batch via --stdin --json | ${CLAUDE_SKILL_DIR}/scripts/classify_artifact.py |
Save/compare score history; gate on min_score | ${CLAUDE_SKILL_DIR}/scripts/hygiene_snapshot.py |
Safety verbs (always the same meaning):
- dryrun — preview only (default for repair, cleanup, install-hooks)
- careful — mutates agent working files only (
tidy_repair.py --apply --move-root) - guard — hard refuse host configs, VHDX, Docker data, git-tracked files, Class A docs
tidy_repair.py is the diagnose→next-step companion to doctor. Default is a plan only. --apply creates .agent_tmp/ + .agent_reports/ with .gitkeep. Root process moves need both --apply and --move-root, and still refuse git-tracked / protected names.
hygiene_snapshot.py save writes under .agent_reports/hygiene-history/ by default (Class B deliverable history, not root litter). gate and doctor exit 2 on hygiene/policy failure.
11. Workspace Hygiene Audit
When asked to scan multiple repos, prefer ${CLAUDE_SKILL_DIR}/scripts/audit_workspace_hygiene.py for a portable baseline. On Windows-only workflows, ${CLAUDE_SKILL_DIR}/scripts/audit-workspace-hygiene.ps1 is also fine. The user must explicitly specify a root directory. Never default to scanning entire drives.
For a single-repo agent artifact audit, prefer ${CLAUDE_SKILL_DIR}/scripts/audit_agent_artifacts.py when Python is available. Use ${CLAUDE_SKILL_DIR}/scripts/audit-agent-artifacts.ps1 when staying in a PowerShell workflow. Both audit and score accept optional --policy.
Optional end-of-task read-only check: ${CLAUDE_SKILL_DIR}/hooks/stop-hygiene-check.py (reports only; never deletes). Trigger phrases live in commands/TRIGGERS.md.
12. Local Machine Hygiene Audit
When asked about C-drive growth, WSL2, Docker Desktop, model caches, package caches, agent state, or local development environment sprawl, use ${CLAUDE_SKILL_DIR}/scripts/audit-dev-environment.ps1.
For portable package/model cache mapping on non-Windows environments, use ${CLAUDE_SKILL_DIR}/scripts/audit_dev_environment.py. Use the PowerShell script for Windows-specific WSL2/Docker VHDX inspection.
Rules:
- Ask for explicit scan roots when project/workspace scanning is needed.
- Use
-IncludeUserProfileonly when the user wants default user-profile cache locations included. - Use
-IncludeDrivesonly when the user explicitly asks for drive-level hints. - Treat WSL/Docker migration, VHDX compaction, Docker data relocation,
.wslconfigedits, and model cache relocation asManual / Risky Operations. - Never read tokens, session files, SQLite databases, registry keys, private logs, or credential stores.
For WSL2 and Docker details, read references/wsl2-docker-hygiene.md.
13. Cleanup Rules
Allowed auto-cleanup:
.agent_tmp/— files older than 7 days.agent_reports/— files older than 30 days- User-specified agent temp directory
- Named, expired, agent-created process files
Forbidden auto-cleanup:
- Protected docs (Class A)
- Source code
- Tool state (Class E)
- Unknown Markdown in user folders
- Git-tracked files
- Root-level suspicious files → report only, ask user
14. Audit Rules
- Read-only — never modifies files
- Bounded depth, skips
.git/,node_modules/,dist/,build/,target/,.venv/,venv/ - Lists:
.agent_tmp/,.agent_reports/, root-level suspicious files, protected docs - Suggests actions, performs none
- No upload or network calls
15. End-of-Task Checklist
Before reporting "done":
- Did I create any files? Were each justified by an Artifact Intent Check?
- Are