A folder
of timestamps,
turned into a manifest.

You can't find a screenshot you took six months ago.

Four stages, in two minutes.

The skill does as little as possible, and validates as much as possible. Subagents handle the work that benefits from parallelism (vision); Python handles the work that benefits from being correct (filename mutation, collision detection, the actual os.rename).

Before a timestamp.
After, a sentence.

A real rename from the run that motivated this skill. The description was generated by Haiku in roughly two seconds.

The original timestamp survives unchanged. Sorting still works. The description sits between, set off by em-dashes.

Three additions, one mixed run.

A second batch of files surfaced cases the first run never hit: Apple's own Screenshot filenames, user-typed keyword prefixes, and folders where some files were already renamed. The pipeline now handles all three in a single pass — and the parser learned a new gotcha along the way.

Every rule below was paid for.

During development, four files were destroyed by a one-line bash mistake. Each rule names the failure mode that earned its place. None are aspirational.

1. Resize before vision.Retina screenshots exceed Read's image cap. Use sips -Z 1568 -s format jpeg first. The agent will fail mid-batch otherwise.
2. Frames, not videos.The vision tool can't read .mp4 or multi-page .pdf. Extract a frame with ffmpeg -ss 1 -frames:v 1 and describe that.
3. Never trust bash regex on filenames.zsh's [[ =~ ]] does not populate BASH_REMATCH. Pattern silently fails, target name is empty, multiple mvs collide. Use Python.
4. mv overwrites silently.One off-by-one in target construction destroys data with no error. Use mv -n in shell, or os.rename after an os.path.exists check in Python.
5. Plan the full rename in memory first.Build every (src, dst) tuple. Verify each dst is unique, doesn't exist, and corresponds to a real src. Then mutate disk.
6. File-count audit, every time.len(listdir(DEST)) before and after must be equal. Inequality is the only evidence of silent loss you'll get.
7. iCloud snapshots are stubs, not bytes.Files in a Time Machine local snapshot inside an iCloud-synced tree are file-provider stubs. cat them and the read times out. Real recovery comes from external backups.
8. Run renames foreground.Bash run_in_background with while read may exit early with no progress. Run via Python in the same shell — os.rename is just a syscall.
9. Validate the filename column.Haiku occasionally returns the resized .jpg name instead of the original .png. The plan-builder must try alternate extensions when the claimed source isn't found.
10. Preserve the original extension.The pipeline reads from a resized JPEG but renames the original .mp4 / .pdf. Write the source extension back into the new name.
11. Apple Screenshot files use U+202F.The narrow no-break space sits between the seconds and AM/PM. Haiku echoes it as ASCII space, the lookup misses, and every Screenshot file is dropped from the plan with a misleading NO_DESC error. Normalize on both sides; emit ASCII space in the new name.
12. Re-runs must skip already-renamed files.Without an ^App - .+ - timestamp.ext$ exclusion rule the parser will pile a second AI description into every name on every run. The pipeline detects and excludes them.
13. User-typed keyword prefix is signal.A name like jojo travel CleanShot ... carries knowledge the AI doesn't have. Strip the keyword phrase, title-case it, and prepend it to the description before assembly. Don't drop it.

What this looks like in practice.

The skill earns its keep when "Spotlight will find it" stops being true. Four scenarios where it has.

What it looks like when you ask.

The skill is conversational at the top, mechanical underneath. You ask in plain English; ten Haiku agents fan out in a single round-trip; Python validates the plan and applies it under the file-count audit. The whole thing fits on one page.

Three commands, one folder.

The skill installs as a Claude Code skill. Once cloned into ~/.claude/skills/, it activates automatically when you ask Claude to rename a screenshot folder. It can also be driven from the command line.

install# clone into your Claude Code skills directory
git clone https://gitea.tojo.team/cardinale/screenshot-rename.git \
       ~/.claude/skills/screenshot-rename

claude code> rename all the cleanshots in
  ~/Documents/Screenshots/
  based on their content.

clipython3 pipeline.py prep    --src "./shots"
# dispatch one haiku agent per batch...
python3 pipeline.py plan    --src "./shots"
python3 pipeline.py execute --src "./shots"