housekeeping
Skill1 starsChanged 24 days agoMITView on GitHub
Safe, reversible project tidy-up. Scores project health 0-100, finds loose files in the root, folders missing from CLAUDE.md, stale paths in CLAUDE.md, possible secrets, large files and git state, then proposes a plan and executes only what the user approves — every move is journaled and can be undone. Use when the user says /housekeeping, "tidy up the project", "clean up this folder", "project health", "is my CLAUDE.md up to date", "наведи порядок", "актуализация", or asks to undo the last cleanup (/housekeeping undo).
14 other projects use a version of this.
Adopted by
Most recently taken up by
- adelrodriguez/skillstheir own version, first seen Nov 15, 2026
- Mharbulous/probanda-devtheir own version, first seen Nov 8, 2026
- ARCASSystems/FounderOStheir own version, first seen Oct 24, 2026
- buttjer/n8n-decantertheir own version, first seen Oct 21, 2026
- elfrost/ai-patchlabtheir own version, first seen Oct 13, 2026
- My-Stacks/claude-code-skillstheir own version, first seen Oct 9, 2026
Other versions14 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 14
- langfuse/langfuse★ 37ksame name
- alexeykrol/claude-code-starter★ 194same name
- htlin222/dotfiles★ 78same name
- valpere/session-indexer★ 42same name
- ARCASSystems/FounderOS★ 7same name
- ImpactMojo/ImpactMojo★ 3same name
- buttjer/n8n-decanter★ 2same name
- adelrodriguez/skills★ 1same name
- bpappin/skills★ 1same name
- elfrost/ai-patchlab★ 1same name
4 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- CLAUDE.mdCLAUDE.md
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 3 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 11 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
If the user disagrees with an item, drop it — don't argue it back in.
- Very specific: line 23
Run HK journal to show sessions, then HK undo (or HK undo --session ID).
- Distinctive: line 42
If the project is a git repo: list uncommitted changes.
- Distinctive: line 50
Update CLAUDE.md so it matches the new layout (backup first).
- Very specific: line 53
If git exists, offer a commit of exactly the touched paths with a message like Housekeeping YYYY-MM-DD: ….
- Very specific: line 57
Run HK purge --dry-run, show what would be permanently deleted, and run HK purge only after the user confirms.
“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Housekeeping
A repeatable tidy-up for a project folder. Reply in the user's language; the script's report already follows the language of the project's CLAUDE.md.
The helper lives next to this file: scripts/housekeeping.py (Python 3.9+,
standard library only). Below, HK means python3 <this skill dir>/scripts/housekeeping.py --root <project root>.
Non-negotiable rules
- Plan first. Steps 1–4 only read. Nothing is moved, deleted, edited or upgraded until the user approves the plan in step 5.
- Every file operation goes through the journal (
HK move,HK trash,HK backup,HK created) — never rawrm,mv,git rm. This is what makes/housekeeping undowork. - Nothing is deleted. "Delete" means
HK trash→.housekeeping/trash/DATE/. Permanent removal is onlyHK purge, only on explicit request. - Never open, print or quote the content of files flagged as secrets. Name the file and why it was flagged; that's all.
- If the user disagrees with an item, drop it — don't argue it back in.
/housekeeping undo
Run HK journal to show sessions, then HK undo (or HK undo --session ID). If it reports conflicts, show them and ask before --force. Report what was restored. Stop here.
1. Scan
Run HK scan --write. It prints the report path (.housekeeping/reports/DATE.md) and remembers this scan so the next one shows deltas (score, size freed, CLAUDE.md size). Read the report and base the whole session on it. Show the user the score and the top problems in two or three lines.
2. Look closer (read-only)
For each finding, figure out what the right action is:
- Loose root files → which folder they belong in (by purpose, matching the structure described in CLAUDE.md). Before proposing a move,
grep -rn "<file name>"across the project (skip.git,.housekeeping, dependency folders): if something references the file by path, either move both or plan the path fix. - Folders missing from CLAUDE.md → read a few files to learn what the folder is; draft a one-line description.
- Stale CLAUDE.md paths → find where the file went (
git log --follow --name-status -- <path>if git exists, or search by name); propose fixing or removing the line. - Possible secrets → by name only. Check whether they are git-tracked (the report separates these — committed secrets are the most urgent: suggest rotating them, not just removing). Suggest
.gitignoreentries. - Large files → what produced them; propose trash or adding the folder to
media_dirsin.housekeeping.tomlif they are expected. - Duplicates → confirm with
cmp, never by name alone.
3. Optional integrations (skip silently if not installed)
- Graphify (
graphifyon PATH andgraphify-out/exists): rungraphify update .— free code-graph refresh, no LLM. If docs changed since the last full build, offer/graphify . --updateand say it costs LLM tokens. Never run the paid rebuild without consent. - PRISM (
prismon PATH):prism analyze -p <root> --json— summarize grade and real issues (its "interactive command" heuristic matches substrings and has false positives — say so instead of passing them on as problems).
4. Git
If the project is a git repo: list uncommitted changes. Don't commit other people's or other sessions' work without asking. If it is not a repo, recommend git init with a .gitignore (media, build output, .housekeeping/, secrets) — offer, don't do it unasked.
5. Plan → approval
Show one table: # · action · what · why · checked (references found / none). Put anything going to trash in its own section with sizes. Ask the user which items to do ("all", numbers, or "none").
6. Execute (approved items only)
HK begin- For each approved item:
HK move SRC DST·HK trash PATH…· before editing any fileHK backup PATH· after creating a fileHK created PATH. Fix references found in step 2 (backup those files first). - Update CLAUDE.md so it matches the new layout (backup first).
HK end— prints a JSON summary (operation counts, bytes moved to trash).HK scan --writeagain and show the before → after (score, freed space).- If git exists, offer a commit of exactly the touched paths with a message like
Housekeeping YYYY-MM-DD: …. - Tell the user: "Undo everything with
/housekeeping undo. Trash is kept N days;/housekeeping purgeempties it."
/housekeeping purge
Run HK purge --dry-run, show what would be permanently deleted, and run HK purge only after the user confirms.
Scheduling (only if asked)
The scan is read-only and safe to schedule: HK scan --write from cron / launchd / Task Scheduler (see README). Never schedule anything that moves or trashes files.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

