Skill: ivangdavila/photos (version 1.0.0)

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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)