tidy-skill

洁癖.skill

Stop AI agents from littering your repo with plan.md, todo.md, summary.md, and throwaway artifacts. 别让 AI Agent 把你的项目根目录变成 Markdown 垃圾场。

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:

Reports should separate:

1. Findings — facts observed locally.
2. Safe Suggestions — low-risk next steps such as running DryRun or moving future reports into .agent_reports/.
3. 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:

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.

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:

6. Hard Rules for File Generation

1. Default: do not write files.
2. Plans, todos, summaries, progress → answer in chat.
3. Project root is forbidden for generic process Markdown unless the user explicitly names a file.
4. 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
   

5. Temporary files → .agent_tmp/
6. Persistent reports → .agent_reports/
7. Formal docs → docs/ (only when explicitly requested)
8. Do not generate reports to "look professional."
9. Do not auto-create end-of-task summary files.
10. Do not duplicate chat into files.
11. Use specific filenames: <task>_<context>_<date>.md
12. If user asks for a file, propose path + filename first.
13. If user says "tell me" / "summarize" / "plan it" → answer in chat.

7. Allowed and Forbidden Locations

Allowed

Forbidden

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

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.

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

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:

1. Ask for explicit scan roots when project/workspace scanning is needed.
2. Use -IncludeUserProfile only when the user wants default user-profile cache locations included.
3. Use -IncludeDrives only when the user explicitly asks for drive-level hints.
4. Treat WSL/Docker migration, VHDX compaction, Docker data relocation, .wslconfig edits, and model cache relocation as Manual / Risky Operations.
5. 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:

1. .agent_tmp/ — files older than 7 days
2. .agent_reports/ — files older than 30 days
3. User-specified agent temp directory
4. 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":

1. Did I create any files? Were each justified by an Artifact Intent Check?
2. Are any of my files in the project root that should not be?
3. Are any of my .agent_tmp/ files safe to delete now?
4. Did I avoid creating summary.md / final_report.md / work_summary.md?
5. If user wants archival, did I propose .agent_reports/ or docs/?

16. Safety Boundaries

This Skill and its scripts:

• Do not modify system settings or registry
• Do not register scheduled tasks
• Do not require admin/root privileges
• Do not perform full-disk scans (user must specify roots)
• Do not delete formal documentation
• Do not delete tool state files
• Do not delete Git-tracked files
• Do not upload any data
• Do not install dependencies
• Do not require network access
• Default to DryRun for all deletion operations
• Refuse to operate on system directories (C:\Windows, /, /usr, /etc, $HOME root unless explicitly requested)
• Workspace scans require explicit user-specified root path
• Environmental suggestions only — no automatic system changes
• Never read auth tokens, credentials, or private credentials databases
• Never move, compact, export, import, or delete WSL/Docker virtual disks automatically
• Never modify .wslconfig, Docker settings, shell profiles, package manager configs, or model cache environment variables automatically

17. Audit Workflows

For Environment Audits:

1. Ask for or infer the explicit scan root folder path.
2. Run a read-only audit command first: audit_dev_environment.py for portable package/model cache mapping, or audit-dev-environment.ps1 for Windows WSL2/Docker inspection.
3. Classify paths as cache, config, runtime, model, project, or unknown.
4. Mark C-drive growth risks and potential cache size optimizations.
5. Produce a clear Markdown report with score rating (Highly controlled to Environment sprawl).
6. Include Overview Cards, Top 10 Optimization Plan, Findings, Safe Suggestions, and Manual / Risky Operations.
7. Do not perform any cleaning or migration actions unless the user confirms in a separate explicit request.

For Local Install / Self-check:

1. Use ${CLAUDE_SKILL_DIR}/scripts/install-local.ps1 -SelfCheckOnly to validate local package metadata.
2. Use install-local.ps1 in DryRun mode before copying into .codex/skills or .claude/skills.
3. Preserve display name 洁癖.skill and machine slug tidy-skill.
4. Prefer ${CLAUDE_SKILL_DIR}/scripts/tidy_doctor.py --root . after install for package + hygiene gate.

For Rule Template Install:

1. Use ${CLAUDE_SKILL_DIR}/scripts/install-rule-template.ps1 in DryRun mode first.
2. Install only user-requested templates: AGENTS, CLAUDE, cursor, or all.
3. Do not overwrite existing project rules unless the user explicitly asks for -Force.

18. Supporting References

• For script parameters and examples, read references/script-usage.md.
• For classification edge cases, read references/artifact-classification.md.
• For safety guarantees, read references/safety-boundaries.md.
• For score details, read references/hygiene-scoring-model.md.
• For WSL2 and Docker hygiene, read references/wsl2-docker-hygiene.md.
• For trigger phrases and command stubs, read commands/TRIGGERS.md.
• For read-only hooks, read hooks/HOOKS.md.
• For host install routes, see the repository docs/installation.md and docs/platforms/.
• For optional host hook samples, see repository docs/host-samples/.
• For optional project policy schema, read references/tidy-skill.policy.example.json.