Roadtrip Navigator

RoadTrip Navigator

Turn "start + days" or "an existing route" into a road trip you can actually drive: paced into days, with overnight stops, fuel/charging, park reservations, seasonal road risks, and a map-first single-file HTML page.

North American road trips revolve around the car, not flights: how many hours do we drive today, where do we sleep, will we make it on the fuel/charge we have, and is the road even open. That focus is what this skill adds on top of a generic "list of attractions."

When to use

Use this skill whenever the request is about driving a multi-stop trip in the US / Canada / Mexico (see read-when triggers). If the user only wants a single city guide or a flight itinerary, this is not the right skill.

Two entry modes

Detect the mode up front (see scripts/helper.py for the heuristic):

• Light mode (plan it for me): user gives a start, a rough region or

destination, day count, and party/vehicle. → Run the full 7-step workflow, designing the route yourself.

• Heavy mode (verify my route): user pastes/links/screenshots an existing

route. → Skip route invention. Parse their route into the schema, then verify and fill gaps: driving segmentation, overnight realism, fuel/charge coverage, reservation countdown, seasonal closures, and produce the page.

When unsure which mode, ask one short question. Otherwise infer and proceed.

The five things that make this more than a list

These are where pure-model answers fail and where this skill earns its keep:

1. Daily driving segmentation (the core). Slice the whole route into days

under a sane daily drive limit, place an overnight at each segment end, and validate each day: drive ≤ limit, arrive before dark, no stop hits a closed gate, fatigue buffer. This is the road-trip equivalent of connection-checking — most AI itineraries skip it.

1. Reservation countdown. Recreation.gov campgrounds often release ~6 months

out; popular timed-entry a few days out; in-park lodges up to ~13 months out. From the departure date, work backwards into a "book by" to-do list.

1. Fuel / charge planning. Gas: flag long empty stretches ("next fuel in

X mi"). EV: plan a charging corridor against the vehicle's range and note whether each leg makes it, charger power, and a backup.

1. Seasonal road conditions & closures. Mountain passes that close in winter

(Going-to-the-Sun, Tioga Pass, Trail Ridge Rd), wildfire/hurricane/snow season. If the travel date hits one, down-rank or reroute and say so.

1. Timezones & borders. Correct arrival times across timezone lines; for

border crossings, flag documents / vehicle papers / insurance / wait times.

Workflow (7 steps)

> Run scripts/helper.py "" first — it parses slots, guesses the > entry mode, picks the trip region (for HTML theming), and prints what's still > missing. Use its output to drive the steps below.

Step 1 — Collect requirements (slot filling)

Required: start, travel date, days, party makeup, vehicle (gas/EV/RV + range). Optional: destination/region, budget, preferences (scenic vs. fast, hike intensity, loop vs. one-way, border crossing). Only ask follow-ups for missing required slots; fill the rest with sensible defaults and proceed.

Step 2 — Route / destination planning (if not given)

Decide loop vs. one-way first (affects one-way drop fees and pacing). For region-level input ("the Southwest", "Pacific Northwest"): search candidates → seasonal & closure check → shortlist. Compute rough total miles / driving days for the shortlist and drop any "can't be driven in N days" option.

Step 3 — Daily driving segmentation (core; see five-things #1)

1. Split by a daily drive limit (default: relaxed adults ≤ 4–5h;

with kids/seniors ≤ 3–4h; user-adjustable).

1. Put an overnight at each segment end (has lodging, supplies, good for the

next morning).

1. Validate: arrive before dark, no stop hits a closed gate, long legs

have a fuel/charge point mid-way.

1. If infeasible: cut miles / add a night / pick a closer overnight town.
2. Surface risks explicitly in the day, e.g. "no fast charger for 180 mi on this

leg — charge to full before leaving."

Step 4 — Parallel research (sub-agents)

Fan out (one concern per sub-agent, run concurrently): weather (per day), lodging/campgrounds (price + booking difficulty), fuel/charging points, attractions & tickets/permits, food, scenic byways & hikes, Reddit real-world gotchas. Delegation rule: instruct each sub-agent to hit official APIs first (NPS / NWS / Recreation.gov / Open Charge Map) and fall back to web search only on failure. See reference.md for the tool routing table and tools/.

Step 5 — Reservation countdown (see five-things #2)

From the departure date, generate a "book by" to-do list: campgrounds (Recreation.gov, ~T-6 months), timed-entry / wilderness permits (per park rule, T-X days), popular in-park lodges (up to ~T-13 months), one-way car/RV rental (lock price early). Render as a ⚠️ checklist at the top of the page + a timeline. Populate bookingCountdown[].

Step 6 — Budget (with reliability grading)

Tag every line verified / reference(~) / estimate(≈). Road-trip specifics: fuel = total miles ÷ MPG × gas price (or EV charging cost); tolls; park entry or the America the Beautiful annual pass; one-way drop fee; campground; lodging; food. Force a bottom disclaimer: prices are dynamic, confirm before departure.

Step 7 — Generate the single-file HTML (map-first)

1. Write the data to tripData.json first (data/view separation — editable,

re-renderable).

1. Render: python3 assets/generate.py tripData.json -o trip.html

→ Leaflet map (numbered stops + ordered polyline) + one-tap mobile nav (Google/Apple deep links) + daily timeline + reservation to-do + budget. Responsive (mobile single-column / desktop multi-column) + print friendly.

1. Validate before delivering (plan §9): the generator already does a light

schema check and a JSON parse of the injected data. Optionally syntax-check the inline JS, then open/preview.

1. Full-page disclaimer: AI-assembled, may be out of date, verify with official

sources.

Output contract

• Always produce both tripData.json and the rendered trip.html.
• Units: miles, °F, MPG, USD by default; switch to km/°C/local currency on

Canadian/Mexican legs and note the change.

• Never invent a precise reservation availability, live charger occupancy, or

minute-level traffic — point to the official app / Recreation.gov / nav.

Honesty boundaries (Phase 1)

Do not promise: exact live fuel/electricity prices, live charger occupancy, minute-level traffic, live campground availability, or replacing turn-by-turn navigation. For these, tell the user to confirm via the official app / Recreation.gov / their navigation app in real time.

Files

• reference.md — tripData schema, reliability grading, tool routing table.
• examples.md — typical prompts and expected outputs.
• assets/generate.py — tripData.json → single-file HTML.
• assets/template.html — the HTML/JS renderer (Leaflet map + timeline).
• assets/tripData.example.json / assets/preview.html — Southwest 7-day demo.
• assets/tripData.tahoe.json / assets/preview-tahoe.html — Sunnyvale→Tahoe

3-day demo (mountain theme, state-park reservations, Sierra snow risk).

• assets/tripData.pnw.json / assets/preview-pnw.html — Seattle→Vancouver→

Whistler EV cross-border demo (exercises all three Phase-3 modules below).

Phase-3 modules (implemented)

These render as extra sections when their data is present (see reference.md):

• Multi-route comparison — scripts/helper.compare_routes(options, party)

→ routeOptions[]. Use when you offer the user A-vs-B routes; it auto-rates drive intensity and renders a comparison table with the chosen route flagged.

• Cross-border — tools/border_client.trip_section([("US","CA",rental),...])

→ crossBorder. Per-crossing documents / insurance / customs / unit-switch checklist for US↔CA↔MX. Note the key asymmetry it encodes: US insurance is usually valid in Canada but never in Mexico (buy Mexican insurance).

• EV charging corridor — `tools/charging_client.corridor(legs, usableRange,

winterderate=...) → evPlan. Simulates state-of-charge leg by leg, sets a recommended charge-to at each stop, and flags legs that won't make the buffer. Pass winterderate` (e.g. 0.25) for cold-weather range loss.

• scripts/helper.py — input parsing, entry-mode + region detection, slot check.
• tools/*.py — per-source clients, each with a web-search fallback

(incl. border_client.py and charging_client.corridor()).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Waybox-AI
• Source: Waybox-AI/roadtrip-skill
• License: MIT

Install and usage instructions live in the source repository linked above.