Tidy Skill

Before and After

Without hygiene governance

Agent drops plan.md, todo.md, final_report.md into the repo root. Next session re-reads the repo, asks you to restate the goal. Sees a large .venv or node_modules and tries to delete it.

With Tidy Skill

Plans stay in chat; reports go to .agent_reports/; temp files go to .agent_tmp/. Audits list paths, sizes, risks, and safe suggestions — no auto-deletion. Cleanup defaults to DryRun; migration, compaction, and config edits are suggestions only.

Four Failure Modes

Tidy-skill is built around the mess agents actually leave, not a giant methodology pack.

Three-Layer Hygiene Model

Safety Verbs

Three short verbs, always the same meaning:

Doctor diagnoses; repair is the next step — still DryRun-first:

uv run python skills/tidy-skill/scripts/tidy_doctor.py --root .
uv run python skills/tidy-skill/scripts/tidy_repair.py --root .          # plan
uv run python skills/tidy-skill/scripts/tidy_repair.py --root . --apply # safe layout dirs

Quickstart

git clone https://github.com/Phoenix0531-sudo/tidy-skill.git
cd tidy-skill
uv sync --extra dev

# Score this repo's hygiene
uv run python skills/tidy-skill/scripts/score_repo_hygiene.py --root . --json
# {"score": 100, "rating": "Clean", ...}

# One-shot doctor (package + hygiene gate)
uv run python skills/tidy-skill/scripts/tidy_doctor.py --root . --json

# DryRun repair plan (create layout dirs / move root litter — apply separately)
uv run python skills/tidy-skill/scripts/tidy_repair.py --root . --json

# Classify a path before writing (Classes A–E)
uv run python skills/tidy-skill/scripts/classify_artifact.py plan.md --root . --json

# Classify many candidate paths at once from stdin (one path per line; emits one NDJSON line per path)
printf 'plan.md\n.agent_tmp/notes.md\ndocs/index.md\n' \
  | uv run python skills/tidy-skill/scripts/classify_artifact.py --stdin --json --root .

# Audit agent artifacts
uv run python skills/tidy-skill/scripts/audit_agent_artifacts.py --root . --json

# Audit local dev environment (read-only)
uv run python skills/tidy-skill/scripts/audit_dev_environment.py --root . --json

# Windows deep audit (WSL2/Docker/VHDX)
pwsh skills/tidy-skill/scripts/audit-dev-environment.ps1 -Roots .

# Cleanup preview (DryRun, deletes nothing)
pwsh skills/tidy-skill/scripts/clean-agent-artifacts.ps1 -Root . -DryRun

# Tests
uv run pytest tests/
uv run ruff check . --select E9,F63,F7,F82

Install Matrix

Two install philosophies (pick one per machine):

Skills CLI (verified discoverable): standard skills/tidy-skill/SKILL.md package. Author-verified for codex / claude-code / cursor / pi:

npx skills add Phoenix0531-sudo/tidy-skill --list
# Found 1 skill: tidy-skill

npx skills add Phoenix0531-sudo/tidy-skill --skill tidy-skill -a claude-code -y --copy

Full matrix, silent failure modes, doctor/repair, uninstall: docs/installation.md · verification log: docs/skills-cli-verify.md.

Per-platform notes: Claude · Codex · Cursor · Pi · OpenCode.

Optional host hook samples (not auto-wired): docs/host-samples/.

Local copy into agent hubs (preview first):

pwsh skills/tidy-skill/scripts/install-local.ps1
# Codex + Claude by default; add -Cursor -Pi -OpenCode or -All
pwsh skills/tidy-skill/scripts/install-local.ps1 -All -DryRun:$false -Force

Marketplace plugin listings (Claude/Codex official stores) are not claimed.

Self-Audit

This repository runs its own scripts against itself. Latest author-run reports:

Regenerate:

uv run python skills/tidy-skill/scripts/score_repo_hygiene.py --root . --report-path docs/self-audit/repo_hygiene_score.md
uv run python skills/tidy-skill/scripts/audit_agent_artifacts.py --root . --max-depth 3 --report-path docs/self-audit/agent_artifacts_audit.md
uv run python skills/tidy-skill/scripts/audit_dev_environment.py --root . --report-path docs/self-audit/dev_environment_audit.md
uv run python skills/tidy-skill/scripts/tidy_doctor.py --root . --report-path docs/self-audit/tidy_doctor.md
uv run python tools/run_evals.py

Methodology note. Self-audit and fixture evals use this repository's own scripts. Internal v1, author-run; not an independent third-party benchmark.

Artifact Classification

Five-level placement model (see SKILL.md):

Commands

Python scripts are pure stdlib (no network, no third-party runtime deps). Cleanup and install scripts default to DryRun. Trigger phrases and command stubs: skills/tidy-skill/commands/.

Scope

In scope

• Read-only audits of agent artifacts, repo hygiene, workspace repos, and local cache footprints
• Optional project policy (.tidy-skill.json), doctor, repair, pre-write classifier, and score history/gate
• DryRun cleanup previews for .agent_tmp/ / .agent_reports/ (retention: tmp 7d / reports 30d by default)
• Optional read-only stop hooks and pre-commit root-process-md guard
• Rule templates so multiple agents share the same placement policy
• Offline, local-only operation

Out of scope

• Automatic deletion of formal docs, source, or Git-tracked files
• Automatic WSL distro migration, VHDX compaction, or Docker data moves
• Token / credential / database / private log reads
• Full-disk scans without an explicit root
• Network calls or uploads

FAQ

No. clean-agent-artifacts.ps1 defaults to DryRun and only previews candidates under agent temp/report directories. Actual deletion requires explicit confirmation flags. Audits never delete. tidy_repair.py defaults to a plan only; --apply creates layout dirs; root process moves need both --apply and --move-root, and still refuse git-tracked / protected files.

Product safety verbs: dryrun = preview only; careful = agent working files only (e.g. move untracked root process Markdown into .agent_tmp/); guard = hard refuse host configs, VHDX, Docker data, git-tracked files, Class A docs. See Safety Verbs.

Python covers portable, dependency-free repo and baseline environment checks on any platform. PowerShell adds Windows-depth visibility into WSL2, Docker Desktop VHDX, and user-profile caches that pure Python cannot safely introspect the same way.

Do not use it as a general disk cleaner, security scanner, or replacement for backup tools. It will not auto-fix a full C: drive, compact VHDX files, or rewrite agent configs. If you need those operations, follow the vendor docs and treat this skill's output as suggestions only.

They solve different problems. PWF keeps long tasks alive on disk; tidy-skill keeps the repo and machine clean. Prefer PWF under .planning/ (always recognized as intentional working memory), or opt the root triple in with planning_root_globs — see docs/comparison.md and references/tidy-skill.policy.pwf.example.json.

Layout

tidy-skill/
├─ skills/tidy-skill/
│  ├─ SKILL.md                 # skill definition (three-layer model, classes A–E)
│  ├─ scripts/                 # Python + PowerShell tools
│  ├─ hooks/                   # read-only stop check
│  ├─ commands/                # trigger phrases + command stubs
│  ├─ templates/               # AGENTS.md / CLAUDE.md / cursor-rule
│  ├─ references/              # deeper usage notes
│  └─ examples/
├─ tools/                      # validate_skill, run_evals, pre-commit helper
├─ evals/                      # fixture eval notes
├─ tests/                      # pytest + PowerShell safety tests
├─ docs/
│  ├─ installation.md          # install matrix + doctor
│  ├─ platforms/               # Claude / Codex / Cursor / Pi / OpenCode
│  ├─ host-samples/            # optional hook JSON samples
│  ├─ cases/                   # before/after case studies
│  ├─ screenshots/             # banner + terminal preview
│  ├─ self-audit/              # author-run reports
│  └─ evals/                   # latest fixture eval report
├─ .github/workflows/          # ci.yml + validate.yml
├─ pyproject.toml
└─ README.md / README.zh-CN.md

License

MIT. See LICENSE.