travel-plan-viz: a Claude Code and Codex skill that turns an itinerary into one offline HTML file

The problem: good itineraries die inside chat windows

Ask a general assistant for a four-day Hong Kong plan and you get prose. It reads well at the desk and is useless at the airport gate, because it lives in a conversation you have to scroll, it needs a network to reload, and the parts that matter on the ground (which stop is next, when the ticket window closes, which train to book) are buried in paragraphs. travel-plan-viz targets that gap. According to the README, the skill takes either a bare destination plus a day count or an itinerary you already have, researches the web, and emits a single .html file that is mobile-first and offline readable for the text portions. The audience is narrow and specific: people who already run an agent with a skills directory, and who want the artifact rather than the answer. The README frames the origin as an upgrade of the community "vibe coding travel guide" pattern into a reusable skill that freezes the error-prone logic. That framing matters, because the project's real claim is not that an AI can plan a trip. It is that the mechanical parts of presenting a trip should not be re-improvised by the model every time.

Fixed engines, regenerated design: the actual architecture

The repository splits the work in two. Mechanical logic lives in three plain JavaScript files under travel-plan-viz/assets/: map.js handles Leaflet markers, the dashed ordered route, navigation deep links and GCJ-02 to WGS-84 coordinate correction; reminders.js computes booking deadlines and renders the checklist and badges; validate.js is a contract checker that runs after generation and flags missing fields, out-of-range or outlier coordinates, and absent required blocks. The README states that an ERROR from validate.js must be fixed, which is the closest thing here to a test gate on model output. The second half is deliberately not fixed. SKILL.md orchestrates mode detection, research and generation, and a design step produces the visual layer each time. page-contract.md tells that design step which data each block needs, research-guide.md defines what to look up (coordinates, images, opening hours, weather, transport, with the note that images must be verified as loadable and that ticket prices are not to be queried live), and design-guidelines.md is the fallback aesthetic when no external design skill is installed. The stated reason for the split is that visual presentation benefits from regeneration while coordinate math and date arithmetic do not. Two soft dependencies follow from this: frontend-design or huashu-design, if present, gets called for the visual pass, and separately installed official travel skills from the likes of Fliggy, Amap, Tencent Maps or Didi can supply live flights, hotels, routing and weather. The README is explicit that neither is required and that the real-time accuracy of that third-party data belongs to those skills, not to this one.

Installing the skill and generating a first itinerary

There is no package to install and no server to run. The README's quick path is a symlink from the cloned repository into the agent's skills directory, one line per agent. Run the one that matches your tool; the -sfn flags replace an existing link rather than nesting a new one inside it.

# Claude Code
ln -sfn "$(pwd)/travel-plan-viz" ~/.claude/skills/travel-plan-viz
# OpenAI Codex
ln -sfn "$(pwd)/travel-plan-viz" ~/.codex/skills/travel-plan-viz

After that, the skill is invoked by ordinary language rather than a command. The README gives two phrasings, one for planning from nothing and one for converting a plan you already wrote.

帮我做香港 4 天 3 晚的旅行计划          # 模式 A：从零规划

这是我的行程<贴上文字/HTML>，帮我做成网页   # 模式 B：已有计划

Expect a single .html file at the end of the run, not a directory of assets. Open it in a browser: the README describes a numbered Leaflet map with a dashed route in order, a per-day timeline split into morning, midday and evening with a photo, rating and one-line note per stop, a top-of-page to-do checklist with booking deadlines counted back from the departure date, and sections for weather and packing notes, candidate flights, hotel districts at three price tiers, and per-meal food suggestions. The map and images need a network; the text itinerary does not. If you want to inspect the engines before trusting them, the repository ships unit tests and the README gives the command.

node --test test/*.test.js

Four generated pages sit in samples/ and open directly in a browser, including a Tokyo 5-day example produced in mode B from a rough plan. Iteration is the part worth noting: the full itinerary JSON is embedded in the page, so handing the HTML back and asking to move a stop from day three to day four changes data and re-renders, and the README claims fields are not dropped in that round trip.

Where the design breaks down

The offline claim is narrower than the phrase "offline readable" suggests on a skim. The README says the text itinerary is readable offline while the map and images need a connection, and that failures degrade gracefully instead of showing broken images. So the page you carry onto a plane is a timeline and a checklist, not a map. That is a reasonable trade, but it means the Leaflet layer is not a navigation fallback on its own.

Freshness is the second boundary, and the project mostly owns up to it. The README states that ticket prices are not to be queried live during research, that all page content is AI-assembled from public sources and may be inaccurate or outdated, and that the page carries a disclaimer pointing users to official apps. When optional official travel skills are installed, the README assigns responsibility for the real-time accuracy of flights, hotels, routing and weather to those skills. Read that as a division of liability, not a guarantee: without them, the flight and hotel sections come from web research with no live feed behind them.

The coordinate correction is the sharpest limitation, because it is the one place where a silent error survives into the output. The README states that GCJ-02 coordinates from Amap or Tencent are converted to WGS-84 automatically, and that overseas coordinates are already WGS-84 and need no correction. The correction path therefore depends on knowing the source of each coordinate. validate.js catches out-of-range and outlier coordinates, which the README describes as aimed at swapped latitude and longitude or a wrong city, but an outlier check cannot tell you that a point is offset by a few hundred metres. If you are using the map to walk between stops, spot-check markers against a known landmark before you leave.

Finally, the tool is the wrong shape for anyone who wants a shared, updatable plan. There is no hosting, no sync and no multi-user editing; the artifact is a file you pass around. If two people need to edit the same trip, this is not it.

How it differs from asking a chat model, or from a hosted planner

The obvious comparison is a plain prompt to a general assistant: "write me a Hong Kong itinerary." The difference is not the itinerary text, which both produce. It is what happens after. Here the itinerary becomes data embedded in a page, and three engines handle the parts a model tends to get wrong across runs: Leaflet marker and route rendering, deadline arithmetic counted back from the departure date, and a post-generation contract check. The README also describes a second pass in mode B, where a plan you supply gets compared against a "complete itinerary" checklist and a small number of optional suggestions are offered. That is the distinction the project itself draws against a pure prompt-to-HTML conversion.

The other comparison is a hosted trip planner or a notes app with a map view. Those give you sync, sharing and an editor, and they keep working when you switch phones. travel-plan-viz gives you a file with no account, no API key for the map (the README notes Leaflet with free tiles), and no dependency on a service staying up. The cost is everything the hosted tools do for you: no live prices, no booking, no collaboration, and no server-side update if a restaurant closes. Pick this when the value is in a durable, self-contained artifact you generated once; pick a hosted planner when the value is in data that stays current and is edited by several people.

Maintenance, upgrade cost and the MIT licence

The repository was last pushed on 2026-09-16 and is not archived, so it is current as of writing. There are no releases, which means there is no version number to pin and no changelog to read before upgrading. Upgrading is therefore a git pull in the cloned directory. Because the agent's skills directory holds a symlink rather than a copy, a pull takes effect immediately with no reinstall step, and the engines under assets/ are loaded from that same working tree. That is cheap, and it is also the risk: there is no released artifact to fall back to if a pull changes behaviour mid-trip. If you depend on a generated page, keep the HTML file itself, since it is self-contained and does not read from the repository at view time.

The project is MIT licensed, which the README summarises as free to use, modify and commercialise with the copyright notice retained. Two things to keep separate from that licence. First, generated pages embed map tiles from OpenStreetMap and photographs pulled from the web during research; the MIT grant covers the skill's code, not the rights in that third-party imagery. Second, the optional official travel skills are separate products under their own terms. This is a description of what the repository states, not legal advice; check the terms of any image or data source you redistribute.

Editorial conclusion

Adopt it if you already drive Claude Code or Codex and want the output of a trip conversation to survive as a file you can open on a phone with no network. Skip it if you need a hosted planner, live prices, or a tool your non-technical relatives can install on their own, since setup is a symlink into ~/.claude/skills or ~/.codex/skills. Before trusting a generated page, open samples/hongkong-4d3n-real.html and check two things yourself: that the numbered markers sit on the right city, and that the departure-date countdown in the top checklist matches your actual travel date.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. zexuanw958-svg/travel-plan-viz on GitHub