photo-rename

name	photo-rename
version	1.2.0
description	Rename photos using image analysis, GPS metadata, and web research to generate descriptive real-world filenames such as "grand_canyon_phantom_ranch.jpg" or "eiffel_tower_paris.jpg". Trigger immediately when the user's message starts with "rp", or when they upload photos and ask to rename, identify, or label them by location or content. Supports batch processing.

Photo Rename Skill

Intent

Rename photo batches with consistent descriptive filenames based on EXIF data, visual content, confidence, and review-safe output.

Do Not Use When

• Do not use when the user wants irreversible file moves without review, face identification, or guesses from unclear images.
• Required context is missing and cannot be reasonably inferred.
• A more specific skill in this repo is a better match.

Constraints

• Do not fabricate missing facts, measurements, dates, sources, or user context.
• Keep output aligned with Mick's direct, practical communication style unless the skill says otherwise.
• Preserve safety, legal, medical, financial, and operational boundaries stated in this file.
• Prefer concise, usable output over broad explanation.

Validation Checklist

• The output matches the skill's intended task and platform.
• Required inputs, assumptions, and uncertainty are explicit.
• Safety, scope, and source limits are respected.
• The response follows the requested format or the skill's default output format.
• The result is practical enough to use without another cleanup pass.

Rename photos to descriptive real-world names using a combination of image analysis, EXIF metadata, reverse geocoding, and web research.

Trigger

Use this skill when the user's message starts with rp, or when they upload photos and ask to rename, identify, or label them.

Workflow

1. Extract EXIF metadata

Extract GPS coordinates and date-taken metadata from each image when available.

Useful EXIF tags include:

• GPS GPSLatitude
• GPS GPSLatitudeRef
• GPS GPSLongitude
• GPS GPSLongitudeRef
• EXIF DateTimeOriginal

If metadata extraction tooling is needed, use a lightweight EXIF reader and convert GPS rational values to decimal degrees.

Treat metadata as supporting evidence, not automatic truth. If GPS values are missing, obviously wrong, or inconsistent with the image, lower confidence and fall back to image and context based naming.

2. Identify what each photo shows

Use a combination of:

A. Image analysis

Look for:

• recognizable landmarks
• natural features
• structures
• visible signs or text
• any other identifying context

B. GPS reverse geocoding

If GPS coordinates exist, use them to get place context through a reverse-geocoding service.

C. Web research for specificity

Combine what the image shows with the GPS location to identify the most specific likely landmark, trail, attraction, or place name.

3. Batch review before naming

When multiple images are provided, review them as a set before finalizing names:

• group visually or contextually similar images
• look for shared date, place, event, or subject patterns
• keep naming consistent across the batch instead of naming each file in isolation
• use sequence suffixes only after the shared naming pattern is stable

If the user provides only one image, skip the grouping logic.

Event clustering: when timestamps and locations cluster (same day, same area), treat the cluster as one event and settle its naming pattern once. Every photo in the cluster inherits the event segment, such as road_to_hana or container_home_weld_day, and only the subject segment varies between files. This keeps a 40-photo hike from producing 40 unrelated names. Photos that fall outside every cluster are named individually.

Subject category rules: pick the subject segment by what dominates the frame:

• people: describe the activity or setting, not identities, such as summit_group_photo; never guess names from faces
• pets: use the animal plus activity, such as dog_lake_swim; use the pet's name only when the user provides it
• landscapes: lead with the named feature when known, otherwise the feature type such as ridge_view or sunset_overlook
• tools and equipment: name the tool and what it is doing, such as mig_welder_corner_joint
• project progress: name the build phase and visible state, such as solar_rack_mounting, so files sort into a build timeline

4. Generate the new filename

Rules:

• use snake_case
• prefer specific names over generic ones
• order parts consistently as date_location_event_subject when enough evidence exists
• omit any segment that cannot be supported instead of inventing it
• prefer the strongest identifying segment order available, such as location_subject or date_location_subject
• include a place type like waterfall, trail, overlook, or beach when it helps
• keep names under 50 characters when practical
• preserve the original file extension
• avoid special characters except underscores

Ordering guidance:

1. Date if capture date is reliable and useful to distinguish the set
2. Location at the most specific supportable level
3. Event when a shared trip, hike, ride, build session, or landmark stop is clear
4. Subject as the final differentiator

Examples:

• 2026_05_road_to_hana_black_sand_beach.jpg
• paris_eiffel_tower_night_view.jpg
• stewart_county_container_home_weld_frame.jpg

Fallback priority when confidence is low:

1. If GPS exists but the landmark is unclear, use the best supported place name such as stewart_county_tennessee
2. If GPS is missing or likely wrong, fall back to date plus visible subject if possible
3. If there is no reliable location data and the image cannot be identified, use unidentified_photo_01, unidentified_photo_02, and so on

Collision handling:

• if two photos would receive the same name, append _01, _02, and so on
• treat this as collision-safe rename behavior, not a failure
• keep suffix numbering stable inside a batch so follow-up cleanup is not needed

Confidence handling:

• High: subject and place are clear from multiple signals
• Medium: most likely name is strong but one part is inferred
• Low: only partial subject or place identification is possible
• None: no defensible descriptive name is available

5. Output a rename report

Produce a clear rename report rather than assuming the files can be renamed in place.

Example format:

PHOTO RENAME REPORT
===================

[PASS] IMG_4821.jpg  ->  phantom_ranch_grand_canyon.jpg
   Confidence: High | GPS: 36.1069, -112.0605 | Method: GPS + vision + web search
   Reason: Landmark and location agree clearly

[PASS] IMG_4822.jpg  ->  colorado_river_bright_angel_trail.jpg
   Confidence: High | GPS: 36.0975, -112.1129 | Method: GPS + web search
   Reason: GPS and trail context support the same destination

[WARN] IMG_4823.jpg  ->  stewart_county_tennessee.jpg
   Confidence: Low | GPS: 36.3012, -87.8456 | Method: GPS reverse geocode only
   Note: Could not identify a specific landmark

[FAIL] IMG_4824.jpg  ->  unidentified_photo_01.jpg
   Confidence: None | No GPS data | Could not identify from image alone

===================
4 photos processed | 2 high confidence | 1 fallback to GPS | 1 unidentified

For batch requests, also include:

• the old name
• the new name
• the confidence level
• the short reason for the chosen name
• any batch grouping note when similar files were named together

For large batches, open the report with a preview summary so the user reviews exceptions instead of every row:

PREVIEW: 38 photos | 2 events detected (road_to_hana: 24, kipahulu_coast: 9)
Outliers needing review: 5
  - IMG_4901.jpg: GPS contradicts the cluster (300 miles away)
  - IMG_4907.jpg: low confidence, subject unclear
  ...

Outliers are anything low or no confidence, GPS that contradicts its cluster, or a name that broke the batch pattern. The user should be able to approve the batch by checking only the outliers.

Notes

• Process all uploaded photos before producing the final report
• For well-known landmarks, use the common English name most people would recognize
• For remote or natural areas, be as specific as the available data allows
• If web results conflict, prefer the answer most consistent with the image and the location data
• If GPS looks obviously wrong, say so and do not anchor the filename to it
• When the subject is only partly identifiable, choose the most defensible generic subject instead of overclaiming specificity
• The final deliverable is the rename report unless the user explicitly asks for a script or file operation

Help And Examples

If the user is not sure how to use this skill, asks what it needs, or asks for examples:

• Explain in plain language what this skill can do.
• Tell the user the minimum input needed for a useful first pass.
• Show the example prompts below.
• Offer the fastest next prompt the user can send.

Minimum useful input:

• The photo set context and the naming pattern or outcome you want.

Example prompts:

• Use photo-rename to propose clean filenames for this folder of build progress photos.
• Help me rename these travel photos with date, place, and subject in a consistent format.
• Show me an example prompt for using this skill on a batch of mixed photos.