Folder Organizer: Read-First File Cleanup

Messy folders are hard to clean up because filenames lie. A file named final is often a draft, an invoice.html can be a login page, and three copies of report_v2.xlsx may contain three different things. Tools that sort by name put files in the wrong place and can delete the wrong one. Folder Organizer has your agent open each file first and work out what it is before deciding where it goes.

The skill runs in five phases. It profiles the folder (size hotspots, file types, biggest files, date span) and finds duplicates by content hash, not by name. It separates true byte-for-byte duplicates from version chains like draft → v2 → final. Then it pulls a content signature from every file: HTML titles, Office sheet and slide names, a PDF's first page, photo EXIF data, audio and video duration. If a file can't be read, it falls back to basic metadata instead of failing.

There's no built-in set of categories. The skill asks how you want things grouped (by project, client, date, type or topic), then proposes a structure and a file-by-file mapping for you to approve. Renaming is optional and works the same way. You lock the naming rules first, review an old → new table, and only then is anything renamed. The new names say what's actually inside each file.

It's built to be safe. Nothing is ever hard-deleted. Removals are moved to a dated staging folder that you empty yourself, and every destructive step pauses for your approval with the exact list of files. It never decides which version is "final" for you, and it flags sensitive files (IDs, contracts, bank details) that are sitting loose in a work folder.

It works on Desktop, Downloads, project drives, photo and asset libraries, and mixed folders. The bundled scripts use only the Python standard library, run on macOS, Linux and Windows, and handle filenames with spaces or CJK characters. Three tools are optional and add deeper reading: pdftotext, exiftool and ffprobe.