flight-search-skill

✈️ Flight Search Skill

Google Flights script-first • VPS-friendly • made for repeatable price scans

A practical flight search workflow for AI agents.

Built so you can ask for “cheapest options in this date window” and get consistent results fast.

✨ What this skill does

• Scans a date range for the cheapest route combinations
• Supports fixed trip length (example: always 7 nights)
• Filters by cabin and max stops
• Optionally enforces “must include two weekends”
• Returns ranked, easy-to-read options

✅ Easiest way to use it (assistant mode)

If you use an assistant like me, you usually just ask in plain English:

• “Find me cheapest flights from VIE to PMI in September for 9 nights, max 1 stop.”
• “Give me top 10 options in EUR.”
• “Only options that include two weekends.”

You don’t need to run commands yourself.

🖥️ Why this works well on VPS

This process is script-first (not browser-click-first), which is usually more reliable on VPS/cloud machines where web pages and sessions can be flaky.

🧠 How the process works

1. Run scripts/google-flights-search.py
2. Query Google Flights via the fli package
3. Apply filters (nights, stops, cabin, date window)
4. Rank by cheapest price
5. Return shortlist

Link behavior:

• If results are 5 or fewer, include direct booking/search links per option.
• If results are more than 5, suppress links by default and mention they are available on request.

Default policy: no automatic fallback engine unless you explicitly ask.

📦 Repo contents

• SKILL.md → agent instructions
• scripts/google-flights-search.py → flight scan engine
• references/commands.md → copy/paste command cookbook
• references/response-template.md → output format
• references/fallback-policy.md → fallback behavior

⚡ Manual mode (optional, for power users)

PIP_BREAK_SYSTEM_PACKAGES=1 python3 -m pip install --user flights

cd ~/publish/flight-search-skill

python3 scripts/google-flights-search.py \
  --origin VIE --destination PMI \
  --start 2026-09-01 --end 2026-09-30 \
  --nights 9 --top 10 --adults 1 \
  --cabin economy --max-stops 1 --currency EUR \
  --json-out /tmp/flight-search.json --csv-out /tmp/flight-search.csv

python3 scripts/google-flights-search.py \
  --origin VIE --destination PMI \
  --start 2026-09-01 --end 2026-09-30 \
  --nights 9 --top 10 --adults 1 \
  --cabin economy --max-stops 1 --currency EUR \
  --require-two-weekends

💡 Troubleshooting

• No results found

  • Broaden date window
  • Increase max stops
  • Relax cabin
  • Remove two-weekend requirement

• Unknown IATA code

  • Use 3-letter airport codes (e.g., VIE, PMI, LHR)

• Dependency errors

  • Re-run install command for flights

🚫 Intentionally not included

• Browser-clicking workflow as primary path
• Automatic provider fallback without user approval

If you’re non-technical: use assistant mode and just ask in normal language.