Turn travel confirmations, booking emails, tickets, meeting notes, restaurant
reservations, and ad-hoc trip details into a structured, exportable itinerary
for internal business travel.
Mental model:
Trip
└── Day
├── Stay / overnight base
├── Node 1
├── Link / route to next node
├── Node 2
├── Link / route to next node
└── Node 3
Day — date, overnight stay, day notes, time-ordered nodes.
Node — flight, train, hotel check-in, meeting, POI, restaurant,
transfer, event, ticketed attraction, free block, admin reminder, or
free-form note. Nodes carry visibility so internal, team-share, private,
and travel-admin exports can differ safely.
The source of truth is the canonical YAML (see
templates/itinerary-schema.yaml). Markdown is the default rendered format,
with optional .ics, PDF, DOCX, Google Doc, and chat-ready variants.
When to use
Use this skill when the user wants to:
Build a business-trip itinerary from forwarded or pasted emails.
Convert scattered booking confirmations into a clean day-by-day schedule.
Create a team-share or exec version of an itinerary.
Hide sensitive details before sharing.
Add travel time or map links between itinerary points.
Export to Markdown, PDF, DOCX, Google Doc, chat message, or calendar .ics.
Update an existing itinerary with new confirmations or amendments.
Do not use this skill as a full travel-management backend. If the task
requires automatic inbox monitoring, persistent multi-trip databases, live
flight status, multi-user editing, or web-app sharing, suggest a separate tool
in addition to this skill.
This skill organises and renders user-provided or tool-retrieved travel facts.
Do not claim live flight status, current prices, venue opening hours, route
duration, ticket availability, or booking availability unless those facts were
verified with an available live tool during the current task.
Reference files
This skill is split for progressive disclosure. Read the reference files when
you need depth on a topic:
templates/itinerary-schema.yaml — canonical YAML structure, the source of
truth.
references/node-types.md — full per-node-type field tables, including
flight/train-specific fields and the status lifecycle.
examples/tokyo-trip.md — end-to-end worked example: source emails →
YAML → all four export variants → .ics.
scripts/itinerary_utils.py — lightweight stdlib helpers for deterministic
chores: Google Maps direction URLs, iCalendar escaping/folding, and .ics
sanity checks. Run with python3.
Core workflow
Collect inputs. Forwarded emails, PDF confirmations, screenshots,
manual notes, an existing itinerary if updating.
Classify each item as a node. Use the type enum in
references/node-types.md.
Group into trip and day structure. Infer rough destination and date
range. Assign each node to the correct local day. Place hotel info on the
relevant nights via overnight_stay. Sort timed nodes chronologically.
Keep untimed nodes in a separate "To schedule / notes" section.
Geocode locations selectively. Geocode route-critical and share-critical
locations by default: hotels, airports/stations, meeting venues, reserved
restaurants, and booked transfers. Geocode optional POIs or every located
node only when the user asks for a map-rich / route-rich itinerary. Never
invent coordinates — see references/routing.md.
Link nodes in sequence. Add route links for high-value transitions
only (airport ↔ hotel, hotel ↔ client office, meeting ↔ important
dinner, intercity transfers). Don't route every short walk unless asked.
Flag uncertainty. Missing terminal, address, timezone, passenger
name, confirmation number, check-in time, or date. Conflicts, duplicates,
ambiguous hotel nights, ambiguous traveller assignment. Put these in
"Open Questions / Missing Details".
Produce export variants. Internal full, team-share, executive
summary, travel-admin, chat, .ics as requested. See
references/exports.md and references/privacy.md.
Output location
Save final deliverables to the user's selected folder or agreed workspace.
Working drafts and intermediate YAML can live in the scratchpad. Use the naming
convention in references/exports.md.
When presenting files, use the delivery method your environment supports:
Chat / messaging environments: send the local file directly using the platform's file-attachment mechanism.
CLI / desktop environments: provide the absolute file path or a supported local-file link.
Cloud-doc exports (Google Docs / Drive, etc.): provide the verified share URL.
Time and timezone conventions
All starts_at / ends_at / due_at values in the YAML are ISO 8601
with an explicit timezone offset, e.g. 2026-06-12T08:10:00+09:00.
For flights and trains that cross a timezone, the starts_at offset is
the departure local offset and the ends_at offset is the arrival
local offset. Also populate timezone_start and timezone_end when the
IANA names differ or when generating .ics.
Each day carries a local_timezone (IANA name). It overrides
trip.timezone_default for that day — needed when a trip crosses a
timezone boundary mid-trip.
Rendered Markdown uses 24-hour HH:MM in the local timezone of the
containing day, with the timezone shown in the day heading
(e.g. ## Day 1 — Friday, 12 Jun 2026 (Asia/Tokyo)).
For overnight or red-eye journeys, place the node on the day of
departure in Markdown and add an arrival-time admin note on the next day.
Status lifecycle (brief)
Each node has a status of confirmed | tentative | cancelled | unknown.
Default to confirmed for items built from confirmations. Use tentative
for held or "maybe" items. Never delete a cancelled node — set
status: cancelled and keep it for the audit trail; rendering hides it from
share variants and strikes it through in the internal version. Full
rendering rules and amendment handling: see references/node-types.md.
OCR and source quality
When extracting from screenshots or scanned PDFs:
Set source_item.ocr_quality to high, medium, low, or unreadable.
List uncertain fields in source_item.ocr_uncertain_fields.
For uncertain fields, leave the field empty and add to "Open Questions",
or quote what you saw with a ? prefix ("?ABC12?"). Never silently
normalise.
If a source is unreadable, do not generate nodes from it — ask the user
to re-send or transcribe.
Privacy and export variants
Always distinguish the internal full version from shareable variants.
Sensitive fields (payment, passport, loyalty, booking PINs, personal
contacts) are redacted or omitted per the matrix in references/privacy.md.
Defaults: if the user asks for "the itinerary" without an audience,
default to internal-full and ask before producing a team-share. Never
default to team-share — accidental over-sharing is worse than accidental
over-disclosure to oneself.
Routing and map links
Use a geocoding/maps tool when available (Nominatim/OSM or a maps MCP). If no
mapping tool is available, leave coordinates empty and use human-readable
addresses or codes in map links.
Geocode route-critical and share-critical locations by default: hotels,
airports/stations, meeting venues, reserved restaurants, and booked
transfers.
Geocode optional POIs or every located node only when the user asks for a
map-rich / route-rich itinerary.
Build Maps URLs using coordinates when available; fall back to URL-encoded
addresses or IATA codes. Never invent coordinates.
Route by default only for high-value transitions (see workflow step 6).
Always keep the human-readable address alongside any coordinate so the
Markdown stays readable.
Full rules: references/routing.md.
Clarification policy
Ask only when ambiguity changes the itinerary materially.
Ask if:
Two bookings conflict.
Traveller assignment is unclear (e.g. one flight, two travellers, only one
passenger named).
A hotel booking could be for different nights/travellers.
A meeting does not specify who from the travel party is attending, or who
they are meeting with (the two split fields — not the generic
participants).
A time lacks a timezone in a way that could affect sequence.
The user requests sharing but the privacy level is unclear.
A geocoder returns multiple confident matches with no clear winner.
A source has ocr_quality: unreadable.
Don't ask if:
A sensible default exists and uncertainty can be flagged in "Open
Questions".
Missing details are minor.
The user explicitly asked for a quick draft.
Common pitfalls
Overbuilding into a full app too early. Markdown + files + optional
Google Doc/PDF/.ics export is enough for internal use.
Mixing private and shareable details. Always produce separate
internal and team-share variants when exporting for others.
Over-routing every node. Route only important transitions unless
asked otherwise.
Ignoring timezones. Cross-border travel must preserve local times
and offsets at both ends.
Treating a hotel stay as a single check-in node. Also point to it via
per-day overnight_stay for each night it covers; don't create one stay
node per night.
Duplicating updated confirmations. New emails may be amendments;
compare provider, ref, date/time, and location before appending. Mark
the old node cancelled and add a private note pointing at the new one.
Forcing untimed POIs into the schedule. Keep them in optional /
unscheduled sections unless the user gave a time.
Overclaiming route accuracy. If a duration is not tool-checked,
either omit it or label it as an estimate.
Inventing coordinates. Lat/lon must come from a geocoder. A
memory-recall coordinate is worse than no coordinate.
Putting a generic participants on a meeting and skipping the split
fields. Always populate attending_from_travel_party and
meeting_with for meeting nodes.
Claiming live facts from static sources. Do not present route
duration, venue hours, availability, prices, or flight status as current
unless a live tool verified them in the current task.
Verification checklist
Before final output, check:
Trip title, date range, destination, and travel party are present or
explicitly marked unknown.
Each day has the right date, a local_timezone, and the right
overnight stay where relevant.
Nodes are chronological within each day.
Flight/train times preserve local time and timezone at both ends.
Hotel check-in/check-out dates match the nights shown via
overnight_stay.
lat/lon come from a geocoder where present; no invented
coordinates.
Important addresses and Maps links are present for high-value
transitions.
Any live status, availability, route duration, opening-hours, or price
claim is either tool-verified or clearly labelled as source-provided /
not currently verified.
Sensitive details are redacted or omitted from team-share, exec,
and chat exports per references/privacy.md.
Cancelled nodes are kept with status: cancelled, not deleted.
Meeting nodes use attending_from_travel_party and meeting_with
only — participants is empty for meetings.
Open questions are listed rather than hidden.
Output file is written to the user's selected folder and verified
readable (for .ics, BEGIN/END blocks balanced).
