For People Who Fly Often
Set It Once
Fly It Every Time
Save the preferences and routes you use most. Every search ranks real flights against what matters for this trip, including the airport rides you actually need.
Every booking starts from scratch, and getting to or from the airport still gets treated as a separate problem.
The external problem
You’re comparing flights across five browser tabs, re-answering the same budget and airline questions you answered last trip, and sorting out rides to or from the airport after you’ve picked a flight.
The internal problem
The tedium of repeating answers you already know, plus the specific annoyance of discovering a flight only works if you accept a bad connection on the ground.
What's at stake
Money left on the table from a flight you didn’t compare closely enough, and a fragile airport connection that turns one delay into a missed flight or hours of waiting.
From a trip request to a plan that accounts for the whole journey.
Confirm a route, preferences, and airport rides for this trip. The scripts fetch the options, then make the filtering, ranking, and shuttle math reproducible.
Resolve the Trip
Say where and when. A saved trip preset skips repeated airport research; otherwise the skill resolves realistic nearby alternates and asks you to confirm the plan.
Confirm What Matters
Confirm saved budget, airline, nonstop, time, and duration preferences, plus whether you need a ride to the airport, from it, both, or neither this time.
Fetch & Evaluate
Pulls every approved route and date through Google Flights data, then applies the common filters or a purpose-built rule for the constraint you actually care about.
Rank the Full Route
Returns a ranked flight list with each soft tradeoff shown in dollars, then pairs only the configured shuttle directions you confirmed and shows total cost and buffer time.
Reference library: Preferences, repeat routes, and shuttle logic are all explicit.
Every ranking starts with a config file: hard or soft preferences, repeat-trip aliases, maximum duration, and per-direction shuttle details. The model can explain the tradeoffs, but it does not eyeball the search, timing, or ranking math.
Supporting reference files follow the practical guide. Archived source material and author workflow notes are not a current policy certification.
01 Preferences & PresetsEvery config field, including hard and soft preferences, repeat-trip aliases, and duration limits.
Reference
Preferences & Presets
Full schema
{
"serpapi_key": "abc123 or null",
"budget_usd": 200,
"budget_strength": "soft",
"airline_preferences": ["UA", "DL"],
"airline_preference_strength": "soft",
"nonstop_preference": "preferred",
"nonstop_strength": "soft",
"time_priority_bands": ["11:00-14:00", "14:00-22:00"],
"time_priority_strength": "soft",
"max_duration_min": null,
"max_duration_strength": "soft",
"home_airport": null,
"frequent_destinations": [],
"trip_presets": {},
"shuttle_service": null
}Field reference
serpapi_key
- Type: string or null
- SerpAPI key for Google Flights queries. If null, the skill falls back to WebSearch (less comprehensive — see SKILL.md).
- Get one at https://serpapi.com/manage-api-key.
budget_usd
- Type: int — max flight price in USD.
budget_strength
- Type:
"hard"or"soft" hard= filter out flights above budget.soft= include them but rank cheaper ones higher.
airline_preferences
- Type: array of IATA airline codes (e.g.
["UA", "DL"]). Empty array = any airline. - A connecting itinerary counts as matching only if every leg is on a preferred airline.
airline_preference_strength
- Type:
"hard"or"soft"
nonstop_preference
- Type:
"required","preferred", or"no_preference"
nonstop_strength
- Type:
"hard"or"soft"
- required + hard = filter out anything with stops
- required + soft = treat stopovers as a downside but still show them
- preferred + soft = rank nonstops first, show stops second (typical setup)
- no_preference = strength is ignored
time_priority_bands
- Type: array of
"HH:MM-HH:MM"ranges in 24-hour time. - Departures inside the first band rank highest; second band second; outside all bands lowest.
time_priority_strength
- Type:
"hard"or"soft"
max_duration_min
- Type: int or null — cap on total itinerary minutes (gate + gate, layovers included).
- Useful when
nonstop_preferenceissoft: it lets one-stops through without letting a 14-hour triple-connection through with them.
max_duration_strength
- Type:
"hard"or"soft"
home_airport
- Type: IATA code or null. Suggested as the origin in Phase 1 (but the skill still asks).
frequent_destinations
- Type: array of IATA codes. Surfaced as suggestions when asking for a destination.
trip_presets
- Type: object mapping a short slug to a saved route. This is the fast path — when the user names a preset (or says something that clearly matches its
aliases), the skill skips airport research entirely and goes straight to confirming dates.
"trip_presets": {
"home-to-school": {
"label": "NJ -> Purdue",
"aliases": ["to school", "back to campus", "nj to purdue"],
"origins": ["EWR", "LGA", "JFK"],
"destinations": ["IND", "ORD"],
"shuttle_legs": "arrival",
"notes": "IND drops me 1h from campus; ORD is 2.5h but usually cheaper."
},
"school-to-home": {
"label": "Purdue -> NJ",
"aliases": ["home", "back to nj", "purdue to nj"],
"origins": ["IND", "ORD"],
"destinations": ["EWR", "LGA", "JFK"],
"shuttle_legs": "departure"
}
}Per-preset fields, all optional except origins/destinations:
| Field | Purpose |
|---|---|
label | Human-readable direction, shown when confirming |
aliases | Phrases that should match this preset in Phase 1 |
origins / destinations | IATA lists passed straight to --routes / --from / --to |
routes | Optional explicit ["EWR-IND", "EWR-ORD"] list, when the full cross-product isn't wanted |
shuttle_legs | Which end of *this* direction normally needs a ride: "departure", "arrival", "both", or "none". See below. |
notes | Free text shown to the user during confirmation |
| Any preference key | Per-preset override of a top-level preference (e.g. a higher budget_usd for a long route) |
shuttle_legs — a default, never an assumption
A configured shuttle does not mean a needed shuttle. Someone flying out of a hub near where they live needs no ride on the home end, and someone who normally rides might be getting dropped off, driving, or stopping somewhere on the way this time.
shuttle_legs records which end of a given direction *usually* needs one, so the skill proposes the right thing instead of pairing a shuttle to an airport where the user has a car. It maps to pair_shuttles.py --legs:
| Value | Meaning | --legs |
|---|---|---|
"departure" | Ride from home to the departure airport | pre |
"arrival" | Land, then ride to the destination | post |
"both" | Ride on both ends | both |
"none" | No ground shuttle for this direction; skip pairing entirely | (skip) |
Note that it's direction-specific and usually asymmetric. The same person flying NJ → Purdue needs a ride only on arrival; flying Purdue → NJ they need one only on departure. Two presets, two different values.
The skill must still confirm it out loud every run. It appears as its own line in the Phase 2 confirmation block, not folded into a general "still your prefs?" yes. A wrong guess here never surfaces as an error — it just quietly ranks every option around a cost that was never going to be paid.
A preset never bypasses confirmation — the skill still shows the resolved plan and waits for a yes. It only removes the research step.
shuttle_service
- Type: object or null. If non-null, the skill pairs flights with ground shuttle runs on either end. Full sub-schema in
references/shuttle_schedules.md.
Example configs
Frequent flier, one home airport, picky about times
{
"serpapi_key": "sk_xxx",
"budget_usd": 350,
"budget_strength": "soft",
"airline_preferences": ["DL"],
"airline_preference_strength": "hard",
"nonstop_preference": "required",
"nonstop_strength": "hard",
"time_priority_bands": ["07:00-10:00", "17:00-20:00"],
"time_priority_strength": "soft",
"max_duration_min": null,
"max_duration_strength": "soft",
"home_airport": "JFK",
"frequent_destinations": ["LAX", "SFO", "SEA"],
"trip_presets": {},
"shuttle_service": null
}Casual traveler, cost-sensitive, flexible
{
"serpapi_key": null,
"budget_usd": 250,
"budget_strength": "hard",
"airline_preferences": [],
"airline_preference_strength": "soft",
"nonstop_preference": "preferred",
"nonstop_strength": "soft",
"time_priority_bands": [],
"time_priority_strength": "soft",
"max_duration_min": 600,
"max_duration_strength": "soft",
"home_airport": null,
"frequent_destinations": [],
"trip_presets": {},
"shuttle_service": null
}Student flying a fixed route both ways, with a shuttle at the campus end
{
"serpapi_key": "sk_xxx",
"budget_usd": 200,
"budget_strength": "soft",
"airline_preferences": [],
"airline_preference_strength": "soft",
"nonstop_preference": "preferred",
"nonstop_strength": "soft",
"time_priority_bands": ["11:00-14:00", "14:00-22:00"],
"time_priority_strength": "soft",
"max_duration_min": 480,
"max_duration_strength": "soft",
"home_airport": null,
"frequent_destinations": ["EWR", "IND", "ORD"],
"trip_presets": {
"home-to-school": {
"label": "NJ -> Purdue",
"aliases": ["to school", "to purdue"],
"origins": ["EWR", "LGA", "JFK"],
"destinations": ["IND", "ORD"]
},
"school-to-home": {
"label": "Purdue -> NJ",
"aliases": ["home", "to nj"],
"origins": ["IND", "ORD"],
"destinations": ["EWR", "LGA", "JFK"]
}
},
"shuttle_service": {
"home_label": "West Lafayette / Purdue",
"home_timezone": "America/New_York",
"providers": [
{"name": "Campus Shuttle Co", "airports": ["IND", "ORD"],
"schedule_urls": ["https://example.com/schedule"]}
],
"costs": {"IND": 30, "ORD": 60},
"airport_timezones": {"IND": "America/New_York", "ORD": "America/Chicago"},
"min_buffer_min": 90,
"min_connect_min": 60,
"max_wait_min": 240,
"reservation_lead_hours": 24
}
}Strength semantics recap
| Strength | Behavior |
|---|---|
hard | Filter applied strictly — non-matching flights are excluded from output |
soft | Filter applied as a rank weight — non-matching flights still shown, flagged with soft_filter_violations and sorted below matching ones |
When hard filters return zero results, the skill runs filter_flights.py --cluster-analysis to see which constraint(s) eliminated which flight counts, then proposes specific relaxations.
02 Shuttle PairingHow to configure a shuttle service in either direction, and the buffer and viability math behind each pairing.
Reference
Shuttle Pairing
1. Config block
"shuttle_service": {
"home_label": "Home town",
"home_timezone": "America/New_York",
"providers": [
{
"name": "Acme Airport Express",
"schedule_urls": [
"https://acmeairport.example.com/schedules/ord",
"https://acmeairport.example.com/schedules/mdw"
],
"airports": ["ORD", "MDW"]
}
],
"costs": { "ORD": 60, "MDW": 55 },
"airport_timezones": { "ORD": "America/Chicago", "MDW": "America/Chicago" },
"min_buffer_min": 90,
"min_connect_min": 60,
"max_wait_min": 240,
"reservation_lead_hours": 24
}Fields:
home_label— display name for the pickup/dropoff townproviders— one entry per shuttle company. Multiple companies serving the same airport is normal and supported; the pairing script picks whichever run fits best regardless of who operates it.
- name — company display name
- schedule_urls — public schedule pages the skill fetches with WebFetch each run
- airports — IATA codes this company serves
costs— one-way USD per airport, charged once per shuttle leg used (a trip with both a pre- and post-flight shuttle is charged twice)airport_timezones— IANA zone per airport. Informational; the buffer math does not need it (see "Timezones" below), but it's useful when reading a schedule page that lists times in a single zone.min_buffer_min— pre-flight floor. Default 90. Raise to 120 for airports with long security lines, drop to 60 with PreCheck and a shuttle you trust.min_connect_min— post-flight floor: how long after landing before the user can realistically be at the shuttle stop. Default 60. Raise it if they check bags.max_wait_min— above this, a pairing is labeled a long wait but still shown. Default 240.reservation_lead_hours— how much notice the company requires. If set, the skill passes--nowand--reservation-lead-hoursso pairings inside the cutoff get flagged.
Set shuttle_service: null (or omit it) if the user has no shuttle.
Legacy single-provider form (still read correctly): a flat "name" + "schedule_urls" at the top level instead of a providers array.
2. JSON the pairing script expects
After fetching the schedule URLs, assemble this and save it as shuttles.json:
{
"shuttles": [
{
"company": "Acme Airport Express",
"airport": "ORD",
"direction": "to_airport",
"stop": "Downtown station",
"departs_local": "06:00",
"arrives_local": "08:30",
"days": ["Mon", "Tue", "Wed", "Thu", "Fri"]
},
{
"company": "Acme Airport Express",
"airport": "ORD",
"direction": "from_airport",
"stop": "Terminal 2, door 3E",
"departs_local": "19:00",
"arrives_local": "21:30"
}
]
}Field rules:
airport— IATA code, required. This is what matches the flight.direction—"to_airport"or"from_airport", required.departs_local/arrives_local— HH:MM 24-hour. Each time is local to the place that event happens. Ato_airportrun departs in home time and arrives in airport time; afrom_airportrun departs in airport time and arrives in home time.stop— optional pickup/dropoff point, shown in the output table.days— optional list of operating weekdays ("Mon"or"Monday", any case). Omit for daily service. Weekend schedules usually differ — capture them.company— optional but recommended; shown in the output.
One object per run. If a company runs 9 times a day to one airport, that's 9 objects.
Older schema still accepted: {"from": "Home", "to": "ORD", "departs_et": "...", "arrives_local": "..."}. The script infers airport/direction from whichever of from/to looks like an IATA code. Entries where neither side is an IATA code are a hard error, not a silent skip.
3. Timezones
The buffer math never converts timezones, and it doesn't need to. It only ever compares the airport-side shuttle time against the flight time, and SerpAPI reports flight times in the airport's own local zone — so both sides are already in the same frame.
--tz-offsets from earlier versions is accepted and ignored (it applied the same offset to both sides of the subtraction, so it always cancelled out).
Overnight runs are handled by testing the adjacent calendar day, so a 23:40 landing can pair with a 01:00 departure the next morning.
4. Extracting schedules from a website
- WebFetch each URL in every provider's
schedule_urls. Prompt: *"extract every shuttle run in both directions — town to airport and airport to town — with departure time, arrival time, destination airport, pickup/dropoff stop, and which days it operates."* - Build one object per run per direction.
- If the site only shows one direction, fetch the return page too, or ask the user. Do not assume the return schedule mirrors the outbound one.
- If weekend schedules differ and the trip falls on a weekend, capture the weekend runs and set
dayson each entry.
5. Per-run overrides
Cost override for a single search (a friend is driving, one way is free): pass --shuttle-costs "ORD:0" instead of the config value. Never write the override to the config.
Tightness override: --min-buffer-min / --min-connect-min / --max-wait-min on the command line beat the config values for that run.
--max-gap-min (default 720) is the hard ceiling — a shuttle run further than this from the flight is not treated as a pairing at all, which is what stops "your shuttle is 22 hours later" from showing up as an option.
6. What the labels mean
| Label | Meaning |
|---|---|
| comfortable | Buffer sits between the floor + 30 min and the floor + 90 min |
| comfortable, longer wait | Above floor + 90 min but still under max_wait_min |
| tight | Within 30 min of the floor — works only if the shuttle is on time |
| long wait | Over max_wait_min |
| TOO TIGHT | Under the floor. Shown, ranked last, and never recommended. |
03 Search HistoryThe append-only log format that tracks every search and selection over time.
Reference
Search History
File format
A single JSON array of entry objects. The file is created the first time the skill writes to it; until then the file does not exist.
[
{ entry 1 },
{ entry 2 },
...
]To append safely: read the array, push the new entry, write the file back. If the file is missing or corrupt, start a fresh array.
Entry types
There are two entry types. Each search produces one of each (under normal flow).
search_started
Written immediately after the user confirms Phase 2 preferences and before fetch_flights.py runs. Captures what they were looking for, even if they abandon the search before booking.
{
"type": "search_started",
"id": "2026-05-11T14:23:07-04:00-3f9a",
"timestamp": "2026-05-11T14:23:07-04:00",
"dates": ["2026-05-15", "2026-05-16"],
"origins": ["IND", "ORD"],
"destinations": ["EWR", "LGA"],
"config_snapshot": {
"budget_usd": 200,
"budget_strength": "soft",
"airline_preferences": ["UA", "DL"],
"airline_preference_strength": "soft",
"nonstop_preference": "preferred",
"nonstop_strength": "soft",
"time_priority_bands": ["11:00-14:00", "14:00-22:00"],
"time_priority_strength": "soft",
"had_shuttle": false
}
}Fields:
id— unique identifier for this search. Format: ISO timestamp + 4-char random hex.timestamp— ISO 8601 with timezone offsetdates— list of YYYY-MM-DD strings the user searchedorigins,destinations— list of IATA codes used for this search (Phase 1 input)config_snapshot— preferences as-applied to this search (after any Phase 2 overrides). Don't includeserpapi_key.
selection_made
Written after the user picks a flight from the ranked output. Links back to the search_started entry.
{
"type": "selection_made",
"timestamp": "2026-05-11T14:31:42-04:00",
"search_started_id": "2026-05-11T14:23:07-04:00-3f9a",
"chosen_flight": {
"date": "2026-05-15",
"flight": "UA 1234",
"from": "IND",
"to": "EWR",
"departs": "13:45",
"arrives": "16:20",
"price": 178,
"stops": 0,
"airline": "United"
},
"chosen_shuttle": null,
"total_cost": 178,
"options_shown_count": 7
}Fields:
search_started_id— id of the matchingsearch_startedentrychosen_flight— the flight dict fromfilter_flights.pyoutputchosen_shuttle— the shuttle dict frompair_shuttles.pyif pairing was used, else nulltotal_cost— flight + shuttle USDoptions_shown_count— how many options the user could pick from
How the skill uses the log
- Pattern surfacing (passive): When relevant, the skill can read recent entries to note things like "Your last 3 trips picked flights between $160–$200 — flagging the $245 option as out-of-pattern."
- Abandoned-search detection: A
search_startedwith no matchingselection_madewithin the same day suggests an abandoned search. The skill should not bring these up unprompted. - Privacy: The log lives on the user's local disk, unencrypted. Don't put the SerpAPI key or any other secret in
config_snapshot.
Pruning
The file grows by 2 entries per booking. Pruning is the user's responsibility — they can delete it or keep it indefinitely. The skill does not prune.
Use it now. It's free.
Works on all platforms. Pick yours and get set up in under a minute.
Claude.ai
Download & upload in 60 seconds
Download the zip, then open Claude.ai to upload it.
Download the zip below. With JavaScript enabled, Claude.ai opens in a new tab if your browser allows it. Otherwise, use Open Claude.ai.
Click the + button in the skills column on the left.
Select Create a skill.
Select Upload a skill and upload the zip.
Start your flight planning session by running /estack-flight-planner.
Claude Code
Run one command in any terminal
Works anywhere Node.js is installed — your project directory, home directory, anywhere.
Open your terminal app and run this command.
npx elliot-stack@latest
Run the command.
Start Claude Code by typing claude in your terminal.
Start your flight planning session by running /estack-flight-planner.
ChatGPT / Other
Paste a prompt — the AI does the rest
This prompt tells the AI where to fetch current instructions from the live site. No installs. No version lag.
Copy the prompt below.
Preview prompt
# Flight Planner
A deterministic flight search and ranking pipeline. The user supplies their trip (dates + origin + destination) every run; everything else (budget, airlines, time windows, duration cap, optional shuttle) comes from a saved preferences config so repeat searches are fast.
The math (filtering, pricing, ranking, shuttle buffer calculation) runs in Python scripts — never eyeballed by the LLM — so results are reproducible. The LLM's job is orchestration and presentation.
## What the scripts own, and what you decide
The scripts exist to do the work that is **repetitive, unavoidable, and expensive to get subtly wrong**. Everything else is yours.
| Scripts own it | Why |
|---|---|
| Fetching every route × date from SerpAPI | Happens every run regardless of the request. Missing a route means silently recommending the wrong flight. |
| Parsing SerpAPI's nested shape | Full of traps: arrival time is on the *last* leg, the delay flag is per-leg, a "UA" itinerary can have an AA second leg. Wrong here poisons everything downstream. |
| Shuttle buffer math | Timezones, overnight rollover, day-of-week schedules. Fiddly, and a silent hour of error puts someone at a closed airport counter. |
**You own filtering, ranking, and the shape of the answer.** Those depend entirely on what this particular user asked for this particular time, and there is no reason to squeeze that into a fixed set of flags.
So: **`load_flights.py` is the real entry point after fetching.** It hands you every itinerary with every field SerpAPI returned (per-leg detail, layover airports and durations, delay and overnight flags, legroom, aircraft, operating carrier, carbon, price insights) and filters nothing.
`filter_flights.py` is an optional convenience covering the common case (budget, airlines, nonstop, time windows, duration). Reach for it when it genuinely fits. The moment the user wants something it doesn't express — "nothing connecting through Charlotte", "I'll pay $60 to land before 6pm", "red-eyes only", "cheapest per hour of my time", "no aircraft with under 30 inches of legroom" — **stop using it and write the pass yourself.** Contorting a real request into `--max-price` and `--soft-filters` gives a worse answer than five lines of Python.
**Put one-off scripts in the scratchpad.** If your harness gives you a session scratchpad directory, write them there; otherwise a temp directory. Never write them into the skill folder, and never edit the shipped scripts to handle a single request. Those scripts are shared by every user of this skill; your custom filter is for this conversation.
```python
# <scratchpad>/pick_flights.py -- one-off, throwaway, not part of the skill
import json, subprocess, sys
flights = json.loads(subprocess.run(
[sys.executable, "https://elliotdrel.com/e-stack/flight-planner/scripts/load_flights.py", "--json-dir", JSON_DIR],
capture_output=True, text=True).stdout)
# whatever the user actually asked for
ok = [f for f in flights
if not any(lo["airport"] == "CLT" for lo in f["layovers"])
and f["arrives"] < "18:00"
and f["legroom"] >= "30 in"]
ok.sort(key=lambda f: f["price"] + (0 if f["stops"] == 0 else 60))
json.dump(ok, open(OUT, "w"), indent=2)
```
The output shape matches `filter_flights.py`, so `pair_shuttles.py` accepts it either way.
## Two things that are easy to get wrong
**1. The shuttle can be on either end of the trip.** A ground shuttle pairs with a flight in two different ways, and which one applies depends on the direction the user is travelling:
| Leg | When it applies | Rule |
|---|---|---|
| Pre-flight (`to_airport`) | The user is *leaving* from the shuttle's home town | Shuttle must **arrive** at the airport before the flight departs |
| Post-flight (`from_airport`) | The user is *arriving* at an airport near the shuttle's home town | Shuttle must **depart** the airport after the flight lands |
Both can apply to one itinerary, one can, or neither.
**Always ask which ends need a ride. Never infer it.** Having a shuttle configured for an airport does not mean the user wants one on this trip — they may be getting dropped off, driving and parking, staying with someone near the airport, or stopping somewhere else on the way. Ask plainly:
> Do you need a ride to the airport, from the airport, both, or neither?
A saved preset can carry a default (`shuttle_legs`), and that default is usually right, which is exactly why it still gets confirmed out loud every run rather than applied silently. A wrong assumption here doesn't produce a visible error; it produces a table quietly ranked around a $55 cost the user was never going to pay.
Once you know which legs are needed, fetch **only those directions** — and fetch them properly. A user flying *to* their home town needs the airport-to-town schedule, and scraping only the outbound one produces a table that silently drops every flight.
**2. Soft means soft.** A soft preference is worth a fixed number of dollars in the ranking, not a veto. `filter_flights.py` scores every flight as `price + penalties` so a $400 flight matching every preference will not outrank a $189 flight that misses one. Don't re-sort the script's output by hand.
## Show progress on every question
**Every question you ask the user must show how many questions are left in the current phase.** Use a prefix like `[Q 2 of 7]` or end with `(2 questions left after this)`. This applies to Phase 1, Phase 2 wizard, Phase 2 confirmation prompts, and any clarifying follow-ups within a phase.
Counting rules:
- Each value question and each strength question count separately (so a 4-preference wizard with strengths = 8 questions, plus 3 non-strength = 11 total).
- Skip questions that don't apply (e.g., nonstop strength when user picked "no preference") don't count toward the total — recompute remaining as you go.
- In **batch mode**, count each line in the batch as one question, and tell the user "this batch has N questions" up front.
- In **Phase 2 confirmation mode** (returning user), it's effectively 1 question ("are these still your prefs?") — say so.
- Phase 1 has 1 question (the open "where/when").
Example phrasing:
- One-at-a-time: `[Q 3 of 11] What's your max budget per flight in USD?`
- Batch header: `Here are 4 questions in one batch — answer in any order:`
## Operating mentality — boil the ocean
**Don't make the user do work you could do yourself.** When the user gives a vague trip ("this weekend, Indiana to NJ"), do NOT bounce back with "please give me IATA codes and exact dates." Use your tools to fill in everything inferable, then present a complete proposed plan and let the user adjust.
For every vague input, before asking a follow-up, exhaust:
- **`date` command via Bash** for any relative date ("this weekend", "next Friday", "in 3 weeks")
- **`WebSearch`** for nearby major airports given a city/state/region (e.g., "Indiana" → IND, SBN, FWA; "NJ" → EWR, plus nearby LGA, JFK, PHL)
- **Config defaults** (`home_airport`, `frequent_destinations`) for likely matches
- **Flight history** for recent route patterns
- **Common sense + sanity checks** — e.g., if user says "Indiana" and config has `home_airport: IND`, lead with IND.
Then present:
> Here's what I worked out — adjust anything that's off:
> - **Dates:** 2026-05-16 (Sat) — 2026-05-17 (Sun) ← resolved from "this weekend"
> - **Origin:** IND (Indianapolis) — also nearby: SBN (South Bend), FWA (Fort Wayne)
> - **Destination:** EWR (Newark) — also nearby: LGA, JFK
>
> Want me to expand origin/destination to include the nearby airports, or run with just IND→EWR? Any changes to dates?
**The bar is "holy shit, that's done," not "good enough."** Never present a workaround when the real fix is one tool call away. Never offer to "ask more questions later" when you can answer them now. Never leave a dangling assumption — confirm it visibly. Search before asking. Verify before shipping.
This applies to every phase, not just Phase 1. If the user later says "actually, just nonstops" without specifying strength, infer `hard` from "just" and confirm in your next message, rather than asking a separate strength question.
## Files
- `https://elliotdrel.com/e-stack/flight-planner/scripts/check_setup.sh` — Deterministic startup check (runs in Phase 0)
- `https://elliotdrel.com/e-stack/flight-planner/scripts/fetch_flights.py` — SerpAPI Google Flights wrapper
- `https://elliotdrel.com/e-stack/flight-planner/scripts/load_flights.py` — Normalize every itinerary, filtering nothing. Start here after fetching.
- `https://elliotdrel.com/e-stack/flight-planner/scripts/filter_flights.py` — Optional convenience filter/rank/cluster-analyze for the common case
- `https://elliotdrel.com/e-stack/flight-planner/scripts/pair_shuttles.py` — Optional: pair flights with a ground shuttle on either end
- `https://elliotdrel.com/e-stack/flight-planner/references/config_schema.md` — Full config.json field reference, including trip presets
- `https://elliotdrel.com/e-stack/flight-planner/references/flight_history_schema.md` — Flight log format reference
- `https://elliotdrel.com/e-stack/flight-planner/references/shuttle_schedules.md` — Shuttle schema, both directions, and how to scrape a schedule page
## Persistent state (not in the skill directory)
- `~/.flight-planner/config.json` — User preferences. Created via first-run wizard. Never overwritten by skill installer.
- `~/.flight-planner/flight_history.json` — Append-only log of searches and selections.
`~` expands to `%USERPROFILE%` on Windows and `$HOME` on Mac/Linux.
## Workflow — four phases
Run these in order every time. Do not skip Phase 2 even if the config looks right.
### Phase 0 — Setup check (deterministic, runs on skill load)
The fenced command below runs automatically when the skill is invoked. Read its output before doing anything else — it tells you the user's setup state without you having to ask.
```!
bash ~/.agents/skills/estack-flight-planner/scripts/check_setup.sh
```
The output reports:
- Today's date and local timezone (use this when converting relative dates in Phase 1)
- Whether `~/.flight-planner/config.json` exists, and if so, all current preferences (with the SerpAPI key masked to "set" or "null")
- Any saved **trip presets**, with their aliases — these are the fast path in Phase 1
- The shuttle service: providers, costs, buffer settings, and how many schedule URLs to fetch
- Whether `SERPAPI_KEY` is set in the environment
- Whether `~/.flight-planner/flight_history.json` exists and how many entries it has
**Decision tree based on output:**
- **Config exists** → Phase 1 (ask trip details), then Phase 2 in confirmation mode (show saved prefs, ask "still right?")
- **Config missing** → Phase 1 (ask trip details), then Phase 2 in wizard mode (walk through each preference, offer to save at end)
- **Config exists but `serpapi_key: null` AND no env var** → tell the user up front that you'll use the WebSearch fallback in Phase 3 Step 2, with the caveat about coverage
- **Shuttle configured but zero schedule URLs** → say so now. Pairing cannot run without them, and finding that out in Phase 3 wastes a full search.
Don't repeat back the setup output to the user verbatim — just internalize it and adapt your behavior.
**After Phase 0 finishes, present an overview to the user before Phase 1:**
Tell the user, in your own words:
- What this skill does: finds and ranks flights between any two airports using their preferences.
- How it works: 4 phases — (1) Trip details (where/when), (2) Preferences (confirm saved config or run a first-run wizard), (3) Run the search pipeline (fetch → filter → rank → optional shuttle pairing), (4) Recommend and log.
- Where state lives: `~/.flight-planner/config.json` (preferences) and `~/.flight-planner/flight_history.json` (search log).
- Whether they're in first-run wizard mode or returning-user mode (based on Phase 0 output).
**Pacing for Phase 2 wizard (first-run only):** If Phase 0 showed no config, the user will face a multi-question wizard in Phase 2. Right after the overview, ask once: "When we get to your preferences setup, do you want me to ask all questions one at a time, or batch them so you can answer in one message?" Skip this question entirely if a config already exists (returning user — Phase 2 is just confirmation).
### Phase 1 — Trip details (one question, then a proposed plan)
Per the "boil the ocean" mentality above, **do not ask three separate questions**. Ask ONE open question, then do the work:
**The single question:** "Where are you going and when?" (Wait for answer.)
The user may answer with anything from "May 16-17 IND→EWR" (already precise) to "this weekend Indiana to NJ" (vague). Either way, the next thing you do is **resolve every inferable detail with your tools**, then present a proposed plan.
**First: check the trip presets.** If the answer matches a preset's slug, label, or any of its `aliases` — "flying home", "back to campus", "NJ to Purdue" — the route is already decided. **Skip step 2 below entirely.** No airport WebSearch, no alternates hunt; the user already did that research when they saved the preset. Resolve dates, then jump straight to the proposed plan:
```
Matched your saved preset "home-to-purdue" (NJ -> Purdue).
Dates: 2026-08-20 (Thu), 2026-08-21 (Fri)
Origins: EWR, LGA, JFK
Destinations: IND, ORD
Shuttle: post-flight (land, then ride to West Lafayette)
Note: IND is a 2h/$25 ride; ORD is ~3.5h/$55 but often cheaper to fly into.
Run it?
```
A preset removes the research, not the confirmation. Still show the resolved plan and wait for a yes. If the user's phrasing is close to but not clearly one of the presets, name the one you think they mean and ask — don't silently pick.
**Tool steps before you respond (no preset matched):**
1. **Resolve dates deterministically with the `date` command via Bash.** Never guess or do calendar math in your head.
- Today: `date +%Y-%m-%d`
- Next Friday (Linux/WSL): `date -d 'next Friday' +%Y-%m-%d`
- Next Friday (macOS): `date -v+Fri +%Y-%m-%d`
- "+N weeks": `date -d '+N weeks' +%Y-%m-%d` (Linux) / `date -v+Nw +%Y-%m-%d` (macOS)
- PowerShell fallback: `(Get-Date).AddDays(N).ToString('yyyy-MM-dd')`
- For "this weekend" / "next weekend", compute both Sat and Sun explicitly.
2. **Resolve airports — always WebSearch for common alternates, even when the user gave an exact IATA code.**
- Check config first: does `home_airport` or `frequent_destinations` match the region? Lead with those.
- **WebSearch is mandatory for every origin and every destination**, not just vague ones. Queries to run:
- "major airports near <location>" (when user gave a city/state/region)
- "airports within 100 miles of <IATA or city>" (to find common alternates even for a specific airport)
- "alternate airports to <IATA>" (e.g., user says EWR → surface LGA, JFK; user says LAX → surface BUR, LGB, SNA, ONT)
- Aim for 1 primary + 2–3 nearby alternates per endpoint. Alternates often save significant money on flights.
- Output IATA + full city name + approximate distance from the user's stated location so they can verify (e.g., `LGA (LaGuardia) — ~15mi from Newark`).
- **Never skip the alternate search.** A user who said "EWR" may not realize LGA flights to their destination are $80 cheaper — your job is to surface that option.
3. **Sanity-check the result yourself** before showing it. Are the dates in the future? Do the airports actually exist? Does the route make geographic sense?
**Then present the proposed plan in a single block:**
```
Here's what I've worked out — adjust anything that's off:
Dates: 2026-05-16 (Sat), 2026-05-17 (Sun) ← from "this weekend"
Origin: IND (Indianapolis)
Also nearby: SBN (South Bend), FWA (Fort Wayne)
Destination: EWR (Newark)
Also nearby: LGA (LaGuardia), JFK (Kennedy)
Want me to widen origin/destination to include the nearby airports, or
run with just IND→EWR? Any changes to dates?
```
If the user says "looks good" → proceed to Phase 2 with that route. If they tweak it ("add LGA, drop Sunday") → apply the change and proceed; no need to re-confirm a third time unless something is now ambiguous.
Origin and destination are **never saved to config by default**. The user can opt in to saving them as `home_airport` / `frequent_destinations` in Phase 2 if they want.
**Offer to save a preset when a route is worth repeating.** After a search finishes on a route with no matching preset, and only if the user seems likely to fly it again (they mention school, work, family, "every semester", or it's their second search on the same pair), ask once: *"Want me to save this as a preset so next time you can just say 'flying home' and skip the airport research?"* If yes, write it into `trip_presets` with a slug, a label, the origins/destinations you resolved, and 2-3 aliases in the user's own words. Never save one unprompted.
### Phase 2 — Preferences confirmation
**If `~/.flight-planner/config.json` exists:**
Read it and show a single block:
```
Your saved preferences:
Budget: $200 (soft)
Airlines: UA, DL (soft)
Nonstop: preferred (soft)
Time priority: 11:00–14:00, 14:00–22:00 (soft)
Max duration: 8h (soft)
SerpAPI key: set
Shuttle service: Acme Express — IND $25, ORD $55
For this trip:
Ride FROM the airport at IND/ORD → yes (preset default)
Ride TO the airport at EWR → no (no shuttle configured there)
Still right? (yes / change <field>)
```
**The shuttle line is never folded into a general "yes".** Call it out as its own item every run, even when the preset default has been correct twenty times running. The user might be getting a ride, driving, or stopping somewhere on the way, and none of those show up as an error later — they just quietly skew the ranking around a cost that was never real.
If the user says "yes" → proceed to Phase 3. If they want to tweak a field for this run only, capture the override without writing it to disk. If they want a permanent change, ask "save this change to your config?" before writing.
**If no config file exists:**
Run the first-run setup wizard. **Strength questions are always separate from value questions** — never bundle "Budget: $200, hard or soft?" into one ask. The pacing the user chose after the overview determines how to sequence:
**The four strength-paired preferences:**
| # | Preference | Value question | Strength question |
|---|---|---|---|
| 1 | Budget | "What's your max budget per flight in USD?" | "Is the $X budget hard (exclude anything over) or soft (include but rank cheaper higher)?" |
| 2 | Airlines | "Any airline preferences? (IATA codes like UA, DL, AA — or 'none' for any airline)" | "Are <airlines> hard (only show these) or soft (prefer them but show others)?" |
| 3 | Nonstop | "Required / preferred / no preference for nonstop?" | (Only if not "no preference") "Is that hard (exclude stops) or soft (rank stops lower)?" |
| 4 | Time-of-day priority | "Priority time windows for departure? (e.g., 11:00-14:00,14:00-22:00 in 24h format — or 'none')" | (Only if not "none") "Is the <windows> priority hard (exclude flights outside) or soft (rank lower but include)?" |
| 5 | Max trip length | "Longest total trip you'd accept, gate to gate including layovers? (e.g. 8h — or 'no limit')" | (Only if not "no limit") "Is <N>h hard (exclude longer) or soft (rank longer ones lower)?" |
**One-at-a-time mode:**
For each preference, ask the value question → wait for answer → ask the strength question (echoing the chosen value verbatim) → wait for answer → move to the next preference.
**Batch mode:**
Send TWO batches:
- **Batch A — values.** Ask all four value questions in one message. Wait for all answers.
- **Batch B — strengths.** Echo each value back and ask its strength in one message. Example:
```
Got it. Now strength for each — hard (filter) or soft (rank)?
1. Budget = $200 → hard or soft?
2. Airlines = UA, DL → hard or soft?
3. Nonstop = preferred → hard or soft?
4. Times = 11–14, 14–22 → hard or soft?
```
Skip lines in Batch B where strength doesn't apply (airlines = "none", nonstop = "no preference", times = "none").
**After the strength-paired preferences, ask the remaining non-strength questions** (these don't need a strength companion). One at a time, or one final batch — match the user's chosen pacing:
6. **SerpAPI key** — "Do you have a SerpAPI key? (yes — paste it / no — explain how to get one / skip — use WebSearch fallback)". See the SerpAPI walkthrough section below.
7. **Optional fields** — "Want to save a home airport so we suggest it next time? (IATA code or 'no')". Same for `frequent_destinations`.
8. **Optional shuttle service** — "Do you use a ground shuttle between your town and an airport? (yes / no)". If yes, ask for:
- company name(s) — more than one company serving the same airport is fine and supported
- schedule URL(s)
- which airports each company serves
- one-way cost per airport
- **which ends they actually need a ride on** — to the airport, from it, both, or "depends on the trip". This becomes `shuttle_legs` on their presets and it is asked again every run regardless.
- if they ride in both directions, you need the return schedule too, not just the outbound one
- how much advance notice the company requires (many require 24h)
See `https://elliotdrel.com/e-stack/flight-planner/references/shuttle_schedules.md` for the full sub-schema.
After collecting answers, show the full config and ask "Save this to ~/.flight-planner/config.json?" before writing.
### Phase 3 — Execute
Run the scripts. Do all math via the scripts, never in your head.
**Step 1 — Log search start**
Append a `search_started` entry to `~/.flight-planner/flight_history.json` with timestamp, dates, route, and a snapshot of the preferences used (after Phase 2 overrides). See `https://elliotdrel.com/e-stack/flight-planner/references/flight_history_schema.md` for the exact format.
**Step 2 — Fetch live flight data**
If the user has a SerpAPI key:
```bash
python https://elliotdrel.com/e-stack/flight-planner/scripts/fetch_flights.py \
--dates 2026-05-09,2026-05-10 \
--routes IND-EWR,ORD-LGA \
--airlines UA,DL \
--stops 1
```
Pass `--airlines` only if the user has airline preferences. Pass `--stops 1` only if `nonstop_preference` is `required` or `preferred` with `hard` strength. Omit both for "any airline, any stops".
The script reads `SERPAPI_KEY` from the environment or accepts `--api-key`. Saves raw JSON to a temp directory and prints the directory path on stdout — capture this for the next step.
**If the user has no SerpAPI key:** Use WebSearch to query flight prices for each route × date combination. Tell the user up front: "Without a SerpAPI key, results will be less comprehensive — I'll search the web for each route but won't have structured price/time data." Build a JSON file in the same shape `fetch_flights.py` would produce so the downstream scripts work unchanged. If you're not confident the WebSearch results are reliable, say so and recommend they get a key.
**Step 3 — Load the data, then decide what's good**
Always start by loading everything:
```bash
python https://elliotdrel.com/e-stack/flight-planner/scripts/load_flights.py --json-dir <temp-dir-from-step-2> --with-meta
```
`--format table` gives a quick scan; `--with-meta` adds SerpAPI's own price insights per route/date (`lowest_price`, `price_level`, `typical_price_range`), which is what lets you say "this is a high fare for this route" rather than just quoting a number.
Now pick your path:
- **The request fits the common shape** (budget, airlines, nonstop, time windows, duration) → use `filter_flights.py` below.
- **It doesn't** → write a short pass in your scratchpad over the loaded JSON. This is the expected route, not a fallback. Say what rule you applied so the user can correct it.
Either way the result is a JSON array that `pair_shuttles.py` accepts.
```bash
python https://elliotdrel.com/e-stack/flight-planner/scripts/filter_flights.py \
--json-dir <temp-dir-from-step-2> \
--max-price 200 \
--time-priority "11:00-14:00,14:00-22:00" \
--from IND,ORD \
--to EWR,LGA \
--airlines UA \
--nonstop \
--max-duration-min 480 \
--soft-filters max-price,time-priority,airlines,nonstop,duration
```
Pass `--soft-filters` listing every preference whose strength is `soft` — those become rank weights instead of hard filters. Pass all hard preferences as strict filters with no `--soft-filters` entry.
A `preferred` + `soft` nonstop setting means you still pass `--nonstop` **and** list `nonstop` in `--soft-filters` — the flag defines the preference, the soft list decides whether it excludes or just ranks.
**Ranking.** Every flight comes back with `rank_score` (dollars: price + a penalty for each soft preference it misses) and `rank_explanation` (the arithmetic). The output is already sorted by it. Default penalties are `nonstop $60, route $50, airlines $40, duration $40, time-priority $30, max-price $0` plus `$15` per rung down the time-band list. `max-price` is $0 on purpose — the overage is already in the price, so charging it again would double-count.
Override with `--soft-penalties "airlines:80,nonstop:120"` when the user says a preference matters more than the default weighting implies ("I really don't want a connection"). Say what you changed and why.
The script outputs filtered flights as JSON to stdout. Capture it for step 5.
**Step 4 — Handle empty results (constraint relaxation)**
If step 3 came back empty, **never just report "no flights found"** — the flights exist, your constraints ate them. Say which constraint did it and what relaxing it would cost.
Wrote your own pass? Count how many itineraries each condition eliminated on its own; that's a three-line loop over the loaded data and it's the whole answer.
Used `filter_flights.py`? Rerun with `--cluster-analysis`, which does the same thing for its built-in constraints:
```bash
python https://elliotdrel.com/e-stack/flight-planner/scripts/filter_flights.py --json-dir <dir> --cluster-analysis
```
Read the report — it shows which constraint(s) eliminated which flight counts plus a price distribution. **Propose specific relaxations to the user**, not generic "try again with looser settings":
- "Your $200 hard budget filtered all 23 flights. Cheapest available is $237. Want to raise the budget to $240?"
- "The 11:00–22:00 window filtered out 15 morning flights. Want to add a 06:00–11:00 priority band?"
- "Airline filter (UA only) eliminated 18 of 23 flights. Want to drop the airline filter for this search?"
Wait for the user to pick a specific relaxation, then rerun step 3 with adjusted args.
**Step 5 — Pair shuttles (only if `shuttle_service` is set in config)**
Skip this entire step if the user's config has `shuttle_service: null`. Otherwise:
**5a. Use the answer the user gave you in Phase 2** about which ends need a ride. Never re-derive it from which airports happen to have a shuttle configured.
- Ride to the airport → fetch the **pre-flight** (`to_airport`) schedule, pass `--legs pre`.
- Ride from the airport → fetch the **post-flight** (`from_airport`) schedule, pass `--legs post`.
- Both → fetch both, pass `--legs both`.
- Neither → skip this step entirely and show a flights-only table. Don't add a shuttle cost the user isn't paying.
`--legs auto` pairs whichever legs the shuttle data can serve. It's the right default only when the user confirmed they want a ride wherever one exists.
**5b. Fetch the schedules.** WebFetch every URL in every provider's `schedule_urls`, in parallel. Prompt for **both directions explicitly** — most schedule pages carry the outbound and return tables on the same page, and a prompt that only names one direction will come back with only one. Ask for departure time, arrival time, stops, and operating days per run.
If a direction you need isn't on the page, say so and go find it (a sibling URL, the company's schedule page) rather than assuming the return mirrors the outbound. Times that come back ambiguous across a timezone line are worth flagging to the user rather than guessing.
**5c. Build `shuttles.json`** matching the schema in `https://elliotdrel.com/e-stack/flight-planner/references/shuttle_schedules.md`: one object per run, each with `airport`, `direction`, `departs_local`, `arrives_local`, and `days` where the schedule varies by weekday. Then:
```bash
python https://elliotdrel.com/e-stack/flight-planner/scripts/pair_shuttles.py \
--flights-json <filtered-output-from-step-3> \
--shuttles-json <shuttles-file> \
--shuttle-costs "IND:25,ORD:55" \
--legs auto \
--min-buffer-min 90 \
--min-connect-min 60 \
--max-wait-min 240 \
--now "<today's date and time, ISO>" \
--reservation-lead-hours 24
```
| Flag | Source | Notes |
|---|---|---|
| `--shuttle-costs` | `shuttle_service.costs` | Charged once per leg used |
| `--legs` | derived in 5a | `auto` pairs whichever legs the data can serve; `pre`/`post` force one; `both` requires both and drops flights missing either |
| `--min-buffer-min` | `shuttle_service.min_buffer_min` | Pre-flight floor (shuttle arrival → flight departure) |
| `--min-connect-min` | `shuttle_service.min_connect_min` | Post-flight floor (landing → shuttle departure). Raise it if the user checks bags. |
| `--now` / `--reservation-lead-hours` | today + config | Flags pairings inside the company's booking cutoff |
| `--include-unpaired` | — | Add it when a lot of flights got dropped and the user should see them anyway |
| `--format json` | — | Use when you need the numbers rather than the table |
Read the stderr summary line — it says how many flights paired and how many were dropped for missing which leg. If a large share dropped, that usually means a direction is missing from `shuttles.json`, not that the flights are bad.
**Step 6 — Present results**
- If pairing was done: show the markdown table from `pair_shuttles.py` directly. It's already ranked; don't re-sort it.
- If no shuttle: print a flights-only table with Date | Flight | Route | Departs | Arrives | Price | Airline | Stops | Notes.
Long result sets are normal. Show the top 10-15 rows, say how many there are in total, and offer the rest.
Recommend the top row in one or two sentences, and say what the runner-up trades against it (cheaper but a tighter connection, later but nonstop). Ask which flight they want to book.
**Step 7 — Log the selection**
When the user confirms a choice, append a `selection_made` entry to `~/.flight-planner/flight_history.json`, linking back to the `search_started` entry from step 1. See `https://elliotdrel.com/e-stack/flight-planner/references/flight_history_schema.md`.
**Step 8 — Offer booking link**
Give **two** links: the airline's own search page, and a Google Flights fallback. Airline sites are client-rendered apps behind bot protection, so you cannot load one to check your own URL — the fallback is what saves the user a round trip when the deep link is stale.
```
https://www.google.com/travel/flights?q=Flights%20from%20<DEP>%20to%20<ARR>%20on%20<DATE>%20nonstop%20<AIRLINE>
```
**Say plainly that these open a pre-filled search, not a purchase.** No airline supports deep-linking into checkout for one specific flight, so the user lands on a results list and picks the departure time out of it. Name the time so they know which row to click.
**Three ways an airline deep link goes wrong**, all silent — the page loads and shows *something*, just not what was asked for:
1. **The trip-type flag is often inverted or non-obvious.** Getting it wrong returns round-trip prices for a one-way search, which look wrong by roughly double.
2. **Booking paths get moved between site versions.** An old path may still resolve to a redirect or an empty form rather than a 404.
3. **Prices may default to base fare, excluding taxes and fees.** The quoted number then undercuts what the user actually pays.
Check the parameters against a current source before handing the link over rather than reconstructing one from memory. If you cannot verify, lead with the Google Flights link and say the airline one is unverified.
United, verified 2026-08-10 against [this breakdown of united.com's search deep link](https://browse.sh/skills/united.com/search-flights-xs5157.md):
```
https://www.united.com/en/us/fsr/choose-flights?f=<DEP>&t=<ARR>&d=<YYYY-MM-DD>&tt=0&sc=7&px=1&taxng=1&clm=7&st=bestmatches
```
`tt=0` is one-way and `tt=1` is round-trip (backwards from what you'd guess). `taxng=1` shows all-in pricing; without it the fare reads low. `clm=7` is economy. Airport must be an IATA code. The old `/en/us/flight-search/book-a-flight` path no longer serves this.
**Flag a restricted fare before the user buys.** If the itinerary is a basic/no-frills fare brand, say so and name what it costs them in practice: baggage limits, no seat selection, no changes or refunds. That last one matters most when the trip is pinned to a fixed date (a lease start, a first day of work) where a slip makes the ticket worthless rather than movable. Do not assert a specific airline's current baggage rule from memory — point the user at the checkout screen, where the real number appears.
## SerpAPI walkthrough
If the user doesn't have a SerpAPI key and asks for help getting one:
1. Tell them: "SerpAPI gives the skill structured Google Flights data. Free tier is 100 searches/month — usually enough for personal trip planning. Paid plans start at $50/month."
2. Walk them to https://serpapi.com/users/sign_up — sign up with email.
3. After signup, the API key is at https://serpapi.com/manage-api-key.
4. To set it permanently, walk them through either:
- Saving it in their `~/.flight-planner/config.json` (`serpapi_key` field), or
- Setting `SERPAPI_KEY` as an environment variable in their shell profile.
5. If they don't want a key: confirm they want the WebSearch fallback. Set `serpapi_key: null` in config. Tell them: "I'll use WebSearch each run. Results won't be as complete and prices may be approximations."
## Important behaviors
**Always run the scripts.** Don't summarize flights from memory. If the conversation has stale flight data from a previous run, re-fetch.
**Strength matters.** Hard filters exclude; soft filters rank. Pass soft filters via `--soft-filters` to keep non-matching results visible.
**Don't re-rank by hand.** The scripts emit `rank_score` and `plan_score` on one dollar scale. If the order looks wrong, the fix is a `--soft-penalties` override you can explain, not a manual reshuffle.
**Round trips are priced as two one-ways.** `fetch_flights.py` queries one-way fares (SerpAPI `type=2`). For a round trip, run the whole pipeline once per direction and show two tables. Say plainly that some carriers price a true round trip below two one-ways, so the total is an upper bound worth checking on the airline's own site before booking.
**No shuttle data ships with this skill.** Each user provides their own shuttle service info in their config. The skill scrapes their schedule URLs at search time.
**A shuttle serves two directions.** Fetching only the outbound schedule is the most common way to end up with an empty pairing table. Check which leg(s) the trip needs before you fetch.
**A configured shuttle is not a needed shuttle.** Ask which ends want a ride every single run, even when the preset default has been right every time before. Getting this wrong produces no error, just a ranking bent around a cost nobody was going to pay.
**Don't reshape the user's request to fit the flags.** `filter_flights.py` covers the common case only. Anything else gets a scratchpad script over `load_flights.py` output.
**Origin and destination are not saved by default.** Only save them if the user explicitly opts in. Trip presets are the exception — they exist to be saved, but only when the user says yes.
**Two log entries per search.** Entry 1 on fetch (step 1), entry 2 on selection (step 7). Both are written even if the user abandons mid-search — the search_started entry preserves what they were looking for.
**Times in the config are 24-hour HH:MM format.** Display them in 12-hour to the user but store 24-hour.
---
## Skill Feedback
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
```bash
gh issue create \
--repo ElliotDrel/e-stack \
--title "estack-flight-planner: <concise summary>" \
--body "<description from user feedback — expected vs. actual behavior and context>"
```
**If `gh` is not installed**, build a pre-filled URL:
```bash
python3 -c "
import urllib.parse
title = 'estack-flight-planner: <concise summary>'
body = '<description from user feedback — expected vs. actual behavior and context>'
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
"
```
Share the printed URL with the user and offer to open it in their browser.
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
Open your platform and paste the prompt.
Start your flight planning session.
Flight Planner ships in E-Stack, a set of 21 free skills installed by one command. See the whole stack.