file-tidy

---
name: file-tidy
description: Renames and files every document in a folder to one date-first convention, writing a dry run first and an undo log after, so nothing is ever lost. Use on a messy Downloads, Documents or scans folder.
---

# Every document on your machine named and filed so you can find it

You point it at one folder. It gives you a plan to read, then a tidy folder tree, a log of every move, and a one-command undo.

Run it from the folder above the mess:

```
codex exec -C "the folder" - < the-prompt.md
```

## What it does

1. **Take one folder and refuse to go above it:** the owner names an exact folder. Refuse to run on a drive root, the Windows or Program Files folder, or the whole user profile, because a rename sweep at that level catches application settings and licence files that break when moved. Skip any subfolder containing `.git`, `node_modules`, `AppData`, or a file called `package.json`, and say in the report which folders were skipped and why.

2. **Write the inventory before forming any opinion:** walk the folder once and record, for every file, the full path, size in bytes, last modified date, extension and an MD5 hash, into `tidy-inventory.csv`. Every later step reads that file, never a fresh directory walk, so the plan cannot drift underneath itself while the run is in progress.

3. **Work out what each file is from its contents, not its name:** open PDFs and text files and read the first page, read the embedded document properties, and note the folder it currently sits in. A file called `scan001.pdf` that opens with a letterhead and a total is an invoice. Where the document carries its own date inside it, that date wins over the file system date, which is rewritten every time a file is copied to a new machine or a USB stick.

4. **Name every file to one pattern:** `YYYY-MM-DD_who_what_v01.ext`. Date first in ISO 8601 form, because it is the only date format where sorting the folder alphabetically also sorts it in time order, and because it removes the ambiguity between British day-month and American month-day. Harvard Medical School's data management guidance sets the rest of the shape: keep the whole name to 40 to 50 characters, use only letters, numbers, dashes and underscores, and use no spaces, because many systems still cannot handle them.

5. **Use leading zeros and a version suffix, never a word:** sequence numbers run `01, 02 ... 10`, not `1, 2 ... 10`, so they sort correctly. Versions run `_v01`, `_v02`. Never use `final`, `final2` or `latest` in a filename, as the newest version stops being obvious the moment a second one exists.

6. **Build a shallow tree, at most three levels:** `Year / Category / Party`. Derive the categories from what is actually in the folder and cap the list at twelve, because a person cannot hold more than that in their head when filing the next document. The National Archives' guidance for voluntary sector record keeping is the test to apply: name folders so they retain the context of who created the content, and avoid long and complex folder and file names.

7. **Treat identical hashes as duplicates and move them, never delete them:** two files with the same MD5 are byte for byte identical. Keep the copy in the most sensible location, move the rest to a folder called `_duplicates` inside the target folder, and list every set in the report with all its paths, sizes and dates so the owner can empty that folder themselves later.

8. **Dry run, and stop:** write `tidy-plan.csv` with four columns, current path, proposed path, the reason, and a confidence of high, medium or low. Print the counts by category and by confidence. Move nothing. The owner reads the plan and says go. Anything marked low confidence, or that the run could not identify at all, is proposed for a `_review` folder with its original name untouched.

9. **Execute one move at a time and log it as you go:** after each successful move, append the old path and the new path to `tidy-undo.csv`, then write the reverse commands to `undo-tidy.sh`. Never overwrite: if the target path already exists and the hashes differ, append `_02` to the name and record the collision. If any single move fails, stop the run, report how many moves had completed, and leave the undo log complete up to that point.

## Then it checks

1. Every file in `tidy-inventory.csv` appears exactly once in one of three places: moved, skipped, or sent to `_review`. A file present in none of them, or in two, stops the run.
2. Nothing was deleted. The count of files and the total bytes under the folder after the run match the inventory, ignoring the four files this skill created itself.
3. Every new filename matches the pattern, is 50 characters or fewer, and contains only letters, numbers, dashes, underscores and a single full stop before the extension.
4. No two files were moved to the same path, and no existing file was overwritten. The number of recorded collisions matches the number of `_02` suffixes on disk.
5. Pick three moves at random from `tidy-undo.csv` and confirm the new path exists and the old path is now free, so the undo would actually replay.
6. Every unreadable or low confidence file is sitting in `_review` under its original name, and is listed in the report with the reason it could not be identified.

Any check fails: name it, redo that step once. Failed twice: say what is wrong and stop.

## Rules
- Public information only.
- Never invent a fact, a number or a quote.
- Never delete a file, never empty a recycle bin, never overwrite an existing file. Duplicates and unknowns are moved, never removed.
- Nothing moves until the dry run plan has been read and approved by the owner. A plan is not permission.
- Never rename a file whose contents could not be read. Guessing from a filename is how a bank statement becomes a holiday photo.
- If the folder holds business records, say so in the report and leave them in place: in the UK, records kept for VAT purposes must generally be kept for at least six years, so a tidy-up is a filing job, not a clear-out.

## Built from
- ComposioHQ/awesome-claude-skills, https://github.com/ComposioHQ/awesome-claude-skills, 74,627 stars read from api.github.com on 7 September 2026: its File Organizer entry and skill file. Took the propose-a-full-plan-before-touching-anything step, its rule to log all moves for a potential undo, and its instruction to handle filename conflicts gracefully rather than overwriting.
- openai/plugins, https://github.com/openai/plugins, 5,467 stars read from api.github.com on 7 September 2026: a curated collection of Codex plugin examples, with 64 entries listed in `.agents/plugins/marketplace.json`. Took the shape of a self-contained job that runs locally on the owner's own machine in one pass, with one manifest per job.
- Harvard Medical School Longwood Research Data Management, file naming conventions, https://datamanagement.hms.harvard.edu/plan-design/file-naming-conventions: the exact naming rules in steps 4 and 5. Its wording is that a good format for date designations is YYYYMMDD, that file names should be 40 to 50 characters using only alphanumeric characters, dashes and underscores, that many computer systems cannot handle spaces in file names, and that sequential numbering should use leading zeros.
- The National Archives, digital record keeping in the voluntary sector, management and storage, https://www.nationalarchives.gov.uk/archives-sector/advice-and-guidance/resources-by-archive-type/charity-archives-development-plan/outputs/digital-record-keeping-in-the-voluntary-sector/management-and-storage/: the folder depth rule in step 6, from its guidance to name folders to retain context in terms of who created the content, and to try and avoid long and complex folder and file names.