Photo Review

Photo review

Fan-out vision review of a photo folder. Supports four modes, run any combination:

• cull: flag rejects: blurry/out-of-focus, eyes-closed, near-identical burst shots, exact duplicates, badly exposed.
• caption: short description plus searchable tags per photo (people count, scene, setting, notable objects). Good for alt-text and organising.
• organise: propose event grouping plus date/event-based filenames and a folder structure.
• best-of: pick the top N keepers from the set for sharing or printing, with one-line reasons.

This skill expects heavy fan-out. Spawning many agents is the intended design. If your setup rate-limits or costs per agent, decide your own ceiling before starting.

Procedure

1. Get the folder. If the user didn't give a path, ask. Confirm whether to recurse into subfolders.

2. Enumerate and dedupe cheaply first (saves vision tokens):

   python3 ~/.claude/skills/photo-review/list-images.py "<folder>" [--recursive]
   

   This returns per-image {path, bytes, mtime, w, h, md5} plus exact_dup_groups. Drop all-but-one of each exact-dup group before any vision work; note them in the report rather than re-reviewing.

3. Batch. Chunk the remaining images into batches of roughly 8 to 12 (vision context fills fast). Burst shots cluster by near-equal mtime: keep a burst in the same batch so one agent can compare them for near-duplicates and pick the sharpest.

4. Fan out one agent per batch (Agent tool, or Workflow with a pipeline for large sets). Each agent Reads its image paths (Read renders images visually) and returns STRUCTURED JSON for the requested mode(s). Per-image fields, as applicable:

   • path, verdict (keep | reject | maybe), reasons (blurry/eyes-closed/dup-of:/exposure/…)
   • caption, tags[]
   • suggested_name, event
   • score (0 to 100 for best-of)

5. Synthesize. Merge agent results. For best-of, rank by score across all batches and take the top N. For organise, propose the folder/rename plan as a table. Always produce a single report.

6. Apply only on confirmation. Never move, rename, or delete files until the user approves the plan. When applying: prefer copy-to-_keepers/ or rename-in-place; for deletes, move rejects to a _rejects/ folder rather than rm so it's reversible. Show counts before and after.

Notes

• HEIC reads fine via Read; if an agent can't, convert with sips -s format jpeg in.heic --out /tmp/x.jpg.
• list-images.py uses macOS sips for dimensions. On Linux, swap it for identify (ImageMagick) or Pillow; everything else is stdlib.
• Scaffolded generically: it works on any folder, and assumes no default path.
• Keep batches small and fan out wide rather than using few large agents. Parallel wins wall-clock and each agent stays within vision context.