Skip to content

skywain/trip-planner-skill

trip-planner

Unverified

End-to-end international trip planning: turns "I want to go to X for N days" into a verified, bookable plan — route skeleton across cities, flight price scans (international + domestic legs), train-vs-fly decisions, hour-by-hour daily timelines with opening hours, dwell times, holiday collisions and tappable turn-by-turn map links (小时级行程+地图导航+离线KML), hotel shortlists by neighborhood, budget rollup, and a booking checklist with deep links. Use this whenever the user asks to plan a trip, vacation, itinerary or honeymoon, compare flight dates/prices, pick between cities or routes, schedule a travel day hour by hour, fill a spare block of time ("I'm near X with 2 free hours"), turn a finished plan into a designed page (eight themed renders: illustrated / clay / noir / glass / journal / zine / splash / portal — 插画/黏土/夜航/玻璃/手账/Zine/闪屏/穿越版), or asks 旅行规划/行程安排/机票比价/去某国玩N天怎么安排/现在有空档干嘛/把行程做成好看的网页 — even if they only mention one piece (just flights, just hotels, or just navigation), the playbook and verification rules here still apply.

FileKindSize
SKILL.mdskill md32.9 KB
assets/plan.example.jsonconfig12.1 KB
examples/README.mdmarkdown13.0 KB
examples/china-2026/china-splash.htmlother937.1 KB
examples/china-2026/china.art.jsonconfig6.4 KB
examples/china-2026/china.geo.jsonconfig58.3 KB
examples/fixtures/bad/bracketed-note.geo.jsonconfig7.8 KB
examples/fixtures/bad/brief-card-not-text.geo.jsonconfig943 B
examples/fixtures/bad/decision-point-date-two-days-before.geo.jsonconfig848 B
examples/fixtures/bad/decision-point-day-date-not-iso.geo.jsonconfig7.8 KB
examples/fixtures/bad/decision-point-no-if-no.geo.jsonconfig715 B
examples/fixtures/bad/decision-point-same-what.geo.jsonconfig8.2 KB
examples/fixtures/bad/decision-point-src-not-http.geo.jsonconfig803 B
examples/fixtures/bad/decision-point-t-not-hhmm.geo.jsonconfig764 B
examples/fixtures/bad/decision-points-null.geo.jsonconfig594 B
examples/fixtures/bad/driver-enum.geo.jsonconfig711 B
examples/fixtures/bad/driver-self-no-driving-card.geo.jsonconfig736 B
examples/fixtures/bad/driving-card-no-as-of.geo.jsonconfig861 B
examples/fixtures/bad/driving-card-no-desk.geo.jsonconfig800 B
examples/fixtures/bad/driving-card-no-legality-line.geo.jsonconfig811 B
examples/fixtures/bad/driving-card-no-verdict.geo.jsonconfig939 B
examples/fixtures/bad/driving-card-zh-verdict-trailing.geo.jsonconfig967 B
examples/fixtures/bad/hotel-checkout-null.geo.jsonconfig786 B
examples/fixtures/bad/hours-as-of-not-date.geo.jsonconfig674 B
examples/fixtures/bad/hours-bare-string.geo.jsonconfig655 B
examples/fixtures/bad/hours-src-not-http.geo.jsonconfig662 B
examples/fixtures/bad/hours-text-empty.geo.jsonconfig647 B
examples/fixtures/bad/kind-enum.geo.jsonconfig7.9 KB
examples/fixtures/bad/must-false.geo.jsonconfig914 B
examples/fixtures/bad/must-no-stand.geo.jsonconfig755 B
examples/fixtures/bad/must-no-view.geo.jsonconfig758 B
examples/fixtures/bad/must-not-boolean.geo.jsonconfig798 B
examples/fixtures/bad/must-see-unmatched.geo.jsonconfig963 B
examples/fixtures/bad/must-see-view-empty.geo.jsonconfig910 B
examples/fixtures/bad/pending-no-checklist-row.geo.jsonconfig1021 B
examples/fixtures/bad/refundable-not-boolean.geo.jsonconfig686 B
examples/fixtures/bad/rental-leg-no-driving-card.geo.jsonconfig829 B
examples/fixtures/bad/review-counts-disagree.geo.jsonconfig1.0 KB
examples/fixtures/bad/review-lens-enum.geo.jsonconfig1.1 KB
examples/fixtures/bad/review-no-driving-lens.geo.jsonconfig1.3 KB
examples/fixtures/bad/review-not-object.geo.jsonconfig611 B
examples/fixtures/bad/review-single-pass-with-counts.geo.jsonconfig1.0 KB
examples/fixtures/bad/review-two-lenses.geo.jsonconfig959 B
examples/fixtures/bad/self-drive-no-driving-card.geo.jsonconfig635 B
examples/fixtures/bad/sub-stop-no-name.geo.jsonconfig763 B
examples/fixtures/bad/sub-stop-no-query.geo.jsonconfig763 B
examples/fixtures/bad/sub-stops-null.geo.jsonconfig578 B
examples/fixtures/bad/tour-confirmed-prefix.geo.jsonconfig902 B
examples/fixtures/bad/tour-not-boolean.geo.jsonconfig562 B
examples/fixtures/bad/tour-on-day-object.geo.jsonconfig7.8 KB
examples/fixtures/bad/tour-unconfirmed.geo.jsonconfig837 B
examples/fixtures/strict/clean.plan.geo.jsonconfig4.5 KB
examples/fixtures/strict/hours-as-of-after-asof.geo.jsonconfig4.1 KB
examples/fixtures/strict/hours-missing-in-window.geo.jsonconfig4.0 KB
examples/fixtures/strict/hours-stale-as-of.geo.jsonconfig4.1 KB
examples/fixtures/strict/no-generated.geo.jsonconfig3.8 KB
examples/fixtures/strict/refundable-no-clause.geo.jsonconfig3.8 KB
examples/fixtures/strict/rows-without-clock-or-kind.geo.jsonconfig3.7 KB
examples/fixtures/strict/self-drive-not-legal-no-decision.geo.jsonconfig4.4 KB
examples/fixtures/strict/t-n-date-mismatch.geo.jsonconfig3.8 KB
examples/fixtures/strict/tour-no-review.geo.jsonconfig3.4 KB
examples/fixtures/substops.plan.geo.jsonconfig9.1 KB
examples/gates-sample.icsother11.5 KB
examples/japan-2026/japan-illustrated.htmlother1.4 MB
examples/japan-2026/japan.art.jsonconfig6.2 KB
examples/japan-2026/japan.geo.jsonconfig65.5 KB
examples/kyoto-sample.htmlother13.0 KB
examples/kyoto-sample.kmlother1012 B
examples/kyoto-sample.plan.geo.jsonconfig7.2 KB
examples/mexico-2026/mexico-journal.htmlother2.0 MB
examples/mexico-2026/mexico.art.jsonconfig9.4 KB
examples/mexico-2026/mexico.geo.jsonconfig77.1 KB
examples/morocco-2026/morocco-glass.htmlother1.3 MB
examples/morocco-2026/morocco-portal.htmlother13.8 KB
examples/morocco-2026/morocco.art.jsonconfig3.8 KB
examples/morocco-2026/morocco.geo.jsonconfig85.1 KB
examples/nordic-2026/nordic-noir.htmlother686.8 KB
examples/nordic-2026/nordic.art.jsonconfig8.7 KB
examples/nordic-2026/nordic.geo.jsonconfig58.5 KB
examples/turkey-2026/turkey-clay.htmlother1.3 MB
examples/turkey-2026/turkey.art.jsonconfig3.5 KB
examples/turkey-2026/turkey.geo.jsonconfig75.8 KB
examples/vietnam-2026/vietnam-zine.htmlother2.5 MB
examples/vietnam-2026/vietnam.art.jsonconfig10.8 KB
examples/vietnam-2026/vietnam.geo.jsonconfig85.1 KB
references/art-schema.mdmarkdown318 B
references/country-quick-notes.mdmarkdown58.6 KB
references/cover-titles.mdmarkdown10.6 KB
references/data-sources.mdmarkdown49.2 KB
references/navigation.mdmarkdown23.6 KB
references/output-template.mdmarkdown49.2 KB
references/phase-0-intake.mdmarkdown12.4 KB
references/phase-1-brief.mdmarkdown22.8 KB
references/phase-3-legs.mdmarkdown10.5 KB
references/phase-4-days.mdmarkdown13.6 KB
references/phase-6-assemble.mdmarkdown22.3 KB
references/scheduling.mdmarkdown28.8 KB
references/themes.mdmarkdown37.9 KB
scripts/build_site.pyscript47.8 KB
scripts/flight_scan.pyscript18.9 KB
scripts/plan_lint.pyscript58.4 KB
scripts/render_plan.pyscript28.2 KB
scripts/route_tools.pyscript90.0 KB

references/phase-4-days.md

View on GitHub
# Phase 4 — City day-plans (the procedure)

Read this at the start of Phase 4, before any city is planned or any city agent is
launched. SKILL.md Phase 4 is the contract — inputs, outputs, and the gates that decide
pass/fail; this file is the whole procedure it points at. When Phase 4 fans out, the
city-agent prompt is built from §City-agent contract below: paste those lines into the
prompt (or give the agent this file's absolute path — a subagent's working directory
is not the skill root), because the agent never sees SKILL.md.

Inputs: the chosen route skeleton (Phase 2), the legs table (Phase 3), the Phase 1
brief facts (visa / entry, holidays, health, advisory — the assembler's, never a city
agent's) and `prefs` (interests, pace, language). Outputs: per city, plan-JSON day
objects insertable verbatim into `days[]` (output-template.md §city-block) with
`stops`, the hour-level `timeline` (anchors carry `hours`, view anchors their
`sub_stops`), `decision_points` on the days that have one, `hop_links`, `sun`,
`rain_alt`, `ribbon`, plus the city's `checklist_items`.


## City-agent contract — fan out or go sequential

When ≥3 cities and subagents are available, fan out one agent per city (otherwise do
the cities sequentially with the same structure); each prompt must include: the
dates, the user's interests + pace, the locked must-sees — `prefs.must_see` pasted
verbatim (each entry's `view` is the picture expected of it) — **search budget ≤8**, an
explicit **"do not run geocoding"** line (parallel agents would break Nominatim's
1 req/s policy — the assembler geocodes once, centrally), **the plan language**
(`plan.lang`, with one line telling the agent every reader-facing string in its
returned block — `label`, `what`, `note`, `view`, `stand`, `why`, hotel blurbs,
checklist rows, `unverified[]` — is written in that language; its sources will mostly be
English, and English notes pasted verbatim are how a zh plan goes half-English.
Machine fields keep the schema's form regardless: `stops[].query` stays
geocoder-friendly romanized/destination-local, and `kind`/`tag`/`verify`/`driver`, the
`hours` literals `unverified` / `open access` and `meta.review`'s `mode` / `lens` keep
the English enum words the lint and renderers read),
the paid-extras line (**an optional paid extra — spa, upgrade, lounge, excursion — is
named with its price in the first sentence; "free for guests" only from the property's
own page**; SKILL.md Interaction contract),
and the exact return
format from references/output-template.md §city-block — **plan-JSON day objects,
insertable verbatim**, not a summary — and, as the prompt's own last line, the hard
rule: **city agents do not
make visa/entry judgements** — no visa rows in their `checklist_items`, no "you need
a visa" in notes. Visa/entry facts are the assembler's Phase 1 job and override
anything a city block says (Turkey test: both city agents put an outdated "visa
required" as checklist item #1; entry had been visa-free since 2026-01-02). The same
holds for health, advisory, hazard and insurance lines — Phase 1 facts, assembler-only.
When the user prefers group tours, the city agent's first job is
finding real in-sale products with departure schedules (data-sources.md §Group
tours) — the tour's schedule then dictates the surrounding legs, and a fly-in day
tour must clear BOTH weekday grids (operator departure days AND feeder-flight
schedules — same section) before its day is fixed in the skeleton.

## Per city — the six steps

Per city:
1. Anchors per interest-fit, ≤ pace + 1 optional per day. Cluster by geography per day;
   order clusters so the route never criss-crosses town.
2. **Verify every anchor**: open days + hours, last-entry time, price, and sell-out
   pressure (official site beats blogs; treat blog data >12 months old as stale).
   **Any anchor that sells out goes on the booking checklist with its lead time**
   (Ghibli, teamLab, Uffizi, Alhambra,
   Sagrada Família… see country-quick-notes.md). For dates more than ~3 months out
   nobody publishes that day's hours yet, so verify the **seasonal pattern + closure
   rule**, stamp it "pattern as of {date}", and let the **T-14 row of the pre-departure
   re-check ladder** carry the re-confirmation and the **T-3 row** write the fresh
   `hours` (output-template.md §Pre-departure re-check ladder). Claiming date-specific
   verification you cannot have is worse than admitting the horizon — and prices move on their own schedule
   (admission fees jump at fiscal-year boundaries), so re-check the fee, not just
   the hours. **Write what you read into the anchor row's `hours`**:
   `{text, as_of, src}` (a seasonal pattern says so in `text`), `"unverified"` when
   nothing could be read, or `"open access"` for a place with no opening hours (a
   street, beach, public viewpoint, a tour-owned block) — never bare hours, which carry
   no date (shape: output-template.md §city-block); the row's `what` and `note` then drop
   the hours they used to carry, so the page prints them once. National parks and other big
   nature anchors: also read the park's official Alerts/Current Conditions page —
   storm, fire and eruption closures outlast news cycles, and a partially-open park may hold 2-3 hours of content
   where the brochure promises a day (resize the day; design it droppable while
   the region is in disaster recovery). When the draw is a natural phenomenon
   (lava fountains, aurora), plan the day to work WITHOUT it: base rate ≈ event
   duration ÷ recurrence interval, the official forecast horizon (days, not
   weeks) sets a decision gate on the checklist — keep every related booking
   cancellable until that gate, and pay no premium for a lottery ticket. Which days
   carry `decision_points`, and how one differs from a checklist gate: scheduling.md
   rule 10 and §Day types (shape: output-template.md §city-block).
   **Name the picture, not just the place.** For every must-see whose draw is a picture,
   write the picture the user means as a short phrase in `view` (any angle, side,
   level, composition or detail — output-template.md §city-block), where to stand for
   it in `stand`, and the walk to it (`walk_min`).
   The same sight seen two ways is two sub-stops (live case: a group tour stopped only
   at the boardwalk; the picture the traveller came for is taken from an overlook trail
   above it). A picture named in the locked must-sees is the `must: true` sub-stop, with
   `view` and `stand`; the anchor row's `what` carries the must-see's name as it
   stands in `prefs.must_see` (the lint matches the two). A plan that reaches only
   another picture says so in the row; the entry's `view` changes only through the
   traveller's recorded decision (phase-0-intake.md §`prefs` and the assumptions
   block). On a guided day, check which of these pictures the tour actually reaches
   before the day is fixed (data-sources.md §Group tours). Write them as `sub_stops` on
   the anchor row, and mark a block a guided tour owns `tour: true` so its must-sees carry `confirmed`
   (shape: output-template.md §city-block).
3. Transit: day-pass vs pay-per-ride arithmetic — sum the day's expected rides and
   recommend the pass only when it actually wins. Note the local IC card / transit app.
4. Each day gets one rain alternative and a food **area** (market/street/neighborhood)
   near the evening cluster — named restaurants only on request; they churn too fast.
5. Timing realism: transit between clusters from Google Maps (browser) or mark the
   estimate unverified; hard stop = last entry, and nothing scheduled after it.
6. **Timeline assembly — hour-level is the default deliverable.** Read
   references/scheduling.md (dwell times, tiered ticket margins, buffer policy,
   arrival/moving/departure day structures, worship + siesta + crowd-calendar traps,
   degradation tags) and references/navigation.md (hop links, canonical hop-row
   format, exit numbers, verify-vs-estimate rules), then run scripts/route_tools.py
   in this order: **geocode → per-day tz sweep → sun --write → links --write →
   check → kml**, so every hop carries a distance-sane duration and a tappable map
   link written into the plan for you. **`check` must exit 0 before rendering** —
   a BROKEN hop is a stop with no lat/lon (geocode it, or hand-fill: navigation.md
   §2), a SUSPICIOUS hop is an undeclared hop over 12 km, or a declared walk / transit
   hop over 60 km. It has two fixes and no third. A vehicle really runs the hop (fly /
   drive / boat / train / bus) → declare that `mode` on the arriving stop and give it
   its `legs[]` row (add the row if the leg has none) — an undeclared real flight is a
   defect too (a tester shipped exit 2 on Wilson → Seronera rather than write
   `mode: fly`). Nothing runs it (a 250 km hop inside one city is a mis-geocoded stop)
   → fix the stop (read `geocache.json`'s `display_name`, re-query or hand-fill), never
   the `mode` (a tester silenced a hotel geocoded to Kisumu with `mode: transit`). And
   never explain the flag away in prose (a tester shipped exit-2 output rationalised as
   "expected for a multi-city trip" — every flagged hop was a real defect).
   `sun --write` runs once the stops carry coordinates: it fills every day's
   `sun` (civil dawn · sunrise / sunset) in one canonical string and refuses data
   that fails a solar sanity check — never hand-copy sunrise numbers, and **run it
   before writing any sunrise / golden-hour / dark-start prose**: tz changes live in
   tzdata, not in your head (Morocco moves to UTC+0 on 2026-09-20 — the tester's
   hand-written times were an hour off on all ten days, and neither `check` nor
   `qc.py` compares prose against `sun`). A moving day defaults to the last stop;
   when the day's sunrise anchor is at the *first* stop, set the day's `sun_stop`
   (scheduling.md rule 7). **A plan that crosses timezones stamps every day's `tz`
   (IANA name) before `sun --write`** — sun refuses any day whose zone it would
   have to guess from longitude (the guess puts Hawaii at UTC-11), and it refuses
   per-day, so one sweep over `days[].tz` beats fifteen retries.
   **`sun`: non-zero exit = at least one day was skipped or rejected** — the written
   days are fine, re-run `--only DATE` for the ones it names before writing prose
   for them. The one exception: a day `sun` REJECTS as "polar day/night" (Tromsø in
   December, Nordkapp in June) is never re-run into green — remove that day's `sun`
   key (absent — not `null`, not `""`: the schema's own shape for a day without sun;
   renderer copies older than 2026-09-05 crash on `null`), put the polar note in the
   day's `note`, and carry it to Phase 6 as the one
   tolerated `plan_lint --strict` FAIL (output-template.md §`sun`; KNOWN-ISSUES
   PLN-11). Mark ridden
   hops with a `mode` on the arriving stop (`transit`/`train`/`bus`/`drive`/`boat`/
   `fly`; long signature walks `walk`), or the walking total and the links will
   both be wrong — `check` says (guessed) next to anything you left it to infer. Every drive
   stop the traveller drives carries `driver: self` (navigation.md §Self-drive days).
   Transit durations come back as ranges — keep them ranges unless you
   browser-verified the hop. Deliver day-level granularity only if the user asks for
   a rough cut. Each finished day also gets its `ribbon` one-liner (Stop1 →walk 12′→
   Stop2 →metro 9′→ …, output-template.md §5) — no script writes it; seven blank
   ribbons is the usual way to find out you forgot.

## Exit criteria — tick every line before Phase 5

- [ ] Every city block came back as plan-JSON day objects in `plan.lang`, with machine
      fields in schema form; no visa / entry / health / advisory / hazard / insurance
      rows in any
      `checklist_items` or note (assembler-only facts).
- [ ] Anchors per interest-fit, ≤ pace + 1 optional per day, clustered so the route
      never criss-crosses;
      every anchor verified (hours, last entry, price, sell-out — sell-out anchors on the
      booking checklist with lead time) or stamped "pattern as
      of {date}" with the T-14 ladder row carrying the re-confirmation and the T-3 row
      writing the fresh `hours`; every anchor
      carries `hours` (`{text, as_of, src}`, `"unverified"` or `"open access"`) and its
      `what` / `note` no longer print them.
- [ ] Every must-see whose draw is a picture has `sub_stops` on its anchor row with the
      picture in `view`, where to stand in `stand` and `walk_min`; on a guided day, the
      row carries `tour: true` and which of these pictures the tour reaches was checked;
      every `prefs.must_see` name stands in its anchor row's `what` as written there.
- [ ] Every decision scheduling.md rule 10 or §Day types places on the day or the
      evening before is in that day's `decision_points`; a gate days ahead stays a
      checklist row only.
- [ ] Each day has its rain alternative (closure-checked), its food area, its `ribbon`.
- [ ] `route_tools.py` ran geocode → tz sweep → sun --write → links --write → check →
      kml; `check` exited 0 (no BROKEN / SUSPICIOUS hop survived; every `mode`
      written to clear a flag names a vehicle that really runs the hop — fly / drive /
      boat / train / bus — and that leg has its `legs[]` row; none added to silence a
      flag); `sun` exited 0 or every named day was re-run with `--only DATE` — except
      a polar day it REJECTED, whose `sun` key stays absent (never `null`, never `""`)
      and is named in the summary (PLN-11).
- [ ] No sunrise / sunset / dark-start prose was written before `sun --write`; every
      ridden hop carries its `mode` on the arriving stop, and every drive stop the
      traveller drives carries `driver: self`; unverified transit durations
      stay ranges.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall