Album Manager

⚠️ Connection Required — ALWAYS CHECK FIRST

Before doing ANYTHING else in this skill, call

ping

• If

  ping

  succeeds → proceed with the skill normally.
• If

  ping

  fails or the MCP tools are not available → STOP. Do not continue. Tell the user:

❌ Immich is not connected. This plugin needs a running Immich MCP server to work.

Run /setup-immich-photo-manager to configure your Immich connection. You'll need:

1. Your Immich server URL (e.g.,

   http://192.168.1.100:2283

   )
2. An Immich API key (how to create one)
3. The MCP server running (

   ./immich-mcp-server

   )

Nothing in this plugin will work until the connection is configured.

Do NOT skip this check. Do NOT try to run any other tool first. Always ping, always block if it fails.

Intelligent album creation and curation for Immich photo libraries. Organizes photos geographically by default — albums represent places, not dates.

Core Principle

Geography first, chronology second. A user who visited Mexico twice gets one "Mexico" album (or sub-albums by city), not "Mexico 2018" and "Mexico 2023". Dates are metadata shown inside the album, never the organizing principle.

Available MCP Tools

Use the Immich MCP tools for all API interactions:

• immich_search_assets

  — Search by GPS coordinates, date range, city, country, camera, person, or smart/CLIP text query

• immich_create_album

  — Create a new album with name and description

• immich_add_assets_to_album

  — Add photos/videos to an album by asset IDs

• immich_remove_assets_from_album

  — Remove assets from an album

• immich_list_albums

  — List all albums with asset counts

• immich_get_album

  — Get album details including all assets

• immich_delete_album

  — Delete an album (does NOT delete the photos)

• immich_create_shared_link

  — Create a public shared link for an album (makes it visible in Gallery)

• immich_get_asset_info

  — Get full metadata for a specific asset (GPS, EXIF, dates)

• immich_get_statistics

  — Get library statistics (total photos, videos, storage)

• immich_get_asset_thumbnail

  — Get base64 thumbnail for an asset (used for gallery HTML generation)

Album Creation Workflow

1. Discover photos for a location

Search by GPS bounding box OR by CLIP semantic search OR by date range:

# GPS-based (most accurate)
immich_search_assets(latitude=41.87, longitude=12.49, radius_km=50)  # Rome area

# CLIP semantic search (when GPS is missing)
immich_search_assets(query="Colosseum Rome Italy")

# Date-based (supplement)
immich_search_assets(date_from="2023-06-01", date_to="2023-06-15")

# Combined
immich_search_assets(latitude=41.87, longitude=12.49, radius_km=50, date_from="2023-06-01")

2. Filter and curate

From the search results, filter out:

• Screenshots (typical screen resolutions, no GPS, no lens info)
• Duplicate/near-duplicate images
• Blurry or very dark photos (if quality metadata available)
• Photos that don't match the location theme

Prefer photos that:

• Have strong composition or visual interest
• Show landmarks, landscapes, or characteristic scenes of the place
• Have good resolution and quality
• Tell the story of the place

Target: 20-50 photos per album for optimal gallery experience. Can go up to 100 for major destinations.

3. Create the album

Naming convention:

[Country emoji] Place, Country
Examples:
🇮🇹 Cinque Terre, Italia
🇪🇬 Cairo & Luxor, Egypt
🇲🇽 Chiapas, México
🏝️ Lanzarote
🌴 La Palma
🏙️ Barcelona

For the description, include:

• When the photos were taken (year or date range)
• Brief context (e.g., "Summer road trip through coastal villages")
• Number of photos

4. Share for Gallery publication

After creating the album, create a shared link to make it visible in the Gallery frontend:

immich_create_shared_link(album_id="{id}", show_metadata=true, allow_download=false)

5. Verify

Confirm the album appears correctly:

• Check album name and description
• Verify photo count matches expectations
• Confirm shared link is active

Batch Album Creation

When creating multiple albums at once (e.g., "create albums for all my trips"):

1. First, get library statistics and map view data to understand what locations exist
2. Cluster photos by GPS coordinates to identify distinct locations
3. Present a proposed album list to the user for approval BEFORE creating
4. Create albums one by one, reporting progress
5. Summarize all created albums at the end

Always err on the side of creating MORE albums — the user can merge or delete later. It's easier to remove an unwanted album than to discover a missing one.

Handling Missing GPS Data

Many photos (especially older ones or screenshots) lack GPS coordinates. Strategy:

1. First search by GPS for photos that have it
2. Then search by date range to find photos taken during the same trip
3. Use CLIP semantic search as a fallback ("beach Lanzarote", "pyramid Egypt")
4. Flag photos without GPS that were found by date/CLIP — they may or may not belong

Album Maintenance

When asked to update or refine an existing album:

1. Get current album contents
2. Search for additional photos that might belong (expanded date range, nearby GPS, related CLIP queries)
3. Present additions and potential removals to the user
4. Apply changes after approval

Gallery HTML Generation

When the user asks to "show me photos from [album]", "generate a gallery for [album]", "show me [album name]", or any variation of viewing/displaying album contents visually, generate an interactive HTML gallery page.

Template

Use the gallery template at

assets/viewer-template.html

• Triple theme support — Light, System (auto-detects), and Dark modes
• 5 view modes: detail grid, icon grid, list, masonry, compact
• Full-screen gallery overlay with keyboard navigation (arrows, Escape, Space for slideshow)
• Touch/swipe gestures for mobile
• Lazy loading with intersection observers
• Manual pagination with "Load more" button (no infinite scroll)
• Slideshow mode with progress bar
• Polaroid-style album cards linking back to Immich
• Responsive design for all screen sizes

Placeholder Reference

The template uses these placeholders that MUST be replaced:

{{ALBUM_NAME}}

Lanzarote Verde

{{ALBUM_TOTAL}}

273

{{SEARCH_QUERY}}

“green landscapes in Lanzarote”

{{IMMICH_URL}}

https://your-immich-server.com

{{PAGE_SIZE}}

20

{{PHOTO_COUNT}}

50

{{PHOTO_ENTRIES}}

{{ALBUMS_JSON}}

Photo Entry Format (base64 embedded thumbnails)

The Cowork viewer runs in an

about:

data:

Each entry in

{{PHOTO_ENTRIES}}

{src:'data:image/jpeg;base64,/9j/4AAQ...',id:'<asset-id>',name:'<filename>',date:'<ISO-date>'}

• src

  : Base64 data URI of the thumbnail (from

  get_thumbnails_batch

  , size=thumbnail, ~250px, ~15-25KB each)

• id

  : The Immich asset ID (for linking to Immich web UI)

• name

  : Original filename (displayed as label)

• date

  : ISO date string from the asset metadata

Always use

size="thumbnail"

preview

Entries are comma-separated, one per line.

Albums JSON Format

{{ALBUMS_JSON}}

[{...}]

{...}

[{"id":"<album-id>","name":"<Album Name>","total":<count>}]

Each album object needs:

id

name

total

Generation Workflow

1. Get album data: Call

   get_album

   to get the album ID, name, and full asset list (IDs, filenames, dates)
2. Fetch thumbnails: Call

   get_thumbnails_batch(asset_ids=[...], size="thumbnail", limit=50)

   — call in batches of 50 if needed
3. Read the template: Read

   assets/viewer-template.html

   from the plugin root
4. Replace placeholders: Fill in all

   {{...}}

   placeholders
5. Build

   {{PHOTO_ENTRIES}}

   :

   {src:'data:...',id:'...',name:'...',date:'...'}

   for each asset with base64 thumbnail
6. Write the HTML: Save to the outputs directory as

   <album-name-slug>.html

   (~0.9MB for 50 photos)
7. Present to user: Share the file link via

   computer://

get_thumbnails_batch

⚠️ Placeholder Rules (IMPORTANT)

• {{PAGE_SIZE}}

  ,

  {{PHOTO_COUNT}}

  ,

  {{ALBUM_TOTAL}}

  : Must be plain integers (e.g.

  200

  , not

  200+

  or

  "200"

  ). These are injected directly into JavaScript.

• {{ALBUM_NAME}}

  ,

  {{SEARCH_QUERY}}

  ,

  {{IMMICH_URL}}

  : Can be any string (they are placed inside HTML or JS string literals).

• {{PHOTO_ENTRIES}}

  : Must be valid JS object literals, comma-separated.

• {{ALBUMS_JSON}}

  : Must be comma-separated JSON objects (NOT wrapped in array brackets — the template adds

  [...]

  ). Example:

  {"id":"abc","name":"My Album","total":50}

  . If no related albums, use empty string.

CRITICAL: Related Albums = REAL Albums Only

The

{{ALBUMS_JSON}}

When generating a gallery for an album, find OTHER real albums that are related (e.g., same country, same trip) and list them as Related Albums. If there are no related albums, use

[]

Performance Notes

• PAGE_SIZE: Keep at 20 for initial load. Pagination is manual ("Load more" button)
• PHOTO_COUNT: Limit to ~50 photos per gallery for reasonable file size (~0.9MB)
• Thumbnails: Embedded as base64 via

  get_thumbnails_batch(size="thumbnail")

  — ~18KB avg each
• For albums with 100+ photos, show first 50 and tell the user the total count

Example: Generating a gallery

User: "Show me photos from Lanzarote Verde"

1. list_albums() -> find "Lanzarote Verde" album (id: abc123, 273 photos)
2. get_album(album_id="abc123") -> get full asset list with IDs, names, dates
3. Read assets/viewer-template.html
4. Replace:
   - {{ALBUM_NAME}} -> "Lanzarote Verde"
   - {{ALBUM_TOTAL}} -> 273
   - {{SEARCH_QUERY}} -> "Lanzarote Verde"
   - {{IMMICH_URL}} -> "https://your-immich-server.com"
   - {{PAGE_SIZE}} -> 20
   - {{PHOTO_COUNT}} -> 50 (first 50 of 273)
   - {{PHOTO_ENTRIES}} -> {src:'data:image/jpeg;base64,...',id:"abc",name:"IMG_001",date:"2023-06-15"},{src:'data:...',id:"def",...}
   - {{ALBUMS_JSON}} -> {"id":"abc123","name":"Lanzarote Verde","total":273}
5. Save as lanzarote-verde.html (~0.9MB)
6. Present computer:// link

Reference Files

• references/geographic-search-patterns.md

  — GPS bounding boxes of common destinations and search strategies

• assets/index-template.html

  — Dashboard template listing all saved gallery HTML files

• assets/viewer-template.html

  — Self-contained HTML gallery template with dark/light themes, multiple view modes, slideshow, Cowork Actions Panel, and keyboard navigation