Skill: kensonh/film-location-scout (version 1.0.0)

--- name: film-location-scout version: 1.0.0 description: >- Discover nearby film and TV show shooting locations based on the user's current city and position. Outputs 5 self-contained cases, each with a cinematic scene recreation image featuring 1-2 prominent characters/people in the foreground (perfect for photo recreation), precise GPS coordinates, scene description, and weather-based photography parameters. Use when the user mentions film locations, movie shooting spots, TV drama filming sites, cinematic photography, scene pilgrimage, or wants to find nearby places where movies were filmed. Also trigger when user asks about photography at famous film locations or wants a film-inspired photo guide. author: Qoder license: MIT tags: - film - location - photography - travel - cinema - movie - scene - tourism --- # Film Location Scout Discover 5 nearby film/TV shooting locations. Each case is self-contained: cinematic scene image with 1-2 prominent characters in the foreground (perfect for photo recreation) + precise location + photography parameters. ## Trigger User invokes `/film-location-scout` or asks naturally: - "帮我找附近的电影取景地" - "推荐一些可以拍照的电影场景地点" - "附近有什么电影拍摄地" - "film locations near me" - "movie shooting spots nearby" ## Workflow ``` Step 1: Get User Location (IP + confirm) | Step 2: Get Weather & Light Conditions | Step 3: Find 5 Filming Locations within 5km (each as a complete case) | For each of the 5 cases: 3a. Location + precise coordinates 3b. Film scene description 3c. Per-location photography parameters 3d. Generate cinematic scene image (with 1-2 prominent characters in foreground) | Step 4: Output all 5 cases ``` ## Step 1: Get User Location **Phase A - IP auto-detect:** Use WebFetch to query: `https://ipinfo.io/json` Extract: `city`, `region`, `country`, `loc` (lat,lon). **Phase B - User confirmation:** Use AskUserQuestion: > "Detected you are in **{city}**. Is that correct? Please also provide your specific location (landmark, intersection, or address) for precise nearby search." Store: - `city_name`: city name (Chinese + English) - `user_lat`, `user_lon`: **6 decimal places** precision (e.g., `31.230416, 121.473701`) ## Step 2: Get Weather & Light Conditions Use WebSearch: `"{city_name}" weather now temperature humidity` Record: - `weather`: condition (sunny/cloudy/rainy/foggy/snowy/night) - `temperature`: current temp - `humidity`, `wind`, `visibility` - `time_of_day`: calculate from current local time -> golden hour / blue hour / midday / overcast / night - `sun_position`: high / low / setting / rising These will be used per-case in Step 3c. ## Step 3: Build 5 Cases Search for filming locations near the user using built-in knowledge + WebSearch: 1. WebSearch queries (run multiple): - `"{city_name}" famous movie filming locations exact address` - `"{city_name}" TV drama shooting spots GPS coordinates` - `"{city_name}" film scenes famous landmarks` - Also search in Chinese: `"{city_name}" 电影取景地 地址` 2. From results, select **exactly 5** locations that: - Are within **5km** of user (expand to 10km if <5 found, note this) - Come from well-known, diverse films/shows (mix genres, eras) - Have identifiable, visitable spots 3. For each location, use WebSearch to get **precise coordinates**: - Query: `"{location_name}" GPS coordinates` or `"{location_name}" 经纬度` - Coordinates MUST be **6 decimal places** (e.g., `31.239728, 121.499718`) - If WebSearch cannot provide exact coordinates, search for the venue/landmark coordinates directly ### For EACH of the 5 cases, produce all 4 parts: #### 3a. Precise Location Info ``` Name: {location_name} ({location_name_english}) Address: {full_street_address, including district} Coordinates: {lat_6dp}, {lon_6dp} Distance: {distance_in_meters}m from your position Map: https://www.google.com/maps?q={lat},{lon} ``` - Address must include district/neighborhood level detail - Distance in **meters** (not km) for locations <1km; in km with 1 decimal for >1km #### 3b. Film Scene Description ``` Film: {title} ({original_title}, {year}) Director: {director} Genre: {genre} Scene: {detailed_description_of_the_specific_scene} ``` The scene description must be **concrete and vivid** (3-5 sentences): - What happens in the scene (plot context) - What the shot looks like (camera angle, framing, movement) - What makes this location recognizable in the film - Timestamp or episode reference if available (e.g., "01:23:45" or "S02E05") #### 3c. Photography Parameters (per-location) Read [photo-params-reference.md](photo-params-reference.md) for the parameter matrix. Combine the weather/light from Step 2 with **this specific location's characteristics** to produce tailored settings: ``` Light Condition: {time_of_day} + {weather} at {location_type} Camera Settings: Aperture: f/{value} ({reason_for_this_location}) Shutter Speed: {value} ({reason}) ISO: {value} ({reason}) White Balance: {value}K ({reason}) Exposure Comp: {value} EV ({reason}) Focal Length: {value}mm ({reason_matching_film_shot}) Composition Tip: {1-2 sentences on how to frame THIS specific location to match the film} Phone Tip: {1 sentence for phone users} ``` Key: the focal length should **match the look of the original film shot** when possible. The composition tip must reference the specific film scene. #### 3d. Generate Cinematic Scene Image Use **ImageGen** for each case. Read [scene-prompts.md](scene-prompts.md) for prompt templates. **CRITICAL REQUIREMENTS for the image:** 1. **1-2 prominent characters/people in the foreground** - This is ESSENTIAL for photo recreation - Characters should be clearly visible and take up significant frame space (not tiny background figures) - Position them in the foreground or middle ground where they can be the focus - Show their full body or 3/4 body, not just tiny silhouettes 2. **Realistic photographic style** - Must look like a real movie still / film screenshot: - Photorealistic, shot on 35mm film aesthetic - The **real landmark/venue** as recognizable background - Cinematic color grading matching the film's visual tone - Film-accurate camera angle and composition - Appropriate lighting reflecting the film's mood and current weather 3. **NOT illustration, NOT sketch, NOT cartoon** Parameters: - Size: `1024x768` - Name: `scene-{case_number}-{location_slug}` **IMPORTANT**: Generate **5 separate images**, one per case. Do NOT batch into a single image. ## Step 4: Output Format Present as 5 self-contained cards. Each card has all 4 parts together: ```markdown # {City} Film Location Scout > Location: {user_location} | Time: {time} | Weather: {weather} {temp} --- ## Case 1: {location_name} ### Film **{title}** ({year}) dir. {director} {detailed_scene_description} ### Location - Address: {full_address} - Coordinates: `{lat_6dp}, {lon_6dp}` - Distance: {distance} from you - [Open in Maps](https://www.google.com/maps?q={lat},{lon}) ### Photography Settings | Parameter | Value | Reason | |-----------|-------|--------| | Aperture | f/{val} | {reason} | | Shutter | {val} | {reason} | | ISO | {val} | {reason} | | WB | {val}K | {reason} | | EV | {val} | {reason} | | Focal | {val}mm | {reason} | > Composition: {composition_tip} > Phone: {phone_tip} ### Scene Image {scene_image} **Photo Recreation Tip**: Stand where the {character_description} is positioned in the image above. Frame yourself similarly with the {landmark_feature} visible in the background for the perfect recreation shot. --- ## Case 2: {location_name} ... [Cases 3-5 follow same structure] ``` ## Error Handling - IP geolocation fails -> ask user directly - <5 locations within 5km -> expand to 10km, note this - No films for city -> broaden to province/region - Weather unavailable -> use general outdoor params from reference - ImageGen fails -> describe composition in text - Coordinates imprecise -> use the landmark/venue's known coordinates, never round beyond 6 decimal places ## Logging Throughout the execution, log key information for transparency and debugging: ### Log Structure ``` [LOG] {timestamp} | {step} | {status} | {details} ``` ### Required Log Points 1. **Location Detection** - `[LOG] {time} | LOCATION | DETECTED | City: {city}, Coords: {lat},{lon}` - `[LOG] {time} | LOCATION | CONFIRMED | User confirmed: {confirmed_location}` 2. **Weather Fetch** - `[LOG] {time} | WEATHER | FETCHED | {weather}, {temp}°C, {condition}` - `[LOG] {time} | LIGHT | CALCULATED | {time_of_day}, {sun_position}` 3. **Location Search** - `[LOG] {time} | SEARCH | STARTED | Querying {city} film locations` - `[LOG] {time} | SEARCH | FOUND | {count} locations within {radius}km` - `[LOG] {time} | SELECTED | {location_name} | Film: {title} | Distance: {distance}m` 4. **Image Generation** - `[LOG] {time} | IMAGE | GENERATING | Case {n}: {location_name}` - `[LOG] {time} | IMAGE | SUCCESS | Case {n}: {filename} generated` - `[LOG] {time} | IMAGE | FAILED | Case {n}: {error_reason}` 5. **Completion** - `[LOG] {time} | COMPLETE | {total_cases} cases generated | Total distance range: {min}m - {max}m` ### Log Output Present logs in a collapsible section at the end of the response: ```markdown <details> <summary>Execution Log</summary> ``` [LOG] 14:32:01 | LOCATION | DETECTED | City: Shanghai, Coords: 31.230416,121.473701 [LOG] 14:32:03 | LOCATION | CONFIRMED | User confirmed: The Bund [LOG] 14:32:05 | WEATHER | FETCHED | Cloudy, 18°C, Overcast ... ``` </details> ``` ## Skill Description ### Purpose Film Location Scout helps users discover nearby film and TV shooting locations for cinematic photography and scene recreation. It combines real-world location data with film scene information to create a complete photo guide. ### Capabilities - Auto-detects user location via IP geolocation - Searches for film/TV shooting locations within 5km radius - Generates cinematic scene images with prominent characters for photo reference - Provides precise GPS coordinates and navigation links - Calculates weather-based photography parameters - Offers composition tips matching the original film shots ### Output Format 5 self-contained cases, each containing: 1. **Film Info**: Title, director, genre, detailed scene description 2. **Location**: Name, full address, precise coordinates (6 decimal places), distance, map link 3. **Photography Settings**: Aperture, shutter, ISO, WB, EV, focal length with reasons 4. **Scene Image**: AI-generated cinematic still with 1-2 prominent characters for photo recreation ### Use Cases - **Photo Recreation**: Users can stand where characters stood and recreate iconic shots - **Film Tourism**: Discover filming locations while traveling - **Cinematic Photography**: Learn professional camera settings for location shooting - **Scene Pilgrimage**: Visit famous movie spots in your own city ### Limitations - Requires locations to be within database/knowledge coverage - Image generation depends on AI capabilities and may not perfectly match the film - Weather data is current conditions, not when the scene was filmed - Coordinates accuracy depends on available data sources ### Dependencies - IP geolocation service (ipinfo.io) - Web search for location and weather data - Image generation capability - Real-time weather information

path: scene-prompts.md
content: # Cinematic Scene Image Prompt Templates

## Core Principle

Every generated image must look like a **real movie screenshot / film still** — realistic, cinematic, with **1-2 prominent characters in the foreground** that users can use as reference for photo recreation. NEVER generate illustrations, sketches, cartoons, or storyboards.

## CRITICAL: Character Prominence Requirements

**The image MUST have 1-2 clearly visible people in the foreground/mid-ground:**

- Characters should occupy at least **20-40% of the frame** (not tiny background figures)
- Show **full body, 3/4 body, or at least waist-up** - avoid tiny silhouettes
- Position characters in the **foreground or middle ground** where they are the visual focus
- Characters should be **recognizably human** with clear features, clothing, and posture
- The background landmark should be visible but secondary to the characters

**Why this matters**: Users need to see WHERE to stand and HOW to pose for their own photo recreation. The character's position and framing is their reference.

## Base Prompt Structure

```
Cinematic movie still, photorealistic, shot on 35mm film. {scene_action_description} at {location_name}. {character_description} {character_action}, positioned prominently in the foreground. {location_visual_details} visible in the background. {lighting_description}. {color_grading}. Widescreen {aspect_ratio} frame, {camera_angle}, {focal_length} lens. Film grain, shallow depth of field, {mood} atmosphere.
```

## Building the Prompt — Field by Field

### 1. Scene Action (what is happening)

Describe the scene from the film concretely:
- "A man in a dark coat stands alone on the rain-soaked waterfront promenade, gazing across the river"
- "Two young women run laughing through a narrow old-town alley, shopping bags in hand"
- "A couple sits on a park bench under cherry blossoms, deep in conversation"

### 2. Character Description (CRITICAL — 1-2 prominent characters required)

Describe characters by **appearance, clothing, posture** — NOT by actor name:

**Single Character Examples:**
- "A young woman in a red qipao dress, hair pinned up, standing prominently in the foreground"
- "A man in his 30s wearing a long wool overcoat and scarf, positioned center frame"
- "A silhouetted figure standing at the edge of the rooftop, clearly visible against the sky"

**Two Characters Examples:**
- "Two people in the foreground: a young woman in a beige trench coat and a man in a dark suit, standing side by side"
- "A couple seated on a bench in the middle ground: the woman in a flowing white dress, the man in a casual blazer"
- "Two friends walking together in the foreground, one in a leather jacket and the other in a colorful cardigan"

**Rules:**
- **ALWAYS include 1-2 characters prominently in the foreground/mid-ground**
- Characters must be **clearly visible** (not tiny background figures)
- Describe clothing, age range, posture, and action in detail
- Match the character's look to the film's era and style
- Do NOT use real actor/actress names
- Position characters where users can easily stand to recreate the shot

### 3. Location Visual Details

Describe the **recognizable features** of the real location in the background:
- "The art-deco facades of 1920s colonial buildings line the waterfront boulevard behind them"
- "A narrow lane with hanging red lanterns, wet cobblestones, and old wooden shopfronts visible in the distance"
- "A modern glass skyscraper lobby with marble floors reflecting fluorescent lights behind the characters"

### 4. Lighting Description

Match to current weather + film mood:

| Condition | Lighting Prompt |
|-----------|----------------|
| Sunny midday | "Bright natural sunlight casting hard shadows, high contrast, characters well-lit" |
| Golden hour | "Warm golden backlight streaming through the scene, long shadows, lens flare on characters" |
| Blue hour | "Cool blue ambient twilight, warm city lights beginning to glow, characters softly illuminated" |
| Overcast | "Soft diffused daylight, even illumination, no harsh shadows on characters" |
| Rainy | "Moody overcast light, wet reflections on every surface, neon signs glowing, characters reflected on wet ground" |
| Foggy | "Misty diffused light, low visibility, ethereal glow around light sources, characters emerging from fog" |
| Night | "Dramatic artificial lighting, pools of warm streetlight illuminating characters, deep shadows, neon glow" |

### 5. Color Grading

Match the film's visual style:

| Film Style | Color Grading Prompt |
|------------|---------------------|
| Warm drama / romance | "Warm amber and golden tones, soft highlights, romantic color palette" |
| Cool thriller / noir | "Desaturated cool blue-green tones, high contrast, noir aesthetic" |
| Vibrant comedy | "Vivid saturated colors, bright and lively color palette" |
| Vintage / period | "Faded warm tones with slight sepia cast, vintage film color rendition" |
| Modern clean | "Clean neutral color grading, balanced tones, contemporary cinematic look" |
| Moody art-house | "Muted earth tones, crushed blacks, subdued color palette" |

### 6. Camera Angle & Lens

| Shot Type | Prompt Fragment |
|-----------|----------------|
| Establishing wide with characters | "Wide shot, 24mm lens, characters prominent in foreground with full environment visible behind" |
| Medium shot | "Medium shot, 50mm lens, characters from waist up, background landmark visible" |
| Close-up emotional | "Close-up, 85mm lens, shallow depth of field, character face detail with location softly blurred behind" |
| Over-shoulder | "Over-the-shoulder shot, 50mm lens, conversational framing with both characters visible" |
| Low angle dramatic | "Low angle shot looking up, 35mm lens, characters prominent against imposing architecture" |
| High angle overview | "High angle shot looking down, 28mm lens, characters visible in the scene below" |
| Environmental portrait | "Environmental portrait framing, 35mm lens, characters taking up 30% of frame with iconic location behind" |

## Scene Type Templates

### Urban Street Scene
```
Cinematic movie still, photorealistic, shot on 35mm film. {character_description} {action} on {street_name}, positioned prominently in the foreground. {street_visual_details} visible behind them. {lighting}. {color_grading}. Widescreen 2.39:1 frame, street-level shot at character eye-level, 35mm lens. Film grain, depth created by converging buildings, {mood} atmosphere.
```

### Waterfront / River Scene
```
Cinematic movie still, photorealistic, shot on 35mm film. {character_description} {action} along {waterfront_name}, positioned in the foreground with {water_feature} stretching into the distance behind them. {skyline_or_background} visible in the background. {lighting} reflected on the water surface. {color_grading}. Widescreen 2.39:1 frame, medium shot framing characters prominently, 35mm lens. Film grain, atmospheric haze, {mood} atmosphere.
```

### Historic Building / Architecture Scene
```
Cinematic movie still, photorealistic, shot on 35mm film. {character_description} {action} in the foreground in front of {building_name}, with {architectural_details} visible behind them. {lighting} falling across the facade and illuminating the characters. {color_grading}. Widescreen 2.39:1 frame, low angle emphasizing both characters and architecture, 28mm lens. Film grain, grand scale, {mood} atmosphere.
```

### Park / Garden Scene
```
Cinematic movie still, photorealistic, shot on 35mm film. {character_description} {action} in {park_name}, positioned prominently in the foreground surrounded by {nature_details}. {lighting} filtering through the foliage onto the characters. {color_grading}. Widescreen 2.39:1 frame, medium shot with characters clearly visible, 50mm lens. Film grain, natural bokeh from leaves, {mood} atmosphere.
```

### Interior / Venue Scene
```
Cinematic movie still, photorealistic, shot on 35mm film. {character_description} {action} inside {venue_name}, positioned in the foreground with {interior_details} visible behind them. {lighting} from {light_source} illuminating the characters. {color_grading}. Widescreen 2.39:1 frame, medium-wide shot with prominent characters, 35mm lens. Film grain, practical lighting, {mood} atmosphere.
```

## Complete Example Prompts

### Example 1: Single Character Prominent
```
Cinematic movie still, photorealistic, shot on 35mm film. A man in his 30s wearing a long dark wool overcoat stands alone on the rain-soaked Bund waterfront promenade in Shanghai, positioned prominently in the center foreground, gazing across the Huangpu River toward the glowing Lujiazui skyline. The art-deco facades of 1920s colonial buildings stretch behind him, wet stone pavement reflecting the warm streetlights. Moody overcast light illuminating the character, wet reflections on every surface, neon signs glowing in the distance. Desaturated cool blue-green tones with warm amber highlights from the streetlamps, high contrast, noir aesthetic. Widescreen 2.39:1 frame, medium-wide shot from slightly low angle with the character taking up 30% of the frame, 35mm lens. Film grain, shallow depth of field with bokeh city lights behind the character, melancholic atmosphere.
```

### Example 2: Two Characters Prominent
```
Cinematic movie still, photorealistic, shot on 35mm film. Two people walking side by side in the foreground: a young woman in a flowing red dress and a man in a light-colored linen suit, walking along the cobblestone street of a Parisian alley. Historic buildings with wrought-iron balconies line the narrow street behind them, flower boxes on windowsills. Warm golden hour light streaming from behind, creating rim lighting on their silhouettes, long shadows stretching before them. Warm amber and golden tones, soft romantic highlights, vintage film color palette. Widescreen 2.39:1 frame, medium shot capturing both characters from the knees up, 50mm lens. Film grain, shallow depth of field with the alley softly blurred behind them, romantic nostalgic atmosphere.
```

### Example 3: Character as Photo Reference
```
Cinematic movie still, photorealistic, shot on 35mm film. A young woman in a yellow raincoat stands prominently in the foreground on the steps of the Philadelphia Museum of Art, one arm raised triumphantly, the other at her side. The grand neoclassical columns and facade of the museum rise behind her, the wide stone steps stretching down. Overcast soft diffused daylight, even illumination on the character, grey sky above. Clean neutral color grading, balanced tones, contemporary cinematic look. Widescreen 2.39:1 frame, low angle shot looking up at the character, 35mm lens. Film grain, the character clearly visible and centered, inspirational triumphant atmosphere.
```

## Per-Case Generation Rules

1. **5 separate images**: One ImageGen call per case, never combine
2. **Each image is unique**: Tailor prompt to the specific location, film, and scene
3. **1-2 prominent characters are MANDATORY**: Every image MUST have clearly visible people in the foreground/mid-ground
4. **Characters as photo reference**: Position and frame characters so users know exactly where to stand for recreation
5. **Match the film**: Camera angle, color grading, and mood should reflect the original film's style
6. **Reflect current weather**: Incorporate the real weather conditions into lighting description
7. **Balance composition**: Characters prominent (20-40% of frame) with recognizable location visible behind

## ImageGen Parameters

- **Size**: Always `1024x768` (4:3 landscape, cinematic frame ratio)
- **Name format**: `scene-{case_number}-{location_slug}` (e.g., `scene-1-the-bund`, `scene-2-nanjing-road`)

## Photo Recreation Guidance

After generating each image, provide the user with specific guidance:

```
**Photo Recreation Tip**: Stand where the {character_description} is positioned in the image above. 
Frame yourself similarly with the {landmark_feature} visible in the background for the perfect recreation shot.
```


path: install.sh
content: #!/usr/bin/env bash
# Cross-platform installer for film-location-scout skill
# Supports: Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, and more

set -e

SKILL_NAME="film-location-scout"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

log_info() {
    echo -e "${BLUE}[INFO]${NC} $1"
}

log_success() {
    echo -e "${GREEN}[SUCCESS]${NC} $1"
}

log_warn() {
    echo -e "${YELLOW}[WARN]${NC} $1"
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $1"
}

# Detect platform
detect_platform() {
    if [ -n "$1" ]; then
        echo "$1"
        return
    fi

    # Check for various platform indicators
    if [ -d "$HOME/.claude" ] || [ -d ".claude" ]; then
        echo "claude"
    elif [ -d ".cursor" ] || [ -d "$HOME/.cursor" ]; then
        echo "cursor"
    elif [ -d ".github" ]; then
        echo "copilot"
    elif [ -d ".windsurf" ] || [ -d "$HOME/.windsurf" ]; then
        echo "windsurf"
    elif [ -f ".clinerules" ] || [ -d ".clinerules" ]; then
        echo "cline"
    elif [ -d "$HOME/.gemini" ]; then
        echo "gemini"
    elif [ -d ".kiro" ]; then
        echo "kiro"
    elif [ -d ".trae" ]; then
        echo "trae"
    elif [ -d ".roo" ]; then
        echo "roo"
    elif [ -d "$HOME/.config/goose" ]; then
        echo "goose"
    elif [ -d "$HOME/.agents" ]; then
        echo "universal"
    else
        echo "unknown"
    fi
}

# Get install path for platform
get_install_path() {
    local platform=$1
    local user_level=$2

    case "$platform" in
        claude)
            if [ "$user_level" = "true" ]; then
                echo "$HOME/.claude/skills/$SKILL_NAME"
            else
                echo ".claude/skills/$SKILL_NAME"
            fi
            ;;
        cursor)
            if [ "$user_level" = "true" ]; then
                echo "$HOME/.cursor/rules/$SKILL_NAME"
            else
                echo ".cursor/rules/$SKILL_NAME"
            fi
            ;;
        copilot)
            echo ".github/skills/$SKILL_NAME"
            ;;
        windsurf)
            if [ "$user_level" = "true" ]; then
                echo "$HOME/.windsurf/rules/$SKILL_NAME"
            else
                echo ".windsurf/rules/$SKILL_NAME"
            fi
            ;;
        cline)
            echo ".clinerules/$SKILL_NAME"
            ;;
        gemini)
            echo "$HOME/.gemini/skills/$SKILL_NAME"
            ;;
        kiro)
            echo ".kiro/skills/$SKILL_NAME"
            ;;
        trae)
            echo ".trae/rules/$SKILL_NAME"
            ;;
        roo)
            echo ".roo/rules/$SKILL_NAME"
            ;;
        goose)
            echo "$HOME/.config/goose/skills/$SKILL_NAME"
            ;;
        opencode)
            echo "$HOME/.config/opencode/skills/$SKILL_NAME"
            ;;
        universal)
            if [ "$user_level" = "true" ]; then
                echo "$HOME/.agents/skills/$SKILL_NAME"
            else
                echo ".agents/skills/$SKILL_NAME"
            fi
            ;;
        *)
            echo ""
            ;;
    esac
}

# Install the skill
install_skill() {
    local platform=$1
    local install_path=$2
    local dry_run=$3

    log_info "Installing $SKILL_NAME for $platform..."
    log_info "Target path: $install_path"

    if [ "$dry_run" = "true" ]; then
        log_info "[DRY RUN] Would copy files from $SCRIPT_DIR to $install_path"
        return 0
    fi

    # Create parent directory if needed
    mkdir -p "$(dirname "$install_path")"

    # Remove existing installation
    if [ -d "$install_path" ]; then
        log_warn "Removing existing installation at $install_path"
        rm -rf "$install_path"
    fi

    # Create target directory
    mkdir -p "$install_path"

    # Copy skill files (excluding install.sh and hidden files)
    for file in "$SCRIPT_DIR"/*; do
        if [ -f "$file" ]; then
            filename=$(basename "$file")
            if [ "$filename" != "install.sh" ]; then
                cp "$file" "$install_path/"
            fi
        elif [ -d "$file" ]; then
            dirname=$(basename "$file")
            if [ "$dirname" != ".git" ] && [ "$dirname" != "scripts" ]; then
                cp -R "$file" "$install_path/"
            fi
        fi
    done

    # Copy scripts directory if exists
    if [ -d "$SCRIPT_DIR/scripts" ]; then
        cp -R "$SCRIPT_DIR/scripts" "$install_path/"
    fi

    log_success "Installed to $install_path"
}

# Install to all detected platforms
install_all() {
    local dry_run=$1
    local installed=()

    log_info "Installing to all detected platforms..."

    for platform in claude cursor copilot windsurf cline gemini kiro trae roo goose opencode universal; do
        local path=$(get_install_path "$platform" "true")
        if [ -n "$path" ]; then
            # Check if platform directory exists
            local parent_dir=$(dirname "$path")
            if [ -d "$parent_dir" ]; then
                install_skill "$platform" "$path" "$dry_run"
                installed+=("$platform")
            fi
        fi
    done

    if [ ${#installed[@]} -eq 0 ]; then
        log_warn "No platforms detected. Install manually using --platform <name>"
        return 1
    fi

    log_success "Installed to ${#installed[@]} platform(s): ${installed[*]}"
}

# Print usage
print_usage() {
    cat << EOF
Usage: ./install.sh [OPTIONS]

Install film-location-scout skill to your AI coding assistant.

OPTIONS:
    -p, --platform <name>    Target platform (claude, cursor, copilot, windsurf, cline, etc.)
    -u, --user               Install to user-level config (default: project-level)
    -a, --all                Install to all detected platforms
    -d, --dry-run            Show what would be done without making changes
    -h, --help               Show this help message

PLATFORMS:
    claude       Claude Code (~/.claude/skills/)
    cursor       Cursor (.cursor/rules/)
    copilot      GitHub Copilot (.github/skills/)
    windsurf     Windsurf (.windsurf/rules/)
    cline        Cline (.clinerules/)
    gemini       Gemini CLI (~/.gemini/skills/)
    kiro         Kiro (.kiro/skills/)
    trae         Trae (.trae/rules/)
    roo          Roo Code (.roo/rules/)
    goose        Goose (~/.config/goose/skills/)
    opencode     OpenCode (~/.config/opencode/skills/)
    universal    Universal path (~/.agents/skills/)

EXAMPLES:
    ./install.sh                          # Auto-detect platform
    ./install.sh --platform claude        # Install for Claude Code
    ./install.sh --platform cursor --user # Install to user-level Cursor config
    ./install.sh --all                    # Install to all detected platforms
    ./install.sh --dry-run                # Preview changes

After installation, use the skill by typing:
    /film-location-scout
EOF
}

# Main
main() {
    local platform=""
    local user_level="false"
    local dry_run="false"
    local install_all_flag="false"

    # Parse arguments
    while [[ $# -gt 0 ]]; do
        case $1 in
            -p|--platform)
                platform="$2"
                shift 2
                ;;
            -u|--user)
                user_level="true"
                shift
                ;;
            -a|--all)
                install_all_flag="true"
                shift
                ;;
            -d|--dry-run)
                dry_run="true"
                shift
                ;;
            -h|--help)
                print_usage
                exit 0
                ;;
            *)
                log_error "Unknown option: $1"
                print_usage
                exit 1
                ;;
        esac
    done

    log_info "Film Location Scout Skill Installer"
    echo ""

    # Handle --all
    if [ "$install_all_flag" = "true" ]; then
        install_all "$dry_run"
        echo ""
        log_success "Installation complete!"
        echo ""
        echo "To use the skill, type:"
        echo "  /film-location-scout"
        exit 0
    fi

    # Auto-detect platform if not specified
    if [ -z "$platform" ]; then
        platform=$(detect_platform)
        if [ "$platform" = "unknown" ]; then
            log_error "Could not auto-detect platform. Please specify with --platform <name>"
            echo ""
            print_usage
            exit 1
        fi
        log_info "Auto-detected platform: $platform"
    fi

    # Get install path
    local install_path=$(get_install_path "$platform" "$user_level")
    if [ -z "$install_path" ]; then
        log_error "Unknown platform: $platform"
        exit 1
    fi

    # Install
    install_skill "$platform" "$install_path" "$dry_run"

    echo ""
    log_success "Installation complete!"
    echo ""
    echo "To use the skill, type:"
    echo "  /film-location-scout"
    echo ""
    echo "Examples:"
    echo "  /film-location-scout"
    echo "  /film-location-scout Find film locations in Paris"
    echo "  /film-location-scout 帮我找附近的电影取景地"
}

main "$@"


path: .skill-metadata.yaml
content: name: film-location-scout
version: 1.0.0
description:
  en: Discover nearby film and TV show shooting locations with cinematic scene recreation images
  zh: 发现附近的电影和电视剧取景地，生成电影场景重现图片
author: Qoder
license: MIT
tags:
  - film
  - location
  - photography
  - travel
  - cinema
  - movie
  - scene
  - tourism

examples:
  - id: nearby-locations
    title:
      en: Find nearby film locations
      zh: 查找附近的电影取景地
    description:
      en: Auto-detect location and find 5 nearby film shooting spots
      zh: 自动检测位置并查找5个附近的电影拍摄地点
    prompt:
      en: /film-location-scout
      zh: /film-location-scout

  - id: shanghai-film-spots
    title:
      en: Shanghai film locations
      zh: 上海电影取景地
    description:
      en: Discover movie shooting locations in Shanghai
      zh: 发现上海的影视拍摄地点
    prompt:
      en: /film-location-scout Find film locations in Shanghai
      zh: /film-location-scout 帮我找上海的电影取景地

  - id: photo-recreation
    title:
      en: Photo recreation guide
      zh: 照片重现指南
    description:
      en: Find locations for recreating iconic movie scenes
      zh: 寻找可以重现经典电影场景的拍摄地点
    prompt:
      en: /film-location-scout I want to recreate movie scenes, find me good spots
      zh: /film-location-scout 我想重现电影场景，推荐一些好地方

  - id: tokyo-cinematic
    title:
      en: Tokyo cinematic locations
      zh: 东京电影取景地
    description:
      en: Discover famous film locations in Tokyo for photography
      zh: 发现东京著名的电影拍摄地点用于摄影
    prompt:
      en: /film-location-scout Find cinematic spots in Tokyo for photography
      zh: /film-location-scout 推荐东京适合拍照的电影取景地

capabilities:
  - location_detection
  - web_search
  - image_generation
  - weather_query

required_tools:
  - WebFetch
  - WebSearch
  - ImageGen
  - AskUserQuestion

references:
  - scene-prompts.md
  - photo-params-reference.md


path: photo-params-reference.md
content: # Photography Parameters Reference

## Light Condition Matrix

### Golden Hour (sunrise/sunset, ~1hr window)
- **Characteristics**: Warm, directional, soft shadows, long golden tones
- **Aperture**: f/2.8 - f/5.6 (wide for bokeh portraits, mid for landscapes)
- **Shutter**: 1/200 - 1/500s (handheld safe)
- **ISO**: 100 - 400
- **White Balance**: 5500-6500K (preserve warmth)
- **Exposure Comp**: +0.3 to +0.7 EV (protect highlights in backlight)
- **Tips**: Shoot into the light for rim lighting; use lens flare creatively

### Blue Hour (20-40 min after sunset / before sunrise)
- **Characteristics**: Cool blue ambient, city lights emerging, dramatic sky
- **Aperture**: f/2.8 - f/4 (need light gathering)
- **Shutter**: 1/30 - 2s (tripod recommended for >1/60)
- **ISO**: 400 - 1600
- **White Balance**: 3500-4500K (enhance blue tones, or warm up for contrast)
- **Exposure Comp**: 0 to -0.3 EV
- **Tips**: Tripod essential; blend ambient and city lights; HDR bracket useful

### Bright Midday Sun (10am - 3pm, clear sky)
- **Characteristics**: Harsh overhead light, strong shadows, high contrast
- **Aperture**: f/8 - f/16 (deep DOF, reduce light)
- **Shutter**: 1/500 - 1/2000s
- **ISO**: 100 (base)
- **White Balance**: 5200-5500K (daylight neutral)
- **Exposure Comp**: -0.3 to -0.7 EV (protect highlights)
- **Tips**: Use shade/diffusers for portraits; polarizer filter reduces glare; look for interesting shadow patterns

### Overcast / Cloudy
- **Characteristics**: Soft diffused light, no harsh shadows, even exposure
- **Aperture**: f/2.8 - f/5.6 (can shoot wide, light is soft)
- **Shutter**: 1/125 - 1/500s
- **ISO**: 200 - 800
- **White Balance**: 6000-7000K (compensate for cool tones)
- **Exposure Comp**: +0.3 to +0.7 EV (clouds can fool meter)
- **Tips**: Great for portraits (natural softbox); colors are saturated; watch for flat landscapes

### Rainy / Wet Conditions
- **Characteristics**: Reflections, moody atmosphere, saturated colors on wet surfaces
- **Aperture**: f/2.8 - f/4 (gather light, isolate reflections)
- **Shutter**: 1/125 - 1/250s (freeze rain drops) or 1/15s (motion blur rain)
- **ISO**: 400 - 1600
- **White Balance**: 5500-6500K
- **Exposure Comp**: +0.3 EV (dark scenes fool meter)
- **Tips**: Protect gear; shoot reflections on wet streets; neon signs look amazing; umbrellas as props

### Foggy / Hazy
- **Characteristics**: Low contrast, ethereal mood, layered depth
- **Aperture**: f/4 - f/8
- **Shutter**: 1/60 - 1/250s
- **ISO**: 200 - 800
- **White Balance**: 5000-6000K (slightly warm to counteract grey)
- **Exposure Comp**: +0.7 to +1.0 EV (fog fools meter significantly)
- **Tips**: Use depth layers for composition; silhouettes work well; manual focus recommended

### Night / After Dark
- **Characteristics**: Artificial lighting, high contrast, neon and ambient light mix
- **Aperture**: f/1.4 - f/2.8 (maximum light gathering)
- **Shutter**: 1/30 - 1/125s (handheld) or 1-30s (tripod for light trails)
- **ISO**: 1600 - 6400 (handheld) or 100-400 (tripod)
- **White Balance**: 3000-4000K (tungsten) or auto (mixed lighting)
- **Exposure Comp**: -0.3 to -1.0 EV (preserve night mood, avoid overexposure)
- **Tips**: Tripod for sharp night shots; use leading lines from street lights; neon signs as backlight

### Snowy Conditions
- **Characteristics**: Extremely bright, high reflectivity, cool tones
- **Aperture**: f/8 - f/16
- **Shutter**: 1/250 - 1/1000s
- **ISO**: 100 - 200
- **White Balance**: 6500-8000K (warm up snow, prevent blue cast)
- **Exposure Comp**: +1.0 to +1.7 EV (critical - snow fools meter badly)
- **Tips**: Overexpose to keep snow white; use spot metering on subject; protect gear from moisture

## Phone Photography Quick Settings

| Condition | Phone Mode | Key Tips |
|-----------|-----------|----------|
| Golden Hour | Portrait / Pro mode | Tap to expose for sky, reduce exposure slightly |
| Blue Hour | Night mode / Pro | Lean against wall for stability, avoid digital zoom |
| Midday | HDR on | Find shade for portraits, use 0.5x wide for architecture |
| Overcast | Portrait mode | Great natural light, no adjustments needed |
| Rainy | Pro mode | Tap wet reflections to focus, wipe lens frequently |
| Night | Night mode | Hold very still 3-5s, use timer to avoid shake |

## Film-Specific Composition Tips

When recreating a film scene:
1. **Match the focal length**: Wide shots (~24mm) for establishing, 50mm for dialogue, 85mm+ for close-ups
2. **Match the aspect ratio**: Crop to cinemascope (2.39:1) for epic, 16:9 for TV, 4:3 for indie/vintage
3. **Match the color tone**: Consider the film's color grading (warm/cool/desaturated)
4. **Consider the era**: Older films may have grain - embrace it or add it in post
5. **Reference the actual frame**: Search for the exact frame online before shooting


path: README.md
content: # Film Location Scout Skill

Discover nearby film and TV show shooting locations with cinematic scene recreation images. Perfect for photo recreation, film tourism, and cinematic photography.

## Features

- **Auto Location Detection**: Detects your city via IP geolocation
- **5 Curated Locations**: Finds 5 film/TV shooting spots within 5km of your position
- **Cinematic Scene Images**: AI-generated movie stills with 1-2 prominent characters for photo reference
- **Precise Coordinates**: GPS coordinates with 6 decimal places accuracy
- **Photography Parameters**: Weather-based camera settings (aperture, shutter, ISO, etc.)
- **Composition Tips**: Film-accurate framing advice for each location

## Installation

### Quick Install (Auto-detect)

```bash
./install.sh
```

### Install for Specific Platform

```bash
# Claude Code
./install.sh --platform claude

# Cursor (project-level)
./install.sh --platform cursor

# Cursor (user-level)
./install.sh --platform cursor --user

# GitHub Copilot
./install.sh --platform copilot

# Windsurf
./install.sh --platform windsurf

# All detected platforms
./install.sh --all
```

### Manual Install

```bash
# Clone to your platform's skill directory

# Claude Code
git clone <repo-url> ~/.claude/skills/film-location-scout

# Cursor
git clone <repo-url> .cursor/rules/film-location-scout

# GitHub Copilot
git clone <repo-url> .github/skills/film-location-scout

# Universal (works with most platforms)
git clone <repo-url> ~/.agents/skills/film-location-scout
```

## Usage

Once installed, invoke the skill with:

```
/film-location-scout
```

Or naturally:

```
帮我找附近的电影取景地
推荐一些可以拍照的电影场景地点
附近有什么电影拍摄地
film locations near me
movie shooting spots nearby
```

### Examples

**Basic search:**
```
/film-location-scout
```

**With specific city:**
```
/film-location-scout Find film locations in Paris
```

**Photo recreation focus:**
```
/film-location-scout I want to recreate movie scenes in Tokyo
```

## How It Works

The skill follows a 4-step workflow:

1. **Location Detection**: Auto-detects your city via IP, confirms with you
2. **Weather Fetch**: Gets current weather and light conditions
3. **Location Search**: Finds 5 filming locations within 5km radius
4. **Case Generation**: For each location, generates:
   - Precise location info (address, coordinates, map link)
   - Film scene description (plot, camera angles, timestamps)
   - Photography parameters (tailored to weather and location)
   - Cinematic scene image (with 1-2 prominent characters for photo reference)

## Output Format

Each of the 5 cases includes:

### Film Info
- Title, director, genre, year
- Detailed scene description (3-5 sentences)
- Camera angles, framing, movement
- Timestamp/episode reference

### Location
- Name (Chinese + English)
- Full street address with district
- Precise coordinates (6 decimal places)
- Distance from your position
- Google Maps link

### Photography Settings
| Parameter | Example | Purpose |
|-----------|---------|---------|
| Aperture | f/2.8 - f/16 | Depth of field control |
| Shutter | 1/60s - 1/1000s | Motion freeze/blur |
| ISO | 100 - 6400 | Light sensitivity |
| White Balance | 3000K - 7000K | Color temperature |
| Exposure Comp | -1.0 to +1.7 EV | Exposure adjustment |
| Focal Length | 24mm - 85mm | Field of view |

Plus composition tips and phone photography advice.

### Scene Image
AI-generated cinematic still featuring:
- 1-2 prominent characters in foreground (for photo recreation reference)
- Real landmark/venue as recognizable background
- Film-accurate color grading and lighting
- Photorealistic movie still aesthetic

## Project Structure

```
film-location-scout/
├── SKILL.md                    # Main skill definition
├── README.md                   # This file
├── install.sh                  # Cross-platform installer
├── .skill-metadata.yaml        # Skill metadata
├── scene-prompts.md            # Image generation prompt templates
├── photo-params-reference.md   # Photography parameter matrix
├── assets/                     # Static assets
└── scripts/                    # Utility scripts
    └── distance_calc.py        # Haversine distance calculator
```

## Reference Files

### scene-prompts.md
Detailed templates for generating cinematic scene images:
- Character prominence guidelines (20-40% of frame)
- Lighting descriptions for different weather conditions
- Color grading for various film styles
- Camera angle and lens recommendations
- Scene type templates (urban, waterfront, historic, park, interior)

### photo-params-reference.md
Photography parameter matrix:
- Light condition settings (golden hour, blue hour, midday, overcast, rainy, foggy, night, snow)
- Phone photography quick settings
- Film-specific composition tips

## Configuration

No configuration required. The skill auto-detects:
- Your location via IP geolocation
- Current weather conditions
- Local time for light calculations

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Wrong city detected | Manually provide your location when prompted |
| < 5 locations found | Search radius auto-expands to 10km |
| Image generation fails | Scene described in text instead |
| Coordinates seem wrong | Verify with Google Maps link provided |
| Weather unavailable | Uses general outdoor photography parameters |

## Requirements

- Internet connection (for location, weather, and image generation)
- Image generation capability
- Web search capability

## Use Cases

### Photo Recreation
Stand where the character is positioned in the generated image. Frame yourself similarly with the landmark visible in the background for the perfect recreation shot.

### Film Tourism
Discover filming locations while traveling to new cities. Visit iconic movie spots and learn the behind-the-scenes stories.

### Cinematic Photography
Learn professional camera settings tailored to each location's lighting conditions and the original film's visual style.

### Scene Pilgrimage
Explore famous movie spots in your own city. See your hometown through the lens of cinema.

## Limitations

- Requires locations to be within database/knowledge coverage
- Image generation depends on AI capabilities and may not perfectly match the film
- Weather data reflects current conditions, not when the scene was originally filmed
- Coordinates accuracy depends on available data sources
- Some locations may be private property or have access restrictions

## Dependencies

- IP geolocation service (ipinfo.io)
- Web search for location and weather data
- Image generation capability
- Real-time weather information sources

## License

MIT License

## Contributing

Contributions welcome! Please ensure:
- Code follows existing style
- All scripts have proper error handling
- New features include documentation updates
- Test on multiple platforms before submitting

## Credits

- Film locations data sourced from public filming location databases
- Photography parameters based on professional cinematography guides
- Scene recreation inspired by film tourism community practices


path: scripts/distance_calc.py
content: #!/usr/bin/env python3
"""
Distance calculation utilities for film-location-scout skill.
Uses Haversine formula to calculate distances between GPS coordinates.
"""

import math
from typing import Tuple, List, Dict


def haversine_distance(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
    """
    Calculate the great circle distance between two points on Earth.

    Args:
        lat1: Latitude of point 1 in decimal degrees
        lon1: Longitude of point 1 in decimal degrees
        lat2: Latitude of point 2 in decimal degrees
        lon2: Longitude of point 2 in decimal degrees

    Returns:
        Distance in meters
    """
    # Convert decimal degrees to radians
    lat1, lon1, lat2, lon2 = map(math.radians, [lat1, lon1, lat2, lon2])

    # Haversine formula
    dlat = lat2 - lat1
    dlon = lon2 - lon1
    a = math.sin(dlat/2)**2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon/2)**2
    c = 2 * math.asin(math.sqrt(a))

    # Radius of Earth in meters
    r = 6371000

    return c * r


def format_distance(distance_meters: float) -> str:
    """
    Format distance for display.

    Args:
        distance_meters: Distance in meters

    Returns:
        Formatted string (e.g., "450m" or "1.2km")
    """
    if distance_meters < 1000:
        return f"{int(distance_meters)}m"
    else:
        return f"{distance_meters/1000:.1f}km"


def filter_locations_by_distance(
    user_lat: float,
    user_lon: float,
    locations: List[Dict],
    max_distance_km: float = 5.0
) -> List[Dict]:
    """
    Filter locations by distance from user position.

    Args:
        user_lat: User latitude
        user_lon: User longitude
        locations: List of location dicts with 'lat' and 'lon' keys
        max_distance_km: Maximum distance in kilometers

    Returns:
        List of locations within max_distance_km, sorted by distance
    """
    max_distance_m = max_distance_km * 1000

    locations_with_distance = []
    for loc in locations:
        distance = haversine_distance(
            user_lat, user_lon,
            loc['lat'], loc['lon']
        )
        if distance <= max_distance_m:
            loc_copy = loc.copy()
            loc_copy['distance_m'] = distance
            loc_copy['distance_formatted'] = format_distance(distance)
            locations_with_distance.append(loc_copy)

    # Sort by distance
    locations_with_distance.sort(key=lambda x: x['distance_m'])

    return locations_with_distance


def calculate_bounding_box(
    lat: float,
    lon: float,
    radius_km: float
) -> Tuple[float, float, float, float]:
    """
    Calculate bounding box for a given point and radius.

    Args:
        lat: Center latitude
        lon: Center longitude
        radius_km: Radius in kilometers

    Returns:
        Tuple of (min_lat, max_lat, min_lon, max_lon)
    """
    # Approximate degrees per km
    lat_degree_per_km = 1 / 111.32
    lon_degree_per_km = 1 / (111.32 * math.cos(math.radians(lat)))

    lat_delta = radius_km * lat_degree_per_km
    lon_delta = radius_km * lon_degree_per_km

    return (
        lat - lat_delta,  # min_lat
        lat + lat_delta,  # max_lat
        lon - lon_delta,  # min_lon
        lon + lon_delta   # max_lon
    )


def main():
    """CLI for testing distance calculations."""
    import sys

    if len(sys.argv) < 5:
        print("Usage: python3 distance_calc.py <lat1> <lon1> <lat2> <lon2>")
        print("Example: python3 distance_calc.py 31.2304 121.4737 31.2397 121.4997")
        sys.exit(1)

    lat1 = float(sys.argv[1])
    lon1 = float(sys.argv[2])
    lat2 = float(sys.argv[3])
    lon2 = float(sys.argv[4])

    distance = haversine_distance(lat1, lon1, lat2, lon2)
    print(f"Distance: {format_distance(distance)}")
    print(f"Exact: {distance:.2f} meters")


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)