Photos

Organize, index, and search local photo libraries with AI-powered metadata and safe file handling.

Security Scan

The skill's stated purpose (local photo indexing using exiftool) is coherent, but the runtime instructions leave key behaviours (vision analysis, reverse geocoding, and face-tagging) underspecified and potentially privacy-sensitive—allowing the agent to send images or GPS/person data to external services without declared constraints or credentials.

Purpose & Capability

The declared requirement (exiftool) matches the stated purpose of reading/writing EXIF and indexing photos. The SKILL.md also references additional tools (sips, heif-convert) and perceptual hashing/pHash operations that are reasonable for the domain but are not listed as required binaries; this is a minor inconsistency but explainable.

Instruction Scope

Instructions direct broad file-system access (recursive EXIF reads, creating .photo-index and .photo-trash) which is expected for a photo indexer. However, the guidance on 'vision analysis' and 'reverse geocode GPS once' is vague about where analysis or geocoding runs—there's no specification whether image pixels or GPS coordinates stay local or are sent to third-party APIs. The face-tagging rule (‘tag all similar faces if user identifies someone’) explicitly enables biometric processing. These open-ended directions give the agent significant discretion to transmit sensitive data (images, faces, locations) externally.

Install Mechanism

No install spec and no code files — instruction-only — so nothing is written or fetched at install time. That minimizes installer risk.

Credentials

The skill requests no environment variables or credentials, which keeps the declared footprint small. But the instructions imply uses (reverse geocoding, vision APIs, possible face-recognition services) that commonly require API keys. The omission of required credentials means the agent may either (a) perform services locally, (b) call unauthenticated public endpoints, or (c) prompt the user or use other agent-configured credentials. This mismatch is important to surface before use.

Persistence & Privilege

The skill does not request permanent or system-wide privileges (always:false). It creates its own per-library directories (.photo-index, .photo-trash, edited/) which is reasonable and expected for this functionality. It does not modify other skills or global agent config in the instructions.

What to consider before installing

Before installing, consider the following: - Backup: Back up a sample of your photo library before running any bulk operations. - Local vs remote analysis: Ask the skill author (or confirm in your agent configuration) whether 'vision analysis' and reverse geocoding run entirely locally. If the agent will send images or GPS coordinates to external APIs, you may expose sensitive location/person data. - Face recognition: The SKILL.md calls for automatically tagging faces once a user identifies someone. This is biometric processing with privacy and legal implications; disable or require explicit consent per-person if you are uncomfortable. - API keys: The skill lists no required credentials, but reverse geocoding and cloud vision usually need API keys. Decide which geocoding/vision providers to use and provide your own credentials if you want control over where data goes. - Tools: Ensure exiftool is installed. If you need HEIC conversion, install sips (macOS) or heif-convert (Linux) as needed; the skill mentions these but does not require them explicitly. - Data handling: The skill's safety rules (never overwrite originals, move deletes to .photo-trash, keep sidecars) are good. Confirm the exact path the skill will use for .photo-index/.photo-trash and whether it will index network mounts. - Least privilege: If possible, run the skill on a test folder first and restrict it to only the directory you want indexed rather than your whole photos root. If you need help deciding, ask the skill author how they perform vision/geocode operations (local model vs which cloud provider) and whether they will ever transmit raw image data or GPS coordinates to third parties. If they cannot provide a clear answer, treat the skill as privacy-sensitive and avoid granting it broad access to your entire photo library.

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