Cleaning up my mess: fs-audit skill

I'm often my own worst enemy when it comes to file organization.

I build a clean system. Routing tables, CONTEXT.md files, load instructions pointing at exactly the right places. And it works great, until I decide to reorganize something.

A folder gets renamed. A file moves. A whole workspace gets restructured. Life happens. The routing table doesn't update itself.

Now Claude walks into a session, follows the instructions I left, and hits a dead end. A CONTEXT.md that references a path that no longer exists. A load instruction pointing at a folder that moved two weeks ago. Files sitting on disk that nothing is looking for anymore - completely disconnected from the system. The instructions are precise. The map is just wrong.

I already had an ICM audit skill (it's great at what it does thanks to

@Yucky Yuckyyyy

's work HERE diagnosing structural problems in Claude's instruction architecture). But it wasn't built for filesystem integrity. That's a different problem. So I built one that is.

**fs-audit** walks a target directory, catalogs everything on disk, extracts every path reference from your docs, and cross-references them. Orphaned files. Orphaned folders. Dead paths cited in routers that lead nowhere. It flags everything, tells you the severity, and in fix mode it'll walk you through cleaning it up one confirmed action at a time - nothing moved, archived, or touched without your approval.

It's a small skill. Took about an hour to build. And it solves something I've been working around for months. I checked (not exhaustively) other repos, there are a metric f-ton of skills for file organization, but I couldn't locate anything specific to cleaning up the files and folders within CLAUDE desktop. Hope this helps others. Please post thoughts (especially any improvements, critiques, etc. - there's always room for improvement).

4 comments

Cleaning up my mess: fs-audit skill