{"skill":{"slug":"photos","displayName":"Photos","summary":"Organize, index, and search local photo libraries with AI-powered metadata and safe file handling.","description":"---\nname: Photos\ndescription: Organize, index, and search local photo libraries with AI-powered metadata and safe file handling.\nmetadata: {\"clawdbot\":{\"emoji\":\"🖼️\",\"requires\":{\"bins\":[\"exiftool\"]},\"os\":[\"linux\",\"darwin\",\"win32\"]}}\n---\n\n## Safety First\n\n- **Never delete photos directly** — move to `.photo-trash/` folder with original path preserved in filename\n- **Never overwrite originals** — edits go to `edited/` subfolder, originals stay untouched\n- Before bulk operations, create manifest: `photos-pending.json` with planned actions for user review\n- When user says \"delete duplicates\", move to trash and report count — let them empty trash manually\n\n## Indexing Strategy\n\n- Create `.photo-index/` in library root with one JSON sidecar per photo\n- Sidecar filename: `{original-hash}.json` — survives renames and moves\n- Index fields: `hash`, `path`, `date_taken`, `camera`, `gps`, `description`, `tags`, `indexed_at`\n- Run indexing incrementally — skip files with matching hash already indexed\n- Store description from vision analysis in sidecar, not in EXIF (non-destructive)\n\n## Vision Analysis (Token-Efficient)\n\n- Don't analyze every photo upfront — index on-demand when user searches or asks\n- Cache vision results permanently in sidecar JSON — never re-analyze same photo\n- For bulk analysis, process in batches of 20 with progress updates\n- Use concise prompts: \"Describe this photo in 2-3 sentences. List people, objects, location, activity.\"\n- Skip screenshots and memes (detect by aspect ratio + lack of EXIF) unless explicitly requested\n\n## Duplicate Detection\n\n- Generate perceptual hash (pHash) alongside content hash — catches near-duplicates and resized copies\n- Group duplicates by pHash similarity, keep highest resolution as \"original\"\n- Report duplicates with thumbnails/paths, never auto-delete\n- Consider EXIF date — oldest is likely the original, newer copies are backups\n\n## Search Patterns\n\n- **By content**: Search sidecar descriptions with simple text match first, vision re-analysis if no hits\n- **By date**: Parse EXIF DateTimeOriginal, fall back to file mtime\n- **By location**: Reverse geocode GPS once, store city/country in sidecar for text search\n- **By person**: If user identifies someone once (\"that's Maria\"), tag all similar faces in index\n\n## EXIF Handling\n\n- Read: `exiftool -json photo.jpg` — returns all metadata as JSON\n- Write date: `exiftool -DateTimeOriginal=\"2024:03:15 14:30:00\" photo.jpg`\n- Strip GPS before sharing: `exiftool -gps:all= photo.jpg` (operates on copy, not original)\n- Batch read: `exiftool -json -r /photos/` — recursive, outputs array\n\n## File Organization\n\n- Propose structure, don't impose: `YYYY/MM/` or `YYYY/MM-DD/` based on user preference\n- Rename pattern: `YYYYMMDD_HHMMSS_originalname.ext` — preserves original name, adds sortable prefix\n- Handle timezone: EXIF dates are local time — ask user's timezone once, store in `.photo-index/config.json`\n- HEIC to JPEG: `sips -s format jpeg input.heic --out output.jpg` (macOS) or `heif-convert` (Linux)\n\n## NAS/Remote Libraries\n\n- For Synology/NAS: work with mounted paths, don't assume local speeds\n- Test connection before bulk operations: `ls /Volumes/photos | head -1`\n- For slow connections, build local index cache that syncs periodically\n- Respect `@eaDir` (Synology thumbnails) and `.DS_Store` — skip in indexing\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":1744,"installsAllTime":66,"installsCurrent":6,"stars":2,"versions":1},"createdAt":1770808973307,"updatedAt":1778487899210},"latestVersion":{"version":"1.0.0","createdAt":1770808973307,"changelog":"Initial release","license":null},"metadata":{"setup":[],"os":["linux","darwin","win32"],"systems":null},"owner":{"handle":"ivangdavila","userId":"s178jdk12x4qj3gs2se3etxf3h83h7ft","displayName":"Iván","image":"https://avatars.githubusercontent.com/u/81719670?v=4"},"moderation":null}