From apple-photos
Use this skill when the user wants to query or export photos from their macOS Apple Photos library — searching by date/album/keyword/person, browsing albums and folders, fetching metadata (location, dimensions, type flags), or exporting originals/edited versions to a directory. Backed by osxphotos.
How this skill is triggered — by the user, by Claude, or both
Slash command
/apple-photos:apple-photosThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill enables you to query and export photos from the macOS Apple Photos library using natural language. It is backed by the [osxphotos](https://github.com/RhetTbull/osxphotos) Python library and operates **read-only** against the Photos library — no modifications are made to the library itself, but exports write files to disk.
This skill enables you to query and export photos from the macOS Apple Photos library using natural language. It is backed by the osxphotos Python library and operates read-only against the Photos library — no modifications are made to the library itself, but exports write files to disk.
Use this skill when the user:
| Tool | Purpose |
|---|---|
health-check | Verify osxphotos is installed and the library can be opened |
library-info | High-level stats: counts of photos, movies, albums, folders, keywords, persons |
query | Search the library with combinable filters; returns photo summaries with UUIDs |
get-photo | Full metadata for one photo by UUID (location, dimensions, type flags, etc.) |
list-albums | All albums with their folder paths and photo counts |
list-folders | All folders with parent and album/subfolder counts |
list-keywords | Keywords sorted by usage count (with optional top-N limit) |
list-persons | People detected by face recognition, sorted by photo count |
export | Export one or more photos by UUID to a destination directory |
User: "Find photos of Sarah from last summer"
→ query with person=["Sarah"] fromDate="2025-06-01" toDate="2025-09-01"
User: "Show me my favorite sunsets"
→ query with keyword=["sunset"] favorite=true
User: "Tell me everything about UUID ABC-123"
→ get-photo with uuid="ABC-123"
User: "What albums do I have?"
→ list-albums
User: "What are my top 20 keywords?"
→ list-keywords with limit=20
User: "Export the photos I just searched for to ~/Desktop/sunsets"
→ export with uuid=[...] dest="~/Desktop/sunsets"
User: "I want the edited versions, not the originals"
→ export with edited=true
Two-step workflow: Use query to find UUIDs, then get-photo or export for details/files. Don't ask the user for UUIDs — derive them from a search first.
Hidden photos are excluded by default. Pass hidden=true if the user is looking for them specifically.
System library is the default. Pass library only when the user names a non-default .photoslibrary path.
Date format is ISO 8601 (2025-06-01 or 2025-06-01T00:00:00).
Export creates the destination directory if it doesn't exist. Use overwrite=true only when the user has confirmed they want to replace existing files.
macOS only. The Photos library only exists on macOS.
First-run setup: If health-check reports osxphotos is missing, instruct the user to run npm run setup once in the project to create the venv.
| Error | Likely Cause |
|---|---|
| "osxphotos not installed" | First-run setup not done — run npm run setup |
| "Library not found" | The library path doesn't exist or isn't a .photoslibrary |
| "No photos matched the query" | Filters too narrow — relax the criteria |
| "Photo not found: " | Wrong UUID, or photo deleted |
| Permission errors during export | Destination not writable, or library locked by Photos.app |
Searches MemPalace before answering questions about past work, people, projects, or prior decisions. Returns verbatim stored content instead of guessing from model memory.
Guides Payload CMS config (payload.config.ts), collections, fields, hooks, access control, APIs. Debugs validation errors, security, relationships, queries, transactions, hook behavior.
Implements vector databases with Pinecone, Weaviate, Qdrant, Milvus, pgvector for semantic search, RAG, recommendations, and similarity systems. Optimizes embeddings, indexing, and hybrid search.
npx claudepluginhub sweetrb/apple-photos-mcp --plugin apple-photos