Photo Homecoming

Inspiration

The first thing most people do with a new NAS is move their photos out of the cloud. For Google Photos that means Google Takeout, and Takeout breaks the library on the way out:

• every file carries the export date, while the real capture date sits in a separate JSON sidecar
• each photo appears in its year folder and again in every album folder it belonged to
• albums arrive as plain folders

Open-source scripts can fix part of this, but they need a PC and a command line. We wanted the NAS to finish the move itself, by conversation.

What it does

Photo Homecoming is an Uliya Skill. The user says "I moved my Google Photos export to the NAS. Fix it." and the Skill:

1. surveys the export folder (year libraries, album folders, archive parts that are still not extracted)
2. matches every photo and video to its sidecar and reads the real capture date
3. checks which files already carry a correct embedded date and leaves them alone
4. groups identical files by hash and remembers which albums each photo belonged to
5. shows one plan with exact counts and changes nothing until the user approves it, all or in part
6. restores capture dates, moves duplicate copies to a review folder (nothing is deleted), rebuilds the original albums inside the NAS photo library, and saves a move-in report

How we built it

• A single SKILL.md that only delegates to the NAS's registered experts: file-agent (survey, sidecars, duplicate scan, date restore, batch move), photo-agent (embedded dates, albums) and knowledge-agent (report).
• Steps 1-4 are read-only, step 5 waits for the user, and steps 6-9 change data only through the platform approval flow, inside the export folder.
• The Takeout matching rules (truncated sidecar names, moved (1) counters, edited copies, which JSON fields to trust) live in a linked reference file.
• Validated with the UGOS Skill Creation Tool checker: zero errors, zero warnings.

Challenges we ran into

• Takeout has no published specification. Sidecar names are cut at different lengths (.supplemental-metadata.json, .supplemental-me.json, even ..json), and the (1) counter of a renamed photo moves to the end of the sidecar name. We wrote matching rules that refuse to guess when more than one sidecar could fit.
• creationTime in the sidecar is the upload time, not the capture time. Only photoTakenTime is used.
• Deleting duplicates is risky, so duplicates are set aside and the album membership is recorded first, so albums can be rebuilt from the copies that stay.

Accomplishments that we're proud of

• A full move-in flow with one approval gate and a clear "what will not happen" list.
• Nothing is ever deleted, and every file that could not be fixed is listed with the reason.

What we learned

The hard part of a migration is not the AI. It is reading the export the way it was written and being honest about what could not be fixed.

What's next for Photo Homecoming

• Validate on a real UGREEN AI NAS: approval flow for date restores, timeline display, album creation from existing files.
• Apple iCloud Photos export support.
• A follow-up check a week later: new files dropped into the export folder get the same treatment.

Disclosures

No third-party code, libraries or data are included; the package is Markdown only. Takeout naming patterns were learned from public community reports (GooglePhotosTakeoutHelper issues, ExifTool forum). Claude Code (Anthropic, Claude Opus 5.5) was used to research, propose candidate ideas (the entrant chose this one), suggest the name, and write the Skill, references and proposal text.

Built With

• claude
• google-photos
• google-takeout
• markdown
• ugos
• ugreen-ai-nas
• uliya