home / skills / openclaw / skills / apple-photos

apple-photos skill

safe

/skills/tyler6204/apple-photos

This skill helps you manage Apple Photos via scripts, listing albums, searching, and exporting photos from Photos.app.

npx playbooks add skill openclaw/skills --skill apple-photos

Review the files below or copy the command above to add this skill to your agents.

Files (11)

SKILL.md

1.5 KB

---
name: apple-photos
description: Apple Photos.app integration for macOS. List albums, browse photos, search by date/person/content, export photos.
metadata: {"clawdbot":{"emoji":"📷","os":["darwin"]}}
---

# Apple Photos

Access Photos.app via SQLite queries. Run scripts from: `cd {baseDir}`

## Requirements
- Full Disk Access for terminal (System Settings → Privacy → Full Disk Access)

## Commands

| Command | Usage |
|---------|-------|
| Library stats | `scripts/photos-count.sh` |
| List albums | `scripts/photos-list-albums.sh` |
| Recent photos | `scripts/photos-recent.sh [count]` |
| List people | `scripts/photos-list-people.sh` |
| Search by person | `scripts/photos-search-person.sh <name> [limit]` |
| Search by content | `scripts/photos-search-content.sh <query> [limit]` |
| Search by date | `scripts/photos-search-date.sh <start> [end] [limit]` |
| Photo info | `scripts/photos-info.sh <uuid>` |
| Export photo | `scripts/photos-export.sh <uuid> [output_path]` |

## Output

- Recent/search: `Filename | Date | Type | UUID`
- People: `ID | Name | Photo Count`
- Default export: `/tmp/photo_export.jpg`

## Workflow: View a Photo

1. Get UUID: `scripts/photos-recent.sh 1`
2. Export: `scripts/photos-export.sh "UUID"`
3. View at `/tmp/photo_export.jpg`

## Notes

- Date format: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM`
- Content search uses ML, slower (~5-10s) than date/person (~100ms)
- HEIC auto-converts to JPEG on export
- Name search is case-insensitive, partial match

Overview

This skill integrates with Apple Photos.app on macOS to list albums, browse and search photos, and export images for further use. It runs lightweight shell scripts that query the Photos library via SQLite and can export HEIC as JPEG. Full Disk Access for the terminal is required to read the library.

How this skill works

The skill executes a set of scripts from a working directory to query the Photos.sqlite database and return structured results like filename, date, type, and UUID. Searches can be by date, person, or content (ML-based), and an export command writes a selectable photo to a temporary path for viewing or downstream processing. Exports auto-convert HEIC to JPEG and default to /tmp/photo_export.jpg.

When to use it

Audit or count images and albums in a Photos library
Quickly find recent images or a specific photo by UUID
Search photos by person name, date range, or visual content
Export individual images for sharing, editing, or backup
Automate photo retrieval in scripts or backups on macOS

Best practices

Grant Full Disk Access to your terminal before running scripts
Run commands from the skill base directory (cd {baseDir}) so scripts find the library
Use person or date searches for fastest results; content searches are ML-based and slower
Specify limits when searching large libraries to reduce output
Copy exported files from /tmp promptly if you need to keep them

Example use cases

Run scripts/photos-count.sh to get a quick library summary before backup
List albums with scripts/photos-list-albums.sh to choose sources for export
Find photos of a person: scripts/photos-search-person.sh "Alice" 50
Get today’s recent photo: scripts/photos-recent.sh 1 then scripts/photos-export.sh "UUID"
Export by UUID in an automation pipeline to feed images into an editor or uploader

FAQ

Do I need any system permissions?

Yes — grant Full Disk Access to the terminal in System Settings → Privacy → Full Disk Access so scripts can read the Photos library.

How do I view an exported photo?

Export with scripts/photos-export.sh "UUID" and open the default output file at /tmp/photo_export.jpg.