English | 简体中文

Trip Planner Skill

One sentence in, a verified, hour-by-hour, bookable trip plan out — delivered as a
designed page in one of eight visual themes. An open-format Agent Skill (SKILL.md)
that runs inside whichever coding agent you already use — Claude Code, Codex, Gemini CLI,
Cursor, GitHub Copilot, OpenCode, Qwen Code, Deep Code, Goose, Kiro, Roo Code, or any
other harness that loads Agent Skills: it checks opening hours, prices and holidays with
tools instead of guessing, hands you a link for every booking, and never books or pays
for you.

Showcase

Eight themes across four real trips (two themes per trip). Every trip below was planned
end-to-end by a fresh agent session using this skill, then rendered from its plan.geo.json

• art.json; the three frames per row are the cover, one day module (what the share buttons
  export on the seven still themes) and the end of the scroll — the checklist and closing
  spread. Four of the eight pages ship verbatim under examples/; three of the
  other four render from the same example folders with one command (each example's art.json
  carries both of its trip's themes); portal additionally needs footage (see below).

illustrated — Japan · London → Tokyo → Hakone → Kyoto → Osaka (open-jaw) → London,
21–28 Nov 2026 · a painted picture-book on paper: the cover is the menu, each day a tinted
riso plate with a ghost numeral, the whole scroll exports as one long image ·
examples/japan-2026

cover	a day	the end

clay — China · New York → Beijing → Xi'an → Beijing → New York, 11–18 Nov 2026 · one
continuous claymation landscape with a road threading the milestone stones ·
render it: python3 themes/render_clay2.py examples/china-2026/china.geo.json -o china-clay.html
(Chinese-language clay example: examples/turkey-2026)

cover	a day	the end

noir — Mexico · Berlin → Mexico City → Oaxaca → Berlin, 28 Oct – 6 Nov 2026 (Día de
Muertos) · one night-negative tracking shot, monospace body, days dissolving into each
other · render it: python3 themes/render_noir2.py examples/mexico-2026/mexico.geo.json -o mexico-noir.html
(Chinese-language noir example: examples/nordic-2026)

cover	a day	the end

glass — Morocco · Toronto → Marrakech → Aït Benhaddou → Merzouga → Fes → Chefchaouen →
Casablanca → Toronto, 6–15 Nov 2026 · liquid-glass panes floating over a fixed world of
cross-fading photographs, one pane per world · examples/morocco-2026

cover	a day	the end

journal — Mexico · Berlin → Mexico City → Oaxaca → Berlin, 28 Oct – 6 Nov 2026 · a
vintage travel journal on a dark desk: tape, stamps, postmarks, polaroids, and a Day of the
Dead week planned around the crowd · examples/mexico-2026

cover	a day	the end

zine — Japan · London → Tokyo → Hakone → Kyoto → Osaka (open-jaw) → London,
21–28 Nov 2026 · torn riso-poster collage with giant vertical two-colour glyphs, built like a
photocopied fan zine · render it: python3 themes/render_zine.py examples/japan-2026/japan.geo.json -o japan-zine.html
(Chinese-language zine example: examples/vietnam-2026)

cover	a day	the end

splash — China · New York → Beijing → Xi'an → Beijing → New York, 11–18 Nov 2026 · a
game splash screen stretched into a scroll: floating day-islands under a chained sky, routed
Xi'an-first so the Wall and the Forbidden City both land on weekdays ·
examples/china-2026

cover	a day	the end

portal — Morocco · Toronto → Marrakech → Aït Benhaddou → Merzouga → Fes → Chefchaouen →
Casablanca → Toronto, 6–15 Nov 2026 · scrolling is flying: five 3D worlds in one unbroken
take, dive → frame-chained link → dive, with the day's plan laid over the footage; let go and
it holds, scroll back and it flies in reverse. The only theme that needs video (nine clips
here, rendered on a local GPU; an agent with native video generation or themes/genvideo.py
produces the same chain). Footage is not shipped with the example, so this page is
screenshots only — the motion capture below is recorded from the live page.

cover	a day	the end

Every render command, cost and file for the seven trips is listed in
examples/README.md. The plain, un-themed page — the printable
extra, never the default deliverable — looks like
examples/kyoto-sample.html (a Chinese-language sample; the
same renderer produces the English UI from a "lang": "en" plan);
themes/render_picker.py builds a style-chooser page linking every rendered edition of a
trip as <prefix>-<theme>.html.

What you get

Say "Japan, 12–15 days in October, mid budget, history and food." The skill returns:

• A route across cities — 2–3 skeletons to pick from, then real flight prices for a grid
  of dates and a train-vs-fly call for every intercity leg.
• An hour-level plan for every day — opening hours and closure days checked with tools,
  dwell times and buffers from a written scheduling method, a holiday and festival collision
  scan, and a tappable map link on every hop.
• A designed page as the deliverable, not a wall of text — the plan is rendered
  through one of the eight themed renderers above (default illustrated) into one
  self-contained, phone-friendly file: trip-<theme>.html. The seven still themes carry
  offline share-image buttons (Save this day / Save appendix / One long image;
  whole-page export on five of the eight — noir and glass export day modules only), and
  portal (video) has no share buttons — screenshot it. The plain printable page is an
  extra you can ask for.
• plan.geo.json, the single source of truth — the themed page, the map links and an
  offline KML for Organic Maps / Google My Maps all come out of that one file.
• A hotel shortlist by neighbourhood (dated deep links, not invented nightly rates), a
  budget rollup in your home currency, and a booking checklist sorted by deadline.
• Pictures, whatever your agent can do — three rungs, checked silently before the
  page style ever comes up: your agent's native image generation → your own
  OpenRouter key → the built-in stock kit. The last rung still ships a themed
  page, and says so in plain words (see No image generator? below).

What it will not do: book, pay, hold, or enter personal data. You click the links.

Quick start

1. Install — agents that support Agent Skills discover them by directory, so clone
straight into your skills folder (Claude Code's path is shown; other agents: see
Compatibility):

git clone https://github.com/skywain/trip-planner-skill.git ~/.claude/skills/trip-planner
pip3 install --user fast-flights Pillow   # optional: flight price scanner · asset pipeline

Everything else is Python 3.9+ standard library. Without fast-flights the scanner degrades
to a Google Flights link; without Pillow you can still render every theme from the shipped
picture library. If pip3 install --user is refused with externally-managed-environment
(PEP 668: Homebrew / Debian Python 3.11+), install into a python3 -m venv instead, or add
--break-system-packages.

Try it in 30 s — no key, no agent needed, from the repo root:

python3 scripts/render_plan.py examples/kyoto-sample.plan.geo.json -o kyoto.html          # the plain page (Chinese-language sample)
python3 themes/render_clay2.py examples/china-2026/china.geo.json -o china-clay.html \
  && python3 themes/qc.py china-clay.html                                                 # an English themed page + its QC (exit 0)

(For a Chinese-language themed page swap in examples/turkey-2026/turkey.geo.json; the
other six trips and their commands are in examples/README.md.)

2. Plan a trip — in your agent, one sentence. The skill triggers on its own for trip /
flight / itinerary requests, or explicitly:

/trip-planner Japan, 12-15 days in October from London, mid budget, history and food, dates ±3 days

The plan's UI language follows the language you ask in ("lang": "zh"|"en" in the plan;
--lang overrides on every renderer). Four modes are picked from what you ask:

3. The designed page — this is the deliverable the skill hands over, in the theme you
picked (default illustrated = render_theme2.py), never a plain text page. Three
commands, from the repo root (full manual: themes/README.md,
references/themes.md):

# optional: a <plan>.art.json beside the plan is picked up automatically — cover title, per-day titles, which pictures go where
python3 themes/render_<theme>.py plan.geo.json -o trip-<theme>.html   # theme2 clay2 noir2 glass2 journal zine splash portal
python3 themes/qc.py trip-<theme>.html                                # exit 0 = clean; exit code = FAIL count
themes/xprobe.sh trip-<theme>.html module '#d5' out.png              # click the real share button headlessly, look at out.png (macOS + Chrome only)

The art contract is themes/ART-SCHEMA.md; every field is optional
and an empty art file must still render. Pictures resolve --assets → art dir → plan dir →
themes/assets/.

4. Pictures and video: three rungs, best first. The skill walks this ladder itself,
silently, before it ever mentions a page style:

1. Native — the agent running the skill can already generate images or video, so it
   uses that: art drawn for this trip, no key to set up (same specs and prompts, same
   split_sheet.py → cutout.py → towebp.py → trip-manifest steps; the contract is the
   generator-choice section of themes/ART-SCHEMA.md).

2. One key — no native generation: create themes/.auth_header containing one line —
   Authorization: Bearer <your OpenRouter key> — (gitignored, read only from that
   directory; both scripts pass it to curl as a header file, so it must be the full header
   line, not the bare key). --dry-run prints the credential path it would read:

   python3 themes/gen.py <trip>/jobs.json --outdir <trip> --manifest <trip>/manifest.<trip>.json      # gpt-image-2; --dry-run first
   python3 themes/genvideo.py jobs.json --outdir <trip>/portal --manifest <trip>/manifest.<trip>.json  # veo-3.1-lite by default; --models for prices
   

3. Stock kit — neither of the above: the pictures come from the kit bundled in this
   repo, and the page is still a themed page (next block).

On every rung the shipped library comes first —
themes/assets/IMAGE-LIBRARY.md indexes 301 stems
(444 webp, 26 MB) by subject, and its rules draw the line: generic props are reusable,
while anything destination-specific (covers, hero plates, title stickers, terrain bands,
splash islands, journal photos) must belong to the trip it is on. Real costs from the
shipped examples: $0.25–0.46 of image generation per trip (7–11 gpt-image-2 calls).
The portal theme is the one that needs footage: either genvideo.py in the cloud
(google/veo-3.1-lite, 720p, ≈ $0.03/s → roughly $3 for a ten-world chain; smoke-tested
on one 4 s clip, $0.12) or a local GPU (the author's regression footage comes from ComfyUI
on an RTX 5090 via themes/build_portal_jobs.py). The shipped chain in
themes/assets/portal/ (19 clips, ~35 MB) belongs to the US trip that drove the design;
another trip needs its own.

No image generator? Still a designed page. Two commands, and the plan comes out in a
real theme instead of degrading to plain text:

python3 themes/stock_art.py plan.geo.json --theme illustrated -o plan.art.json
python3 themes/render_theme2.py plan.geo.json --art plan.art.json \
        --assets themes/assets/stock -o trip-illustrated.html   # --assets is required here

The kit (themes/assets/stock/, 80 stems / 161 webp / 5.2 MB, all in the illustrated
gouache style) holds 14 region cover paintings, 30 generic scene cut-outs and 36
world-landmark cut-outs; stock_art.py picks the cover from the destination country and
one hero per day by keyword score, leaves the words (cover title, day titles, captions) to
the agent, and writes the notice — "Pictures: built-in stock kit — no image generator or
key was available; provide one and the art is generated for this trip." — into the page's
fine print, where it must stay, and into the chat summary. Coverage: complete for
illustrated, works for clay; the other six themes need generated pictures.
Details: themes/assets/stock/README.md.

How it works

Pipeline. SKILL.md is the playbook the agent follows: Phase 0 intake (one message,
only for what is missing) → Phase 1 country brief (visa from official sources, holiday API +
a budgeted festival search, weather, money, safety) → Phase 2 route skeletons → checkpoint
→ Phase 3 flights and intercity legs (scripts/flight_scan.py) → Phase 4 city day-plans
(parallel city subagents with an explicit search budget) → Phase 5 hotels → Phase 6
assemble, adversarial self-check, deliver. Three moments with the user at most, usually
two: an intake message only when a core fact is missing and cannot be inferred, the
route-skeleton pick, and delivery.

Intake: no questions when the request already carries the facts. "Plan my Germany
trip, 1–7 Oct this year" has the destination and the dates, so nothing is asked — the
origin and the rest are inferred and listed as assumptions at the first checkpoint. Only a
genuinely missing core fact (destination, when / how long, an origin that cannot be
inferred) triggers a single intake message, and the optional preferences ride along in that
same message, each one marked skip = default: travel style (public transport ·
self-drive · group tour), lodging habit and band, scenery taste (nature / city / beach /
forest / lake / mountain), pace, party size, budget, ranked interests, date flexibility.
Whatever you answer or the skill assumes is written into the plan's prefs block
(assets/plan.example.json) so a later replan does not re-ask.
Say "just plan it, don't ask" and both the intake and the route checkpoint are skipped,
with every assumption stated at the top of the result.

One file, one truth. plan.geo.json is written once and read by everything:
scripts/route_tools.py (geocode · check · links --write · kml · sun) produces
the map links and the KML from its stops; scripts/render_plan.py produces the plain
HTML; every themed renderer reads the same file plus its art.json. That is what stops
the written plan, the map links and the pretty version from drifting apart. Schema
template: assets/plan.example.json — copy it, fill the
PLACEHOLDERs, then render (render_plan.py refuses an unfilled copy unless --force).

Hard rules (distilled from SKILL.md and references/):

1. Never books, pays, holds, or enters personal data — links and a checklist only.
2. Prices and hours come from tools, never from memory; a missing price is "—, check link".
3. Cheap before expensive: bundled scripts and keyless APIs first, browser second; never
   curl OTA or airline sites.
4. Search budgets are explicit and written into every subagent prompt.
5. Estimates stay estimates: transit durations ship as (est.) ranges unless verified.
6. Beyond ~3 months out nobody publishes that day's hours — verify the seasonal pattern,
   stamp "as of {date}", put a re-confirm task on the checklist.
7. The plan must survive the self-check before delivery: closure scans, chain arithmetic,
   last-entry times, walking totals, open-jaw consistency.

Data sources — all keyless and free; prices are comparison-grade and the deep links
in the plan are the source of truth (references/data-sources.md):

Hotels have no usable keyless API, so the skill recommends neighbourhoods and produces
dated deep links rather than quoting a nightly price it cannot verify.

Compatibility

• Format, not a product integration. This is an Agent Skill
  — an open format: a SKILL.md playbook plus references/, scripts/ and themes/.
  Any harness that loads Agent Skills can load this one; nothing here is tied to one
  vendor's agent.
• The agents. Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, OpenCode,
  Qwen Code, Deep Code (DeepSeek), Goose, Kiro and Roo Code all declare support for
  SKILL.md skills, and the scripts here are stdlib-only Python 3.9+. The only difference
  between them, from this repo's point of view, is where they expect skills to live — so
  the git clone target in Quick start is the one line you adapt.
• Verified in Claude Code; the rest are untested. Every trip, render and export in
  this repository was produced in Claude Code, and the install path above is its skills
  directory. We have not run the other harnesses one by one — reports welcome,
  including the skills directory each one expects.
• What the harness needs. A shell that can run Python 3.9+ (the scripts), and web
  search / fetch tools (the country brief, day plans and hotel phases verify hours, prices
  and holidays online). Nice-to-have: subagents (Phase 4 fans out one agent per city — a
  harness without them plans the cities in sequence), a browser tool (the flight and hotel
  price fallbacks when the keyless scripts fail), and native image / video generation (else
  an OpenRouter key, else the bundled stock kit — the page stays themed either way).
• Any model. The skill is instructions plus scripts; whatever model your harness runs
  (Claude, GPT, Gemini, Qwen, DeepSeek, Mistral, …) executes it. Stronger models follow the
  verification rules more faithfully; the scripts behave the same regardless.
• Native generation is optional. Pictures and portal footage use the agent's own image /
  video generation when it has one; otherwise themes/gen.py / themes/genvideo.py with a
  single OpenRouter key; otherwise themes/stock_art.py and the bundled stock kit.
  Rendering from the shipped library or the stock kit needs no key at all.

Repository layout

README.md  README.zh-CN.md    this page, English and Chinese
THIRD-PARTY-NOTICES.md        license texts for the redistributed font and icons (Caveat OFL, Lucide ISC)
SKILL.md                      the playbook: phases, hard rules, quick modes
references/
  data-sources.md             every API + URL recipe, with fallback chains
  scheduling.md               dwell times, buffers, day types, traps, verification list
  navigation.md               map links, hop-row format, verify-vs-estimate policy
  country-quick-notes.md      per-country passes, sell-outs, closure patterns (+ "destination not listed" checklist)
  output-template.md          the city-block hand-off + final deliverable structure
  cover-titles.md             bilingual poetic cover-title library + cliché blacklist
  themes.md                   themed-render manual: the eight themes, adding one, defect checklist
  art-schema.md               pointer to themes/ART-SCHEMA.md
scripts/
  flight_scan.py              Google Flights grid scanner (keyless, centre-out)
  route_tools.py              geocode → distance check → map links → KML → sun times
  render_plan.py              plan JSON → self-contained printable HTML
themes/
  README.md                   what is here, the three commands, where pictures come from
  render_theme2.py …          eight renderers: theme2 (illustrated) · clay2 · noir2 · glass2 · journal · zine · splash · portal
  render_picker.py            style-chooser page (links <prefix>-<theme>.html)
  theme_common.py             shared helpers, i18n, the offline share-image engine
  qc.py  xprobe.sh  xt.sh     static QC · headless export probes
  gen.py  genvideo.py         fallback generators (OpenRouter gpt-image-2 / video, one key) for agents without native generation
  stock_art.py                no generator, no key: builds the picture side of art.json from the stock kit
  towebp.py cutout.py split_sheet.py build_manifest.py build_portal_jobs.py
                              asset pipeline (png→webp, cut-outs, sheet splitting, manifest, portal jobs)
  ART-SCHEMA.md               the art.json contract (the only copy)
  assets/                     picture library: 444 webp (301 stems), Caveat font, manifest.json,
                              IMAGE-LIBRARY.md (index by subject), portal/*.mp4 (19 clips)
    stock/                    the stock kit: 14 region covers + 66 cut-outs (161 webp, 5.2 MB),
                              index.json (lookup: archetypes, 225 ISO2, keywords, notice), README.md
assets/plan.example.json      schema template — copy it, fill the PLACEHOLDERs, then render (or --force to preview)
examples/
  README.md                   the seven trips: themes, routes, costs, every render command
  japan-2026/ …               one folder per trip: <trip>.geo.json + <trip>.art.json + <trip>-<theme>.html
  kyoto-sample.*              the plain page's sample plan, its HTML and its KML
docs/
  showcase/                   README images (hero grid, per-theme cover / day / end frames, portal motion capture)
  verification.md             how the skill was hardened, and what the reviews caught
  KNOWN-ISSUES.md             30 defects and hard limits (29 open / planned, 1 resolved), each with a source pointer, plus the roadmap

Not in the repo: personal trip data (trips/), PNG originals, and the OpenRouter
credential file themes/.auth_header that gen.py / genvideo.py read.

Verification

• Static QC — themes/qc.py page.html checks the offline contract (no network, no
  external fetches), no-JS survival, print, focus order and link hygiene; exit code is the
  FAIL count. The seven themed examples re-render byte-identically from the commands in
  examples/README.md and pass; the plain render_plan.py page
  (examples/kyoto-sample.html) passes too.
• Export probes — themes/xprobe.sh / xt.sh drive a headless Chrome to click the
  page's real share button and write the image it produces, so export defects are seen,
  not assumed. macOS with Google Chrome in /Applications only (the path is hardcoded in
  the probes). Run them serially.
• Friction testing — the most valuable technique: give a fresh agent that has never
  seen the skill a real trip request, let it follow the instructions in order, and treat
  every place it got confused as the primary deliverable. Nine test trips (Australia,
  Nordic, Japan, China, Italy, Mexico, Morocco, Turkey, Vietnam) were planned this way,
  each by a fresh agent session, on top of the earlier Kyoto and Rome runs; the friction
  points became rules in references/ and entries in country-quick-notes.md.
• Adversarial review — three rounds by seven independent agents (script torture-tester,
  external fact-checker, tour-leader realism attacker, cross-file coherence reviewer, two
  end-to-end builders). What they caught, and the rules that came out of it:
  docs/verification.md.

Status and known issues

Working, personal-use software under active development, and harness-agnostic on
purpose: an Agent Skill, not a Claude Code plugin — verified end-to-end in Claude Code,
expected to run in the ten other agents listed under Compatibility, and
untested there until someone files a report. Every defect and hard limit in the current
tree is listed in docs/KNOWN-ISSUES.md — 30 entries (29 open or
planned, 1 resolved) across export/renderers, planning scripts, assets and scope, each with
a symptom, workaround and source pointer, plus a short roadmap (whole-page export sizing,
journal zh cover fix, picker copy, a portrait portal chain, a post-trip photo album,
affiliate rails for a hosted version).

Requirements. Python 3.9+ (macOS system Python is fine); standard library only,
except optional fast-flights (flight scanner) and Pillow (asset pipeline: towebp.py,
cutout.py, split_sheet.py, gen.py). gen.py / genvideo.py need themes/.auth_header
(one line: Authorization: Bearer <OpenRouter key>) — and only when the agent has no native
image/video generation of its own; with neither, stock_art.py and the bundled stock kit
still produce a themed page. The export probes need macOS with Google Chrome in
/Applications (path hardcoded). Rendering any theme from the shipped library or the stock
kit needs none of these.

Limitations and non-goals.

• Personal-use posture. The browser and scraping steps are what one traveller would do
  by hand. A hosted service for others would need affiliate rails (Travelpayouts, an
  Amadeus production key, Viator/GetYourGuide APIs) — the free sources here are not
  licensed for redistribution.
• Not real-time. It plans; it does not track delays or rebook.
• Prices move. Every figure carries an as-of date for exactly that reason.
• Portal needs footage you generate or render yourself; the shipped chain is one trip's.

Contributing

Issues and pull requests are welcome. The four most useful contributions:

• A compatibility report — run the skill in a harness other than Claude Code and tell
  us what worked, what did not, and where that harness expects skills to live.
• A new country — add a section to
  references/country-quick-notes.md following the
  "Destination not listed?" checklist at the top of that file (passes, sell-outs, closure
  patterns, holiday feed gaps), ideally after planning a real trip there with the skill.
• A new theme — read references/themes.md §4 (adding a theme)
  and §5 (the recurring-defect checklist, every item on every new theme); the art contract
  is themes/ART-SCHEMA.md, and shared helpers live in themes/theme_common.py.
• A friction report — plan a trip with the skill as a first-time user and file every
  place the instructions fought you. That is how most of the current rules were found.

Before opening a PR: python3 themes/qc.py on any themed page you rendered (exit 0), one
xprobe.sh export looked at with your own eyes, and re-render one of the examples/
trips to confirm it is still byte-identical.

Credits

• Caveat (SIL Open Font License 1.1) — the handwriting
  webfont embedded in the journal theme (themes/assets/caveat-vf.woff2).
• Lucide (ISC) — the icon sprite in themes/lucide-icons.json.
  License texts for both: THIRD-PARTY-NOTICES.md.
• OpenStreetMap contributors and
  Nominatim — geocoding, under
  its usage policy (1 req/s, identifying User-Agent).
• sunrise-sunset.org — sun times; attribution is required
  wherever the data is shown, and the rendered plan pages print it in the footer.
• Nager.Date, Open-Meteo,
  frankfurter.dev, open.er-api.com
  — holidays, weather, FX.
• Generated pictures: openai/gpt-image-2 via OpenRouter.
  The shipped portal clips (themes/assets/portal/, 19 mp4) and the Morocco portal footage
  in the showcase were rendered locally with MiniMax-H3 in ComfyUI; the cloud alternative
  in genvideo.py is google/veo-3.1-lite (default) or minimax/hailuo-3 via OpenRouter.

License

MIT — see LICENSE. © 2026 skywain.