Photo Book Organizer

How to Use

Initial Setup

From your project directory:

cd ~/photos-2024

Then run Claude Code and ask:

Help me organize photos for my 2024 photo book

Or more specifically:

I want to create a photo book from photos in ./family-photos-2024

During the Process

The skill will guide you through:

• Naming detected events
• Creating custom themes
• Reviewing AI quality rankings
• Organizing photos in a visual interface

Instructions

Phase 1: Check Dependencies and Setup

Before starting, verify required tools are available:

# Check for required tools
command -v rg >/dev/null 2>&1 || echo "Missing: ripgrep (install via: brew install ripgrep)"
command -v exiftool >/dev/null 2>&1 || echo "Missing: exiftool (install via: brew install exiftool)"
command -v convert >/dev/null 2>&1 || echo "Missing: imagemagick (install via: brew install imagemagick)"
command -v jq >/dev/null 2>&1 || echo "Missing: jq (install via: brew install jq)"

If any tools are missing, inform the user and provide installation commands for their platform.

Ask the user for:

1. Source folder path (relative path containing all photos)
2. Year for the photo book (for naming/organization)

Create working directory structure:

mkdir -p .photobook-temp/{thumbnails,metadata}
mkdir -p photobook-output

Phase 2: Discover and Extract Metadata

Use ripgrep to find all image files:

# Find all image files
rg --files -g '*.{jpg,jpeg,png,JPG,JPEG,PNG,heic,HEIC}' [source_folder] > .photobook-temp/file_list.txt

# Count total files
wc -l .photobook-temp/file_list.txt

Run the metadata extraction script:

bash scripts/extract_exif.sh [source_folder]

This generates .photobook-temp/metadata/photos_metadata.json containing:

• Filepath
• DateTime
• GPS coordinates (if available)
• Camera model
• Image dimensions
• File size

Phase 3: Cluster Photos into Events

Run the clustering script:

python3 scripts/cluster_photos.py

This analyzes temporal and spatial proximity to create initial event clusters. Output is .photobook-temp/clusters.json.

Present clusters to the user:

# Detected Events

I found [N] potential events based on time and location clustering:

## Cluster 1: [Date Range]
- **Photos**: 47 photos
- **Date range**: June 15-17, 2024
- **Location**: Copenhagen (if GPS available)
- **Sample photos**: [show 3-4 representative filenames]

What should I call this event? (e.g., "Summer Copenhagen Trip")

## Cluster 2: [Date Range]
...

[Continue for all clusters]

Allow user to:

• Name each cluster
• Merge clusters (if they're the same event)
• Split clusters (if mixed events)
• Skip clusters (if not for the book)

Phase 4: Identify Custom Theme Suggestions

Analyze photo metadata and filenames to suggest custom themes:

python3 scripts/suggest_themes.py

This script looks for:

• Repeated activities (multiple photos with similar timestamps across different dates)
• Keyword patterns in filenames (e.g., "judo", "handball", "birthday")
• Regular intervals (e.g., monthly patterns)

Present suggestions:

# Suggested Custom Themes

Based on patterns in your photos, you might want these theme pages:

1. **Judo Tournaments** (15 photos across 4 dates)
2. **Handball Matches** (12 photos across 3 dates)
3. **Monthly Portraits** (12 photos, one from each month)

Would you like to:
- Add any of these themes? (yes/no for each)
- Create your own custom theme? (provide theme name)

For each custom theme, help the user tag relevant photos by:

• Showing candidate photos matching patterns
• Allowing keyword search in filenames
• Allowing date range selection

Phase 5: Generate Thumbnails

Create scaled-down versions for the UI:

bash scripts/generate_thumbnails.sh [source_folder]

This creates 400px wide thumbnails in .photobook-temp/thumbnails/ preserving directory structure.

Phase 6: AI Quality Ranking

For each event/theme, use the Claude API to rank photos. Prompt yourself with:

I have [N] photos from [event_name]. Please analyze and rank them based on:
- Technical quality (sharpness, exposure, composition)
- Emotional impact (captured moments, expressions)
- Variety (avoid too many similar shots)
- People representation (ensure everyone is included)

Here are the photo filenames and basic metadata:
[provide list with timestamps, filenames]

Please respond ONLY in JSON format with this structure:
{
  "rankings": [
    {
      "filename": "IMG_1234.jpg",
      "score": 8.5,
      "reasoning": "Sharp focus, great composition, genuine smiles",
      "category": "keeper",
      "similar_to": ["IMG_1233.jpg", "IMG_1235.jpg"]
    }
  ],
  "recommended_count": 15,
  "duplicate_groups": [
    ["IMG_1233.jpg", "IMG_1234.jpg", "IMG_1235.jpg"]
  ]
}

Categories: "keeper" (top tier), "consider" (good but similar to others), "skip" (blur/bad exposure)

For photos, you can include thumbnail image data if helpful for analysis. Process rankings in batches of 50-100 photos to stay within context limits.

Save rankings to .photobook-temp/rankings/[event_name].json

Phase 7: Create Interactive Organization UI

Create an HTML artifact that:

1. Loads all photos and rankings:

   • Read thumbnails using window.fs.readFile
   • Load all event/theme configurations
   • Display AI rankings and recommendations

2. Organizes by theme sections:

   • One section per event/theme
   • Shows thumbnails in grid layout
   • Displays AI scores and notes
   • Color-codes: keeper (green), consider (yellow), skip (gray)

3. Enables drag-and-drop:

   • Drag photos between themes
   • Reorder within themes
   • Remove/add back photos
   • Mark favorites

4. Persists state:

   • Use window.storage to save current organization
   • Auto-save on changes
   • Allow reset to AI recommendations

5. Theme management:

   • Add new custom themes
   • Rename themes
   • Delete themes
   • Search photos to add to themes

6. Export configuration:

   • Generate YAML config
   • Show summary stats
   • Preview page layout

Example artifact structure:

import { useState, useEffect } from 'react';

export default function PhotoBookOrganizer() {
  const [themes, setThemes] = useState([]);
  const [photos, setPhotos] = useState({});
  const [selectedTheme, setSelectedTheme] = useState(null);
  
  // Load photos and rankings
  useEffect(() => {
    loadPhotoData();
  }, []);
  
  async function loadPhotoData() {
    // Load rankings and metadata
    // Create thumbnail image data
    // Initialize themes from clusters
  }
  
  // Drag and drop handlers
  // Theme management functions
  // Export to YAML function
  
  return (
    <div className="flex h-screen">
      {/* Theme sidebar */}
      {/* Photo grid */}
      {/* Export panel */}
    </div>
  );
}

The UI should feel like organizing physical photos on a table - intuitive, visual, and tactile.

Phase 8: Generate Configuration File

Based on the user's final organization in the UI, create photobook-output/photobook_[YEAR].yaml: