Find cheaper flight routes using hidden-city arbitrage and hub transfer combinations. Activates when users search for flights, find cheap flights, compare routes, or look for budget travel deals. Supports 70+ global hubs, multi-date scanning, SQLite caching, and self-transfer detection. No API keys required.
Find cheaper flight routes using hidden-city arbitrage and hub transfer combinations. Activates when users search for flights, find cheap flights, compare routes, or look for budget travel deals. Supports 70+ global hubs, multi-date scanning, SQLite caching, and self-transfer detection. No API keys required.
[{"name":"VENV_PATH","prompt":"Python venv path for flight-search","help":"Defaults to ~/.hermes/venvs/flight-search. Only change if custom path needed.","required_for":"all operations"}]
Flight Search Skill
When to Use
User asks to search for flights, find cheap flights, or compare flight routes
User wants to find the cheapest way to fly between two cities
User mentions "hidden city", "self transfer", "transfer flights", or "hub hopping"
User asks about budget travel or arbitrage opportunities in airfares
User wants multi-date flight searches or flexible date options
User wants to search flights from multiple nearby airports simultaneously
Procedure
Step 1 — Set Up the Python Environment
Create an isolated venv (required due to PEP 668 dependency conflicts):
✅ Success: valid JSON array, prices are numeric, no ValueError or ModuleNotFoundError in stderr.
❌ Rate-limited: all prices show $N/A — retry with --no-cache.
❌ Import error: venv Python not being used — confirm path starts with ~/.hermes/venvs/.
Examples
Example 1: Single date, direct route
Input: "Find flights from LAX to HKG on May 20th"
Run: flight-search LAX HKG -d 2026-05-20
Present: top 3 results as a markdown table with price, duration, stops
Example 2: Cheaper route via transfer
Input: "Find the cheapest way to fly from SFO to HKG, I don't mind a layover"
Run: python3 ~/.hermes/scripts/flight-transfer-finder.py -o SFO -d HKG -dt 2026-06-15 --flexible 3
Present: sorted table, highlight best transfer with savings vs direct
Example 3: Multi-origin power search
Input: "Compare flights from SFO, LAX, and OAK to Bangkok for mid-June"
Run: python3 ~/.hermes/scripts/flight-transfer-finder.py -o SFO,LAX,OAK -d BKK -dt 2026-06-15 --flexible 5
Present: all origins aggregated and ranked by price
Example 4: Rule verification (v5+)
Input: "Verify the self-transfer rules for the best LAX to HKG deal on June 15"
Run: python3 ~/.hermes/scripts/flight-transfer-finder.py -o LAX -d HKG -dt 2026-06-15 --verify-rules
Checks: 3h+ buffer between legs, carry-on only advisory, transit visa requirements for the hub.
Example 5: CSV export (v5+)
Input: "Export the LAX to HKG results to a CSV file"
Run: python3 ~/.hermes/scripts/flight-transfer-finder.py -o LAX -d HKG -dt 2026-06-15 --export-csv --csv-output ~/flight-deals.csv
Example 6: Notion export (v5+)
Input: "Add my flight deals to Notion"
Run: python3 ~/.hermes/scripts/flight-transfer-finder.py -o LAX -d HKG -dt 2026-06-15 \
--export-notion --notion-database <your-db-id> --notion-api-key <your-token>
# Or set env vars: NOTION_FLIGHT_DEALS_DB_ID and NOTION_API_KEY
Example 7: Price alert (v5+)
Input: "Alert me if any LAX to HKG deal drops below $600 in the next 7 days"
Run: python3 ~/.hermes/scripts/flight-transfer-finder.py -o LAX -d HKG -dt 2026-06-15 \
--flexible 7 --alert-below 600
Prints a 🔔 ALERT line when the best available transfer is below your threshold.
Pitfalls
Wrong field names crash get_flights(): Use from_airport/to_airport, NOT origin/destination
System Python vs venv Python: Always call from the venv Python — system Python has httpx version mismatch
16+ threads triggers Google rate-limiting: Use 8 threads max; per-route semaphore prevents thundering herd
Empty price strings crash min(): Validate price is numeric before int() conversion
Self-transfer requires two separate bookings: Non-refundable if one leg cancels; do not use for tight connections
3-hour minimum connection time for self-transfer: Less time risks missed connections due to delays or terminal transfers
