# Tidy Skill

> Keep local AI agent environments clean, explainable, and recoverable. Use for repo artifact governance, workspace cache audits, WSL2/Docker hygiene, package and model cache mapping, C-drive growth diagnosis, and safe cleanup boundaries. Prevent throwaway Markdown files, audit local development environment sprawl, and provide read-only recommendations without moving tools, changing configs, or deleting risky files.

- Skill: `phoenix0531-sudo/tidy-skill` (Agent Skill, multi-file: 46 files)
- Install (CLI): `npx skillmds@latest add phoenix0531-sudo/tidy-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/phoenix0531-sudo/tidy-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: Phoenix0531-sudo (https://skillmd.com/u/phoenix0531-sudo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/phoenix0531-sudo/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:

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

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:

| Trigger | Examples |
|---|---|
| **Tidy / organize** | "整理项目目录", "clean up this repo", "organize my project" |
| **Generate artifacts** | "写计划", "生成报告", "create a plan/todo/summary/report/audit" |
| **Audit** | "审计项目文件", "scan for agent artifacts", "列出可疑文件" |
| **Clean up** | "清理 Agent 文件", "clean agent temp files", "删除临时文件" |
| **Decide** | "这个文件该不该生成?", "should I create this file or keep it in chat?" |
| **Score** | "给我的仓库打洁癖分", "repo hygiene score", "how clean is my repo?" |
| **Workspace audit** | "扫描工作区", "audit my workspace", "找出多个仓库的 Agent 产物" |
| **Local environment audit** | "审计我的本地环境", "inspect local agent environment", "where are my dev caches" |
| **Create rules** | "创建 AGENTS.md / CLAUDE.md / Cursor Rules" |
| **Task completion** | Wrap-up hygiene check before exiting |
| **Pollution** | "多个 Agent 乱写文件", "project root is a mess of markdown" |
| **Complaint** | "不要生成垃圾文档", "清理 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 占用太大", "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

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

| 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) | Rating (zh) |
|---|---|---|
| 90–100 | Clean | 很干净 |
| 70–89 | Mostly clean | 基本干净 |
| 50–69 | Needs tidy-up | 需要整理 |
| 0–49 | Artifact landfill | Agent 产物垃圾场 |

**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:

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`.