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-0-intake.md

View on GitHub
# Phase 0 — Intake (the procedure)

Read this at the start of Phase 0, before you decide whether to ask the user anything.
SKILL.md Phase 0 is the contract — inputs, outputs, and the gates that decide pass/fail;
this file is the whole procedure it points at: what counts as a core fact, how origin
is inferred, the intake message format and its rules, what goes into `prefs`, the
picture-capability check, the style line and the plan language.

Inputs: the user's request (and anything said earlier in the conversation). Outputs:
the plan's top-level `prefs` block and `lang`, the picture mode (`prefs.pictures`), the
assumptions block for checkpoint (a) — and at most one intake message.

## Read the request first — one message, or none

**Read the request before deciding whether to ask anything.** Most requests already carry
what matters — "帮我安排今年 10.1 到 10.7 的德国之旅" has the destination and the dates,
and gets **zero questions**: infer the rest, list the assumptions in one block at the top
of checkpoint (a), and move. Ask only when a *core* fact is missing **and** cannot be
inferred — and then ask for everything in ONE message in the **intake format** below,
under four rules: (1) core first, optional after; (2) **only the items the user has not
already answered** — anything stated in the request (destination, dates, party, "自驾",
a style name, a budget) is settled and must not reappear as a question (a "自驾"
reopens only when the driving card reads not legal / unverified — phase-1-brief.md
§Driving card step 4); (3) **each
optional line carries its default**; (4) **one "all defaults" escape hatch** (the 💡 line).

## Core and optional facts

**Core** — must be known or defensibly assumed:
- **Origin** (city/airport). Missing → infer from the conversation language, the user's
  locale/timezone or anything said earlier, pick that city's own international airport
  (language or locale alone names a country, not a city: take that country's largest
  international gateway — Brazil → São Paulo GRU, Mexico → MEX, Japan → Tokyo HND / NRT,
  mainland China → Shanghai PVG — unless a city was mentioned, and say so) and state it
  as an assumption; it costs one line to fix at checkpoint (a) and a whole round trip to
  ask. Genuinely unguessable → it is the one core question.
  A city named anywhere in the request ("我住在圣保罗", "from Toronto") overrides the
  language inference: a Chinese-language request from someone living in São Paulo
  departs GRU, never PVG. When a city is known, the hub is *that city's* main
  international airport, not the country's biggest — the ones that recur:
  São Paulo GRU (GIG is Rio) · Buenos Aires EZE · Mexico City MEX ·
  Shanghai PVG · Beijing PEK / PKX · Guangzhou CAN · Shenzhen SZX · Hong Kong HKG ·
  Taipei TPE · Singapore SIN · Seoul ICN · Tokyo HND / NRT · Sydney SYD · Melbourne MEL ·
  Toronto YYZ · New York JFK / EWR · London LHR · Paris CDG · Frankfurt FRA · Dubai DXB.
  A city not on this line: look its airport up; never guess it from the country.
- **Destination** (country, city or a shortlist). Missing → ask; nothing to plan without it.
- **When / how long** (dates, or a duration + rough month + flexibility). Missing → ask.
- **Page style** — one of the eight themes (Phase 6). Default: **illustrated 插画版**.
  Before you mention styles at all, run the **picture-capability check** below — its
  result decides what you say about pictures.

**Optional** — ask them in the same message only when you are already asking; never
send a message just for these. Unanswered → default, and the assumptions block says so:
- travel style: self-drive · group tour · public transport + walking (default: public
  transport where it reaches the anchors. **A car-first segment gets no default —
  neither self-drive nor a tour**: `travel_style` is `mixed`, `notes` names the
  undecided segment, and Phase 2 shows it as the priced pair of phase-3-legs.md
  §Driving legs)
- drivers, only when a self-drive option exists: who drives and the country that issued
  each licence — the licence, not the passport (default: one driver, licence from the
  origin country — inferred and stated, never a fifth core question)
- languages the party can follow spoken commentary in (default: the language the user
  wrote in, and only that — reading English pages is not following a guide in English)
- lodging habit: hotel · hostel · B&B / guesthouse · apartment · ryokan/onsen-style
  stays, and the band (default: mid-range hotel, refundable)
- scenery taste: scenery/nature · city · beach · forest · lake · mountain (default: read
  from the destination + interests)
- party size & mobility (default: 2 adults, no kids) · budget style or number (mid) ·
  interests ranked (food/history/nature/anime/hiking/shopping/photography/nightlife) ·
  pace 2/3/4 anchors per day (3) · ±day flexibility (±2) · passport nationality
  (visa! infer from origin, state it) · locked must-sees, each scenic one with the
  picture expected, in a short phrase — any angle, side, level, composition or detail
  (default: its best-known picture, stated as an assumption — a boardwalk past a feature
  and the overlook above it are different must-sees).

## The intake message

**Intake format** (user's language; markdown; full zh/en samples in
references/output-template.md §Intake message). Keep it to one screen:

```
**先确认几件事 —— 一条消息回我,写序号+答案;没写的按默认**

**必答**
1. 出发城市 —— 我猜是上海(你用中文问的),对吗?
2. 玩多久、大概什么时候 —— 例:10.1–10.7,或「7 天 · 10 月 · 前后可挪 2 天」

**选答(不答走默认)**
3. 页面风格:插画(默认)· 黏土 · 夜航 · 玻璃 · 手账 · Zine · 闪屏 · 穿越 —— 样子见 https://skywain.github.io/trip-planner-skill/
4. 出行方式:公共交通+步行(默认)· 自驾 · 跟团
5. 住宿:中档酒店(默认)· 青旅 · 民宿 · 公寓 · 温泉旅馆
6. 偏好:城市 · 自然风光 · 海滩 · 森林 · 湖泊 · 山 —— 默认按目的地定
7. 人数 / 预算 / 节奏:默认 2 成人 · 中档 · 每天 3 个主要点

ℹ️ 本次会话没有生图能力,页面会用内置插画素材(仍是成品页,只是不如定制图贴合);有 OpenRouter key 的话放进 themes/.auth_header 再告诉我,就能为这趟生成。
💡 回「默认」= 全部按默认,直接开工。
```

Rules for the block: numbering runs continuously over whatever is left; a heading with
nothing under it is dropped; the ℹ️ line appears only in stock mode (Picture-capability
check below), the 💡 line only when at least one optional item is shown; a guessed core
value is asked as a confirmation ("我猜是 X,对吗?"), not as an open question; on a
car-first destination the travel-style line names no default ("自驾 · 跟团 —— 不答 =
两种都报价,你来选"); never more than one message, never a follow-up "just one more
thing". English sample: output-template.md. The same facts, answered or defaulted, go
into `prefs` next.

## `prefs` and the assumptions block

Write what you learned or assumed into the plan's top-level `prefs` block
(`assets/plan.example.json`: `theme`, `pictures`, `travel_style`, `lodging`, `scenery`,
`pace`, `budget`, and `notes` — the inferred values in one line, e.g. "assumed origin
PVG (zh request, no origin given)"; the assumptions block at checkpoint (a) is written
from it) so Phases 2-6 read one place and a later replan does not re-ask. Three more
keys, each only when something reads it:
- `drivers` — whenever a self-drive option exists: a list of
  `{"who", "licence_country"}` (ISO2 of the issuing country), one per intended driver;
  `brief.driving` checks each licence (phase-1-brief.md §Driving card).
- `languages` — whenever a guided option may be priced: the language codes the party
  can follow spoken commentary in (read in phase-3-legs.md §Driving legs and
  data-sources.md §Group tours).
- `must_see` — whenever a must-see is locked: a list of `{"name", "view"}`, one per
  must-see. `name` is the sight's own name as a timeline row's `what` will carry it, in
  `plan.lang`, without view words; `view` (free text in `plan.lang`: the picture the
  traveller described, or the one assumed) only on a scenic one, told or assumed and stated. Phase 4 carries
  each entry with a `view` as a `must: true` sub-stop with `view` and `stand`
  (output-template.md §city-block), and `plan_lint.py` FAILs an entry with a `view` that no such sub-stop
  matches (it checks presence; it never compares the phrases). A must-see
  the traveller drops, or a picture the operator refused in writing, edits or removes
  the entry's `view` and writes the `decisions[]` row — the gate never relitigates a
  recorded decision.
`notes` names the locked must-sees and marks which views were assumed — the list itself
is `must_see`.

## Picture-capability check

**Picture-capability check** — silent, once, before styles come up:
1. You have a **native image-generation tool** → bespoke art for this trip, nothing to
   configure (`prefs.pictures = "native"`).
2. Else `<skill>/themes/.auth_header` exists (`test -s`; never read, print or copy it) →
   `gen.py` over OpenRouter with the user's key (`"key"`).
3. Neither → **the page still ships in a theme** (Phase 6 — a plain text page is never
   the deliverable): the built-in **stock kit** (`themes/assets/stock/`) supplies the
   pictures (`"stock"`). Tell the user once — in the intake message if you are sending
   one, otherwise in the assumptions block at checkpoint (a): *"No image generator is
   available in this session, so the page will use the built-in stock illustrations —
   still a designed page, just less bespoke. If you have an OpenRouter key, put it in
   `themes/.auth_header` (one line: `Authorization: Bearer <key>`) and tell me; then I
   generate the art for this trip."* Never ask for a key in the chat, never handle one.
   `prefs.pictures` records how the pictures were **actually** produced, not what the
   check found: a session that ran `stock_art.py` sets it to `stock` before rendering,
   whatever `.auth_header` said — the chat summary's picture notice keys off it.
4. **Stock mode covers two themes only**: complete for **illustrated** (default), works
   for **clay** (built-in terrain kit); the other six themes need generated pictures —
   a user asking for one of those in stock mode is told so and offered illustrated instead.

## Style line and plan language

Style, when you do ask, is one line: the eight names with the showcase link
(https://skywain.github.io/trip-planner-skill/; offline: render
`themes/render_picker.py`), "skip = illustrated". Set the plan's top-level `"lang"` (`zh` | `en`,
output-template.md §Plan language) from the language the user asked in — the rendered
pages' UI follows it; `--lang` overrides. `lang` covers the page chrome only: **every
content string you write into the plan — day titles, notes, tips, checklist rows,
decisions, hotel blurbs — is in the user's language too.** The research sources are
mostly English and will drag your prose toward English if you let them; a zh user
receiving an English page is a shipped bug, not a style choice (self-check row, Phase 6).

## Exit criteria — tick every line before Phase 1

- [ ] At most one intake message was sent, in the intake format, and only for a core
      fact that was missing AND could not be inferred; nothing the user already stated
      was asked again; no follow-up question.
- [ ] Origin, destination, dates / duration and page style are known or defensibly
      assumed, each assumption written for the checkpoint (a) block.
- [ ] `prefs` carries theme · pictures · travel_style · lodging · scenery · pace ·
      budget · notes (the inferred values in one line) — plus `drivers` when a
      self-drive option exists and `languages` when a guided option may be priced;
      `lang` is set from the user's language.
- [ ] No car-first segment was defaulted to self-drive or to a tour; every locked
      must-see is a `prefs.must_see` entry, each scenic one with its `view`, told or
      assumed and stated (an assumed view marked in `notes`).
- [ ] The picture-capability check ran silently before styles were mentioned;
      `prefs.pictures` ∈ native | key | stock, and in stock mode the user was told once
      with the exact notice; no key was asked for or handled in chat; a non-illustrated /
      clay theme requested in stock mode was redirected to illustrated.
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