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

examples/README.md

View on GitHub
# Examples

Seven finished trips, one per theme, plus the plain-page sample. Each folder holds only
the two source files and the page they produce — `<trip>.geo.json` (the facts),
`<trip>.art.json` (what the trip looks and sounds like) and `<trip>-<theme>.html`
(self-contained: every picture is an inlined webp, so the page opens by double-click with
no network). Re-running the render command below rewrites the shipped page **byte for
byte**, which is what makes these examples a regression test as well as a showcase.

The eighth theme, `portal`, is a video fly-through. Its page **is** here
(`morocco-2026/morocco-portal.html`, 13 KB — the markup is small because the footage is not
inlined), but its nine clips are ~16 MB and are not committed; they are published as the
`demo-assets-v1` release asset `morocco-portal-clips.zip`, which `scripts/build_site.py`
downloads when it builds the demo site. So the portal page renders complete online and
warns about missing `portal/*.mp4` when you open the repo copy locally.

## Open them without cloning

Every page below is served from the demo site, built by `scripts/build_site.py` and
deployed by `.github/workflows/pages.yml`. Each one is the real deliverable — ~1.5 MB,
self-contained, no server:

Eleven pages are live. Eight are the gallery's cards — one per theme, all English, each
one matching the frames in the root README's Showcase. Three of those eight are **not
stored in the repo**: `china-clay`, `mexico-noir` and `japan-zine` are rendered at build
time by `scripts/build_site.py`, straight from the committed `geo.json` + `art.json` (each
art file carries its trip's second theme, so nothing extra is needed). The remaining three
rows are the shipped Chinese editions of those same themes.

| Trip · theme | Lang | Live page | On disk |
|---|---|---|---|
| `japan-2026` · `illustrated` | en | <https://skywain.github.io/trip-planner-skill/examples/japan-2026/japan-illustrated.html> | shipped |
| `china-2026` · `clay` | en | <https://skywain.github.io/trip-planner-skill/examples/china-2026/china-clay.html> | rendered at build time |
| `mexico-2026` · `noir` | en | <https://skywain.github.io/trip-planner-skill/examples/mexico-2026/mexico-noir.html> | rendered at build time |
| `morocco-2026` · `glass` | en | <https://skywain.github.io/trip-planner-skill/examples/morocco-2026/morocco-glass.html> | shipped |
| `mexico-2026` · `journal` | en | <https://skywain.github.io/trip-planner-skill/examples/mexico-2026/mexico-journal.html> | shipped |
| `japan-2026` · `zine` | en | <https://skywain.github.io/trip-planner-skill/examples/japan-2026/japan-zine.html> | rendered at build time |
| `china-2026` · `splash` | en | <https://skywain.github.io/trip-planner-skill/examples/china-2026/china-splash.html> | shipped |
| `morocco-2026` · `portal` | en | <https://skywain.github.io/trip-planner-skill/examples/morocco-2026/morocco-portal.html> | shipped (16 MB of video, fetched) |
| `turkey-2026` · `clay` | zh | <https://skywain.github.io/trip-planner-skill/examples/turkey-2026/turkey-clay.html> | shipped |
| `nordic-2026` · `noir` | zh | <https://skywain.github.io/trip-planner-skill/examples/nordic-2026/nordic-noir.html> | shipped |
| `vietnam-2026` · `zine` | zh | <https://skywain.github.io/trip-planner-skill/examples/vietnam-2026/vietnam-zine.html> | shipped |

The gallery that links all of them: <https://skywain.github.io/trip-planner-skill/>. Each
trip's `geo.json` and `art.json` sit next to its page there too, so the sources are one
click away.

## The seven trips

| Trip | Theme | Origin → route | Dates | Lang | Cover title | Image generation |
|---|---|---|---|---|---|---|
| `japan-2026` | `illustrated` | London → Tokyo · Hakone · Kyoto · Osaka (KIX, open-jaw) | 21–28 Nov 2026 · 8 days | en | "Late Maples" | $0.4090 · 10 `gpt-image-2` calls → 18 webp via sheet splitting |
| `turkey-2026` | `clay` | Shanghai (PVG) → Istanbul · Cappadocia · Pamukkale · Istanbul | 1–9 Oct 2026 · 9 days | zh | 九万里风 / NINETY THOUSAND MILES OF WIND | $0.2594 · 7 calls → 19 webp via sheet splitting |
| `nordic-2026` | `noir` | Beijing (PEK) → Oslo · Bergen Railway · Flåm / Nærøyfjord · Bergen | 1–8 Oct 2026 · 8 days | zh | 天接云涛 / SEA OF CLOUDS | $0.2484 · 7 calls → 17 webp |
| `morocco-2026` | `glass` | Toronto → Marrakech · Aït Benhaddou · Merzouga · Fes · Chefchaouen · Casablanca | 6–15 Nov 2026 · 10 days | en | "Ochre Road" | $0.3624 · 11 calls; plus a `portal` variant at 21 GPU min on a local 5090 |
| `mexico-2026` | `journal` | Berlin (BER) → Mexico City · Teotihuacán · Oaxaca | 28 Oct – 6 Nov 2026 · 10 days | en | "Marigold" | $0.2820 · 8 calls → 18 webp |
| `vietnam-2026` | `zine` | Shenzhen (SZX) → Hanoi · Ha Long Bay · Hoi An / Da Nang · Ho Chi Minh City | 12–21 Dec 2026 · 10 days | zh | 人海 / A SEA OF FACES | $0.4566 · 11 calls → 28 webp |
| `china-2026` | `splash` | New York (JFK) → Beijing · Xi'an · Beijing | 11–18 Nov 2026 · 8 days | en | "MOON OF QIN" | $0.2991 · 7 calls → 23 stems |

$2.32 of image generation for all seven pages. No GPU time anywhere except the Morocco
`portal` variant — the stills-only themes never need one.

### In one line each

- **japan · illustrated** — a paper picture-book: the cover is the menu, each day gets a
  tinted riso plate with a ghost numeral and polaroid stickers, and the whole scroll
  exports as one long image.
- **turkey · clay** — one continuous claymation landscape scrolled end to end: modelled
  minarets, fairy chimneys and travertine terraces, with the overnight bus to Pamukkale
  sculpted in as its own scene.
- **nordic · noir** — a night-flight cinema: five stacked full-bleed negatives that
  cross-fade as you scroll, with the aurora odds argued down to an honest 5–10% instead
  of sold as a headline.
- **morocco · glass** — frosted-glass app chrome floating over six ochre desert plates;
  the itinerary reads like a native travel app, one pane per world, from the red rooftops
  to the blue mountain.
- **mexico · journal** — an open travel journal on one continuous sheet: vintage
  photographs taped down, torn ticket stubs, marigold ephemera, and a Day-of-the-Dead
  week that plans around the crowd.
- **vietnam · zine** — a cut-and-paste photocopy zine: film-grain plates, chapter posters
  and hand-set headlines, built around the one leg where the night train genuinely beats
  the flight.
- **china · splash** — a game splash poster stretched into a scroll: an abstract light
  field falling past floating day-islands, routed Xi'an-first so the Wall and the
  Forbidden City both land on weekdays.

## Render them

Run from the repo root; every line rewrites the shipped page exactly.

```
python3 themes/render_theme2.py  examples/japan-2026/japan.geo.json     -o japan-illustrated.html
python3 themes/render_clay2.py   examples/turkey-2026/turkey.geo.json   -o turkey-clay.html
python3 themes/render_noir2.py   examples/nordic-2026/nordic.geo.json   -o nordic-noir.html
python3 themes/render_glass2.py  examples/morocco-2026/morocco.geo.json -o morocco-glass.html
python3 themes/render_journal.py examples/mexico-2026/mexico.geo.json   -o mexico-journal.html
python3 themes/render_zine.py    examples/vietnam-2026/vietnam.geo.json -o vietnam-zine.html
python3 themes/render_splash.py  examples/china-2026/china.geo.json     -o china-splash.html
```

`cmp japan-illustrated.html examples/japan-2026/japan-illustrated.html` exits 0, and so does
the same check on the other six — that is the regression gate. Three conventions keep the
commands that short:

- **`--art` is implicit.** A renderer picks up `<plan>.art.json` sitting beside the plan.
  Running from somewhere else, or with an art file kept elsewhere, pass
  `--art examples/japan-2026/japan.art.json` — the art file's own folder joins the asset
  search path, so its pictures come along.
- **Pictures resolve from `themes/assets/`.** Every trip's stems are prefixed with the
  trip name (`japan-…`, `nordic-…`), so `--assets` is never needed here and a library
  size-variant can't shadow a trip's own picture.
- **The page language follows the plan** (`lang` / `meta.lang`); `--lang zh|en` on any
  renderer overrides the chrome, while art copy renders in whatever language it was
  written in.

## Two themes per art file

Each `art.json` carries the shipped theme's block **and a second theme's block**, so one
extra command gets a completely different page out of the same trip — the cheapest way to
see how far apart the themes really are.

| Art file | Shipped page | Second theme | Render it |
|---|---|---|---|
| `japan.art.json` | `illustrated` | `zine` | `python3 themes/render_zine.py examples/japan-2026/japan.geo.json -o japan-zine.html` |
| `turkey.art.json` | `clay` | `illustrated` | `python3 themes/render_theme2.py examples/turkey-2026/turkey.geo.json -o turkey-illustrated.html` |
| `nordic.art.json` | `noir` | `journal` | `python3 themes/render_journal.py examples/nordic-2026/nordic.geo.json -o nordic-journal.html` |
| `morocco.art.json` | `glass` | `portal` | `python3 themes/render_portal.py examples/morocco-2026/morocco.geo.json -o morocco-portal.html` |
| `mexico.art.json` | `journal` | `noir` | `python3 themes/render_noir2.py examples/mexico-2026/mexico.geo.json -o mexico-noir.html` |
| `vietnam.art.json` | `zine` | `splash` | `python3 themes/render_splash.py examples/vietnam-2026/vietnam.geo.json -o vietnam-splash.html` |
| `china.art.json` | `splash` | `clay` | `python3 themes/render_clay2.py examples/china-2026/china.geo.json -o china-clay.html` |

Morocco's `portal` block is the one that cannot render fully here: the page builds, but it
warns that nine `.mp4` clips are missing, because the video (~16 MB) is not shipped. The
shipped `morocco-portal.html` is that same page — see it running, footage and all, at
<https://skywain.github.io/trip-planner-skill/examples/morocco-2026/morocco-portal.html>.
The other six second themes render complete pages — and three of them, `china-clay`,
`mexico-noir` and `japan-zine`, are exactly what the demo site serves for those themes,
rendered by these same commands on every deploy.

## Maps and the KML

The offline pin set is generated, not stored — one command per trip:

```
python3 scripts/route_tools.py kml examples/japan-2026/japan.geo.json -o trip.kml
```

The output imports into Organic Maps, Google Earth, My Maps or Maps.me. `kyoto-sample.kml`
is kept in the repo as the sample of what that file looks like. Several of these plans
mention their own `<trip>.kml` in the traveller advice ("import the trip KML in Organic
Maps") — that is exactly the file the command above writes, and a real delivery ships it
next to the page; only the repo keeps it out, because it is one command away.

## The plain page and the style picker

`kyoto-sample.plan.geo.json` → `kyoto-sample.html` is the plain, un-themed page (printable,
checkbox checklist, offline route sketch per day) — the extra deliverable, not the default:

```
python3 scripts/render_plan.py examples/kyoto-sample.plan.geo.json -o kyoto.html
```

The style picker builds a one-page chooser of all eight themes: it links all eight editions
by name — `<prefix>-<theme>.html`, the same naming these examples use — and marks the ones
not on disk with `—` in the size column:

```
python3 themes/render_picker.py examples/japan-2026/japan.geo.json \
    --prefix japan --products examples/japan-2026 -o picker.html
```

## Fixtures — sub-stops and the lint's bad samples

`fixtures/substops.plan.geo.json` is a small invented plan (not advice) whose rows carry
`sub_stops`, a `view` phrase on each picture, a guided-tour row with a confirmed must-see, an
`hours` object and an `"open access"` literal, a self-drive hop (`driver: self`) with
its driving card, two `decision_points`, a `meta.review` record, a
`prefs.must_see` entry with a `view` and a hotel option's `checkout` / `bag_hold` — the fields defined
in [`../references/output-template.md`](../references/output-template.md). It is a test
input, not a showcase:

```
python3 scripts/plan_lint.py examples/fixtures/substops.plan.geo.json        # exit 0
python3 themes/render_theme2.py examples/fixtures/substops.plan.geo.json -o substops-illustrated.html
python3 scripts/render_plan.py  examples/fixtures/substops.plan.geo.json -o substops.html
```

Each of the 45 files under `fixtures/bad/` breaks exactly one default-mode rule and names
it in its `_expect` key; `plan_lint.py` must exit 1 on every one of them. `fixtures/strict/`
holds the `--strict`-only cases: `clean.plan.geo.json` exits 0 and the nine files beside
it exit 1, all run as
`python3 scripts/plan_lint.py examples/fixtures/strict/<file> --strict --ics examples/gates-sample.ics --kml examples/kyoto-sample.kml`
(the mtime WARN on the shipped `.ics` is expected). `route_tools.py links --write`
rewrites a plan in place — run it on a copy of the fixture, never on the file here (a
second run leaves the copy unchanged; the shipped good fixture is its own `links
--write` output).

Full manual for the theme system: [`../references/themes.md`](../references/themes.md);
the art.json field contract: [`../themes/ART-SCHEMA.md`](../themes/ART-SCHEMA.md).
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