agentleFS
detroitwtfdetroitwtf/claude-housekeeping/skills/housekeeping/SKILL.md

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

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
  1. Distinctive:

    If the user disagrees with an item, drop it — don't argue it back in.

    line 20
  2. Very specific:

    Run HK journal to show sessions, then HK undo (or HK undo --session ID).

    line 23
  3. Distinctive:

    If the project is a git repo: list uncommitted changes.

    line 42
  4. Distinctive:

    Update CLAUDE.md so it matches the new layout (backup first).

    line 50
  5. Very specific:

    If git exists, offer a commit of exactly the touched paths with a message like Housekeeping YYYY-MM-DD: ….

    line 53
  6. Very specific:

    Run HK purge --dry-run, show what would be permanently deleted, and run HK purge only after the user confirms.

    line 57

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Plan first. Steps 1–4 only read. Nothing is moved, deleted, edited or upgraded until the user approves the plan in step 5.
  2. Every file operation goes through the journal (HK move, HK trash, HK backup, HK created) — never raw rm, mv, git rm. This is what makes /housekeeping undo work.
  3. Nothing is deleted. "Delete" means HK trash → .housekeeping/trash/DATE/. Permanent removal is only HK purge, only on explicit request.
  4. Never open, print or quote the content of files flagged as secrets. Name the file and why it was flagged; that's all.
  5. 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 .gitignore entries.
  • Large files → what produced them; propose trash or adding the folder to media_dirs in .housekeeping.toml if they are expected.
  • Duplicates → confirm with cmp, never by name alone.

3. Optional integrations (skip silently if not installed)

  • Graphify (graphify on PATH and graphify-out/ exists): run graphify update . — free code-graph refresh, no LLM. If docs changed since the last full build, offer /graphify . --update and say it costs LLM tokens. Never run the paid rebuild without consent.
  • PRISM (prism on 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)

  1. HK begin
  2. For each approved item: HK move SRC DST · HK trash PATH… · before editing any file HK backup PATH · after creating a file HK created PATH. Fix references found in step 2 (backup those files first).
  3. Update CLAUDE.md so it matches the new layout (backup first).
  4. HK end — prints a JSON summary (operation counts, bytes moved to trash).
  5. HK scan --write again and show the before → after (score, freed space).
  6. If git exists, offer a commit of exactly the touched paths with a message like Housekeeping YYYY-MM-DD: ….
  7. Tell the user: "Undo everything with /housekeeping undo. Trash is kept N days; /housekeeping purge empties 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.