agentleFS
jablonkaijablonkai/skills/skills/apple-photos/SKILL.md

apple-photos

Skill2 starsChanged 45 days agoMITView on GitHub

Query, export and organise the Apple Photos library on macOS: osxphotos for read-only searches by date, year, place, GPS area, people, keywords and albums, per-year statistics, and exports of originals or edited versions with XMP/JSON sidecars as resumable --update runs; Photos'' AppleScript for creating albums from a query and importing files. Read-only and local by default. Use for "export all photos from our Lisbon trip in May 2023 with XMP sidecars", "make an album of everything tagged hiking", "how many photos did I take each year", "which people appear most in my library", "import this folder into Photos into an album", "back up my Photos originals by year", or Hungarian "exportáld a nyaralás képeit a Fotókból". Not for editing pixels or retouching (use gimp or krita), Lightroom or other catalogs, converting or resizing image files outside Photos, video transcoding (use handbrake), iCloud web or shared albums, or bulk metadata rewrites unless the user explicitly asks.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read-only by default: Write to the library only when the user asks for an album or an import.

    line 33
  2. Very specific:

    Never run osxphotos timewarp, batch-edit, push-exif, add-locations, sync or import unless the user names that operation.

    line 35
  3. Distinctive:

    Stay local: Don't upload photos or send library contents (names, people, places, thumbnails) to any web service.

    line 37
  4. Very specific:

    Query and count before acting: Run osxphotos query … --count, then spot-check with --print "{original_name} {created} {place.name}".

    line 62
  5. Very specific:

    Every script takes --library PATH.

    line 104

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Apple Photos via osxphotos and AppleScript

Two surfaces, split by direction:

  • Reads go through osxphotos (MIT, Python CLI). It reads a snapshot of the library's SQLite database, so Photos doesn't need to run, and it never writes to the library during query, export, info, albums, keywords, persons or places.
  • Writes go through Photos' AppleScript dictionary (JXA): creating albums, adding items, importing files. AppleScript always acts on the library Photos has open, so the write helpers check which library that is before they change anything.

Verified against Photos 12.0 on macOS 27.0.1 with osxphotos 0.77.2.

Privacy rules (read first)

The library is personal data: faces, names, places, private photos.

  • Read-only by default. Write to the library only when the user asks for an album or an import. Never delete, and never edit dates, titles, keywords or locations. Never run osxphotos timewarp, batch-edit, push-exif, add-locations, sync or import unless the user names that operation.
  • Stay local. Don't upload photos or send library contents (names, people, places, thumbnails) to any web service.
  • Report aggregates (counts, years, album sizes). List individual names, people or locations only when the user asked for them.
  • Exports write only into the folder the user names. Don't use --cleanup: it deletes files in the destination.

Setup

S=scripts   # paths are relative to this skill's directory
bash $S/photos.sh --check     # osxphotos path/version, Photos version, readable?, open library, automation
  • osxphotos missing (exit 2): uv tool install --python 3.13 osxphotos. It needs Python 3.10–3.14, and the macOS system Python is 3.9, which is why uv is used.
  • Default library "NOT readable": the terminal or IDE that runs the agent needs Full Disk Access (System Settings › Privacy & Security). Restart it after granting. Libraries outside ~/Pictures are usually readable without it.
  • Automation denied (error -1743): allow the terminal to control Photos under Privacy & Security › Automation. macOS asks for this on the first write.
  • Another library: pass --library PATH to every read. osxphotos list finds libraries.

Workflow

  1. Query and count before acting. Run osxphotos query … --count, then spot-check with --print "{original_name} {created} {place.name}". Tell the user the number before a large export or an album write.
  2. Export with osxphotos export, or write with ph-album.py / ph-import.py.
  3. Verify by read-back: ph-verify-export.py for exports, and the JSON summaries of the album and import helpers. They re-read Photos after writing.
The user saysDo
"photos from 10–17 May 2023"--from-date 2023-05-10 --to-date 2023-05-18. --to-date is exclusive, so add a day for an inclusive end
"taken in Lisbon"--place Lisbon only works after Photos has geocoded the items (it can be empty on new imports). Reliable: a GPS box, --query-eval 'photo.location[0] is not None and abs(photo.location[0]-38.72)<0.3 and abs(photo.location[1]+9.14)<0.3' (≈30 km). Try --place, and fall back to the box if the count is 0 or too small
"tagged hiking"--keyword hiking -i. Without -i, matching is case-sensitive and misses Hiking. It's always an exact keyword match, so hiking-boots is excluded either way
"with Anna" / "in album X"--person "Anna" / --album "X". Repeating the same flag ORs its values; different flags AND together
"originals" / "edited versions" / "both"--skip-edited / --skip-original-if-edited / the default (it exports the original plus NAME_edited.ext for edited items)
"with XMP sidecars"--sidecar XMP writes NAME.jpg.xmp. Add --sidecar-drop-ext for NAME.xmp (what Lightroom and darktable expect)
"by year/month folders"--directory "{created.year}/{created.mm}"
"incremental backup"--update (re-runs export only new or changed items, tracked in DEST/.osxphotos_export.db)
"photos only" / "videos only"--only-photos / --only-movies

Recipes

# Trip export: originals + XMP sidecars, resumable, then verify
mkdir -p "$DEST"     # export fails if DEST does not exist
Q=(--from-date 2023-05-10 --to-date 2023-05-18 --query-eval 'photo.location[0] is not None and abs(photo.location[0]-38.72)<0.3 and abs(photo.location[1]+9.14)<0.3')
osxphotos query "${Q[@]}" --count
osxphotos export "$DEST" "${Q[@]}" --skip-edited --sidecar XMP --update
python3 $S/ph-verify-export.py "$DEST" --sidecar xmp -- "${Q[@]}"

# Album from a query: reuses an existing album, adds only what's missing
python3 $S/ph-album.py --name "Hiking" --dry-run -- --keyword hiking -i
python3 $S/ph-album.py --name "Hiking" -- --keyword hiking -i

# Statistics per year (or --by month), read-only
python3 $S/ph-stats.py                       # photos, videos, favourites, edited, located, hidden, iCloud-only
python3 $S/ph-stats.py -- --person "Anna"    # narrowed by any query args

# Import a folder into an album; already-imported files are skipped
python3 $S/ph-import.py ~/Scans --album "Scans" --dry-run
python3 $S/ph-import.py ~/Scans --album "Scans"

Every script takes --library PATH. With the album and import helpers it must match the library Photos has open, or they exit 3. The query goes after -- and uses osxphotos query syntax.

  • references/osxphotos-cli.md: query, export and template flags, the query --json fields, and the read-only subcommands.
  • references/applescript.md: the Photos dictionary, JXA snippets, ids, folders, and errors.
  • references/recipes.md: more worked jobs, including people, top-N reports, Live Photos and RAW, iCloud-only originals, and folder layouts.
  • references/gotchas.md: read before writing raw commands.

Stopping and resuming

  • Exports: Ctrl-C stops osxphotos. Re-running the same export … --update into the same folder continues where it stopped and skips files it already wrote.
  • ph-album.py adds in batches of 200 and ph-import.py in batches of 100. --timeout SEC or Ctrl-C stop between batches and print what was done (exit 124 or 130). Re-running finishes the job without duplicates.
  • A Photos modal dialog (for example a duplicate-import prompt or a library upgrade) blocks every AppleScript call until someone dismisses it. The helpers time out with a hint instead of hanging.

Safety

  • osxphotos reads a copy of the database. Read commands never modify the library.
  • Album writes are idempotent. Items that are in the album but not in the query are reported, never removed. An ambiguous album name (two albums with the same name) stops with an error.
  • Imports bypass Photos' own duplicate prompt, which would block automation. They skip files whose original name and size are already in the library unless --allow-duplicates is passed.
  • Commands are built as argument lists, never through a shell. Nothing listens on a port. Everything stays on this Mac.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.