Travel Itinerary Builder

Comprehensive travel itinerary generator that creates detailed, multi-day trip plans with automatic weather forecasts, points of interest, restaurant recomme...

Security Scan

The skill's code, declared dependencies, and runtime instructions are coherent with its stated purpose (it parses Gmail for bookings, fetches places and weather, and generates itineraries); optional credentials and external CLIs are used for the expected features.

Purpose & Capability

Name/description match the implementation: scripts implement itinerary generation, Gmail parsing, places lookup, and weather fetching. Required and optional tools (curl, gog, goplaces) and optional env vars (GOG_KEYRING_PASSWORD, GOOGLE_PLACES_API_KEY) align with the described features.

Instruction Scope

SKILL.md instructs the agent to run the provided scripts and documents what data will be accessed. The gmail_parser script explicitly calls the gog CLI to read Gmail and writes extracted bookings to local JSON files; places_fetcher and weather_fetcher call goplaces/Google Places and wttr.in respectively. The instructions do not request unrelated files, credentials, or system paths.

Install Mechanism

Install spec uses brew formulas (gogcli and steipete/tap/goplaces) and creates binaries 'gog' and 'goplaces'. These are optional installs referenced in SKILL.md. Brew formulas are a reasonable install mechanism, but they rely on third-party taps/formula names that should be reviewed by the user before installing.

Credentials

No required environment variables; two optional env vars (GOG_KEYRING_PASSWORD and GOOGLE_PLACES_API_KEY) are proportionate and directly support Gmail OAuth and Google Places usage. The scripts read only those env vars and do not request unrelated credentials.

Persistence & Privilege

Skill does not request always:true or other elevated persistence. It runs as user-invoked/optional; it does not modify other skills or agent-wide settings.

Assessment

This skill appears to do what it says, but it interacts with external services and CLIs so take these precautions before installing: (1) Review the brew formulas 'gogcli' and 'steipete/tap/goplaces' to ensure they come from trusted sources; (2) Only provide GOG_KEYRING_PASSWORD or a GOOGLE_PLACES_API_KEY if you trust the CLIs—Gmail parsing reads email content and stores extracted bookings locally as JSON; (3) Network calls are expected (wttr.in for weather, Google Places or goplaces for POIs, gog CLI for Gmail); consider running the skill inside a container/VM if you want to isolate it; (4) After use, revoke any OAuth tokens/credentials you supplied if you no longer need them; (5) If you require higher assurance, inspect the included scripts (gmail_parser.py, places_fetcher.py, weather_fetcher.py, generate_itinerary.py) yourself or run them in a sandboxed environment.

Generate comprehensive, print-ready travel itineraries with automatic integration of weather, places, dining, transportation, and budget planning.

⚠️ Security & Privacy Notice

This skill accesses sensitive data and requires external credentials:

Gmail Access (Optional)

• The gmail_parser.py script reads your Gmail messages to extract booking confirmations
• Requires GOG_KEYRING_PASSWORD environment variable (for GOG CLI authentication)
• What it accesses: Email subjects, snippets, and full message bodies matching search queries
• What it extracts: Flight details (PNR, times), hotel bookings, car rentals, activity tickets
• Data handling: Extracted data is stored locally in JSON files; no external transmission

Google Places API (Optional)

• The places_fetcher.py script queries Google Places for attractions
• Requires GOOGLE_PLACES_API_KEY environment variable (free tier: 1000 requests/month)
• Fallback to built-in database if API key not provided

External CLI Dependencies

• gog (Google OAuth CLI): Authenticates Gmail access via OAuth2
• goplaces: Queries Google Places API
• curl: Fetches weather data from wttr.in

Before installing:

1. Review all scripts in scripts/ directory
2. Only provide credentials if you trust the external CLIs
3. Consider running in an isolated environment (container/VM)
4. Gmail integration is optional — you can use the skill without it

Quick Start

Basic Usage

# Generate itinerary from user input
python3 scripts/generate_itinerary.py \
  --destination "Tokyo, Osaka, Kyoto" \
  --start-date "2026-03-06" \
  --end-date "2026-03-15" \
  --language zh \
  --output ./japan_trip.html

With Gmail Integration

# Extract bookings from Gmail and generate itinerary
python3 scripts/gmail_parser.py \
  --account [e-mail] \
  --after "2026-03-01" \
  --output ./bookings.json

python3 scripts/generate_itinerary.py \
  --bookings ./bookings.json \
  --destination "Tokyo, Osaka" \
  --start-date "2026-03-06" \
  --end-date "2026-03-15" \
  --output ./trip.html

Core Features

1. Automatic Data Collection

• Weather forecasts: Integrates with weather skill for daily forecasts
• Points of interest: Uses goplaces skill for attractions, restaurants, landmarks
• Multi-language names: Shows place names in user language + local language
• Gmail parsing: Extracts flight, hotel, car rental bookings from confirmation emails

2. Intelligent Planning

• Daily schedules: Auto-generates time-based itineraries (08:00 departure → 10:00 attraction → 12:00 lunch)
• Transportation routing: Calculates distances, travel times, and costs for driving/transit
• Budget estimation: Computes total costs for accommodation, meals, transport, tickets
• Packing lists: Generates climate-appropriate packing suggestions

3. Output Formats

• HTML: Beautiful dark-themed, print-ready documents (based on proven template)
• Markdown: Editable plain-text format
• JSON: Structured data for further processing
• PDF: Optional export via HTML → PDF conversion

Workflow

Step 1: Gather Information

Ask user for:

• Destinations (cities/regions)
• Travel dates (start and end)
• Budget range (optional)
• Interests/tags (history, nature, food, shopping, concerts)
• Language preference (zh, en, ja, ko)
• Special requirements (dietary, accessibility, child-friendly)

Step 2: Extract Existing Bookings (Optional)

If user has Gmail access configured:

python3 scripts/gmail_parser.py \
  --account <email> \
  --after <YYYY-MM-DD> \
  --keywords "flight,hotel,booking,reservation,confirmation" \
  --output bookings.json

This extracts:

• ✈️ Flights: airline, flight number, departure/arrival times, PNR
• 🏨 Hotels: name, address, check-in/out dates, booking number, price
• 🚗 Car rentals: company, car type, pickup/return times, booking number
• 🎫 Tickets: concerts, museums, activities with times and seat info

Supported platforms: Agoda, Booking.com, Singapore Airlines, ANA, Trip.com, Klook, KKday

Step 3: Query Weather and Places

# Weather forecasts for each destination
python3 scripts/weather_fetcher.py \
  --destinations "Tokyo,Osaka,Kyoto" \
  --start-date "2026-03-06" \
  --end-date "2026-03-15" \
  --output weather.json

# Points of interest
python3 scripts/places_fetcher.py \
  --destinations "Tokyo,Osaka,Kyoto" \
  --interests "temples,food,shopping" \
  --language zh \
  --output places.json

Step 4: Generate Itinerary

python3 scripts/generate_itinerary.py \
  --bookings bookings.json \
  --weather weather.json \
  --places places.json \
  --start-date "2026-03-06" \
  --end-date "2026-03-15" \
  --budget 2000 \
  --currency SGD \
  --language zh \
  --output japan_trip.html

Step 5: Export (Optional)

# Export to PDF
python3 scripts/export_pdf.py japan_trip.html japan_trip.pdf

# Sync to Notion (if configured)
python3 scripts/sync_notion.py japan_trip.json

Scripts Reference

generate_itinerary.py

Core generator. Combines all data sources into a complete itinerary.

Arguments:

• --destination: Comma-separated list of cities/regions
• --start-date: Trip start date (YYYY-MM-DD)
• --end-date: Trip end date (YYYY-MM-DD)
• --bookings: Path to bookings JSON (from gmail_parser.py)
• --weather: Path to weather JSON (from weather_fetcher.py)
• --places: Path to places JSON (from places_fetcher.py)
• --budget: Total budget amount (optional)
• --currency: Currency code (SGD, USD, JPY, etc.)
• --language: Output language (zh, en, ja, ko)
• --interests: Comma-separated tags (history, nature, food, shopping, concerts)
• --output: Output file path (.html, .md, or .json)

gmail_parser.py

Extracts travel bookings from Gmail using GOG skill.

Requirements: GOG_KEYRING_PASSWORD environment variable

Arguments:

• --account: Gmail account email
• --after: Start date for email search (YYYY-MM-DD)
• --keywords: Search keywords (default: "flight,hotel,booking,confirmation")
• --output: Output JSON file

weather_fetcher.py

Fetches weather forecasts for destinations using weather skill.

Arguments:

• --destinations: Comma-separated cities
• --start-date: Forecast start date
• --end-date: Forecast end date
• --output: Output JSON file

places_fetcher.py

Queries points of interest using goplaces skill.

Arguments:

• --destinations: Comma-separated cities
• --interests: Activity tags (temples, museums, food, shopping)
• --language: Display language
• --output: Output JSON file

translator.py

Translates place names to multiple languages.

Arguments:

• --text: Text to translate
• --source-lang: Source language code
• --target-langs: Comma-separated target language codes
• --output: Output JSON file

budget_calculator.py

Estimates trip costs based on destination, duration, and bookings.

Arguments:

• --destination: Primary destination
• --days: Number of days
• --bookings: Path to bookings JSON
• --category: Budget category (budget, mid-range, luxury)
• --output: Output JSON file

export_html.py

Converts itinerary JSON to styled HTML using template.

Arguments:

• --input: Itinerary JSON file
• --template: HTML template (default: assets/itinerary_template.html)
• --output: Output HTML file

References

• destination_templates.md: Pre-built templates for popular destinations (Tokyo, Seoul, Paris, etc.)
• travel_tips.md: Climate guides, packing lists, visa requirements, cultural tips
• email_patterns.md: Email parsing rules for different booking platforms
• poi_database.md: Common attractions with multi-language names

Assets

• itinerary_template.html: Dark-themed HTML template with CSS styling
• icons/: SVG icons for flights, hotels, restaurants, attractions
• fonts/: Web fonts for print-quality output

Multi-Language Support

Place names are displayed in user language + local language:

东京塔 (東京タワー / Tokyo Tower)
和歌山城 (和歌山城 / Wakayama Castle)

Supported languages: Chinese (zh), English (en), Japanese (ja), Korean (ko)

Output Example

Generated HTML includes:

• 📅 Day-by-day timeline with emoji icons
• 🌤️ Daily weather forecasts
• ✈️ Flight details with boarding times
• 🏨 Hotel information with check-in/out
• 🚗 Driving routes with distances and tolls
• 🍽️ Restaurant recommendations with local specialties
• 💰 Budget breakdown by category
• 📋 Packing checklist based on climate
• ⚠️ Important reminders (visa, insurance, IDP)

Integration with Other Skills

This skill calls:

• weather — Daily forecasts
• goplaces — Attraction and restaurant search
• gog — Gmail parsing (optional, requires GOG_KEYRING_PASSWORD)
• notion — Sync to Notion database (optional, requires Notion API key)

Tips

• For self-driving trips: Include rental car details, calculate fuel costs, note toll roads
• For concert/event trips: Add venue info, seating, merchandise shop times
• For multi-city trips: Calculate transit times between cities
• For international trips: Include visa requirements, vaccination, travel insurance reminders

Troubleshooting

• Gmail parsing fails: Check GOG_KEYRING_PASSWORD is set and account has access
• Weather data missing: Ensure dates are within forecast range (usually 10 days)
• Places not found: Try broader search terms or check goplaces API key
• HTML rendering issues: Open in modern browser (Chrome, Firefox, Safari)

Future Enhancements

• Real-time flight status updates
• Amadeus API integration for flight price tracking
• Google Sheets export for budget tracking
• PDF generation without external tools
• Mobile-responsive HTML output