Initial commit: skill files, docs site, README

- SKILL.md and pipeline.py from ~/.claude/skills/screenshot-rename/ - docs/index.html — archival/typewriter aesthetic homepage with hero monument, problem, 4-stage pipeline, before/after split, run-log receipt, ten gotchas, four use cases, install snippets - MIT license Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-04 09:23:02 -04:00
commit 63edc33fc4
6 changed files with 1547 additions and 0 deletions
@@ -0,0 +1,87 @@
+# screenshot-rename
+
+> A Claude Code skill that turns a folder of timestamp-named screenshots into a folder of human-readable, searchable filenames — using parallel Haiku vision agents.
+
+```
+CleanShot 2026-04-15 at 09.14.07.png
+   ↓
+CleanShot - Shamel Studio Affiliate Referral Code Modal - 2026-04-15 at 09.14.07.png
+```
+
+Built for [CleanShot](https://cleanshot.com)-style screenshot folders, but works on any directory of `.png` / `.gif` / `.mp4` / `.pdf` files named only by timestamp.
+
+## Highlights
+
+- **Parallel** — describes ~200 files in 3 minutes using 10 concurrent Haiku subagents.
+- **Safe** — pre-builds the full rename plan in memory, validates uniqueness and target collisions, then renames atomically with file-count audit. Designed after losing 4 files to a `mv` overwrite during prototyping.
+- **Handles video/PDF** — extracts the first frame so vision agents can describe them.
+- **Resizes for the vision tool** — Retina screenshots exceed Read's image cap; pipeline downsamples to 1568px max.
+
+## Installation
+
+This is a Claude Code skill. Drop the `screenshot-rename/` directory into `~/.claude/skills/`:
+
+```bash
+git clone https://gitea.tojo.team/cardinale/screenshot-rename.git ~/.claude/skills/screenshot-rename
+```
+
+In your next Claude Code session, ask:
+
+> rename all the cleanshot files in `~/Documents/Screenshots/` based on their content
+
+The skill will activate automatically.
+
+## Usage from the command line
+
+You can also drive the pipeline directly:
+
+```bash
+# 1. Prep — extract frames, resize, build batches
+python3 pipeline.py prep --src "/path/to/folder" --batch-size 19
+
+# 2. (In a Claude Code session, dispatch one Haiku subagent per
+#     /tmp/screenshot-rename/full-batch-NN file using the prompt template
+#     in SKILL.md.)
+
+# 3. Plan — aggregate descriptions, validate, build rename map
+python3 pipeline.py plan --src "/path/to/folder"
+
+# 4. Execute — apply the plan, audit file count
+python3 pipeline.py execute --src "/path/to/folder"
+```
+
+The dispatch step (#2) currently requires a Claude Code session. See [Roadmap](#roadmap).
+
+## Documentation
+
+- **Homepage with worked examples:** [docs/index.html](docs/index.html)
+- **Full skill spec:** [SKILL.md](SKILL.md)
+- **Pipeline source:** [pipeline.py](pipeline.py)
+
+## The gotchas this skill encodes
+
+This skill exists because every one of these caused real damage during development:
+
+1. The macOS `Read` tool has an image-size cap. Resize first.
+2. Vision can't read `.mp4` or multi-page `.pdf` directly. Extract a frame.
+3. **Bash regex `[[ =~ ]]` does NOT populate `BASH_REMATCH` in zsh.** Targets become empty. Loops collide on the same filename. Files vanish. Use Python for any filename mutation.
+4. `mv` silently overwrites. Use `mv -n` or `os.rename` with explicit pre-existence check.
+5. Pre-build the entire rename plan in memory and validate uniqueness before any `mv`.
+6. Audit `len(os.listdir(DEST))` before and after. Equal count == proof no overwrites.
+7. iCloud-synced files in Time Machine local snapshots are file-provider stubs, not bytes. External backups (Backblaze, Time Machine to physical disk) are the real recovery source.
+8. `Bash run_in_background` may exit early on `while read` loops. Run renames foreground via Python.
+9. Haiku occasionally returns the resized `.jpg` filename instead of the original `.png`. Validator must try alt extensions.
+10. Always preserve the original `.mp4` / `.pdf` extension — describe via the extracted frame, rename the source.
+
+The full discussion is in [SKILL.md](SKILL.md#the-critical-gotchas-every-one-of-these-caused-real-pain).
+
+## Roadmap
+
+- Direct Anthropic API mode (no Claude Code session required) — needs `ANTHROPIC_API_KEY`
+- Custom prompt templates per-folder
+- Optional preservation of dots in technical strings (`v2.1` currently becomes `V21`)
+- Dry-run flag on `execute`
+
+## License
+
+MIT — see [LICENSE](LICENSE).