Trip Preparation

Always use this prefix when calling scripts or referencing assets.

When to use

Use this skill when the user asks for any of the following:

• "Plan a walking route" or "best sights to walk"
• "What should I see in X in N hours?"
• "Make an itinerary for today / tomorrow"
• "Show viewpoints, scenic spots, and optimal route"
• "Museums + cafes + parks in one walk"
• "Sightseeing trip", "day plan", "tourist route"

What you will produce

1. Structured itinerary JSON (machine readable) — suitable for rendering in an app UI (map + stop list + durations)
2. Trip brief Markdown (human readable) — narrative summary, time-blocked plan, practical notes
3. Optional checklist — tickets, opening hours checks, reservations, local transit hints

See:

• Output schema: $SKILL_DIR/assets/itinerary.schema.json
• Trip brief template: $SKILL_DIR/assets/trip_brief_template.md

Inputs to collect

Try to collect these, but do not over-question. If missing, use sensible defaults and state assumptions.

Minimum

• Destination: city name, neighborhood, landmark, or coordinates
• Time budget: total minutes (example: 120)

Strongly recommended

• Start point (optional): hotel address, "city center", current location
• Interests (pick 2-4): views, landmarks, museums, parks, food, history, architecture, shopping, nightlife
• Constraints: mobility limits, stroller friendly, avoid hills, budget level

Nice to have

• Date + approximate start time (for opening hours checks)
• Pace (min per km). Default: 12 (about 5 km/h)

Fast path procedure

Step 1. Confirm the brief

If any of these are ambiguous, ask 1-3 short questions:

• "How long do you want to walk?"
• "What 2-3 interests should I prioritize?"
• "Start from where? (hotel / landmark / current location)"

Step 2. Run discovery

SKILL_DIR=/home/node/.claude/skills/trip-preparation
node "$SKILL_DIR/scripts/step1_discover.mjs" \
  --location "Lisbon, Portugal" \
  --duration-min 180 \
  --interests "views,food,landmarks" \
  --out /workspace/group/trip-output

Step 3. Rank and curate

SKILL_DIR=/home/node/.claude/skills/trip-preparation
node "$SKILL_DIR/scripts/step2_rank.mjs" \
  --input /workspace/group/trip-output/discovered_pois.json \
  --duration-min 180 \
  --interests "views,food,landmarks" \
  --max-selected 50 \
  --out /workspace/group/trip-output

step2_rank.mjs applies scoring, multi-source/rating boosts, pageview enrichment, and optional Claude curation when ANTHROPIC_API_KEY is available.

Step 4. Build route and final outputs

SKILL_DIR=/home/node/.claude/skills/trip-preparation
node "$SKILL_DIR/scripts/step3_route.mjs" \
  --input /workspace/group/trip-output/ranked_pois.json \
  --duration-min 180 \
  --max-stops 20 \
  --out /workspace/group/trip-output

Final outputs written to --out:

• trip-output/itinerary.json
• trip-output/trip_brief.md

All step scripts emit runtime monitoring markers on stderr in the format TRIP_PROGRESS {json} (geocoding, discovery, ranking, curation, routing, output). map-poi-agent uses these markers to send live progress updates to the chat.

Step 5. Quality checks before sending

• No duplicate places
• Total walking time fits the budget (or call out the overage)
• Stops match the user's interests
• Check summary.notes in the itinerary for any curation warnings or missing famous places
• Provide at least 1 backup option (rainy day or shorter loop)

If the user gave a date/time, also check top 2-3 places:

• Are they open? (museum closures are common on Mondays)
• Are there tickets needed? Pre-booking advised for very popular attractions?

Step 6. Deliver

Send:

• A short summary (best option, why it fits, highlights)
• The stop list with total walking time and total duration
• A few tips (best time for viewpoints, lunch timing, any curation notes)

Data sources and configuration

Default sources are open and global:

• Geocoding: Nominatim (OpenStreetMap)
• POIs: Overpass API (OpenStreetMap, with automatic fallback mirrors) + Wikidata SPARQL
• Popularity signals: Wikipedia Pageviews API (Wikimedia)
• Routing: OSRM public demo by default (replace for production)
• LLM curation: Anthropic Claude API (optional, highly recommended)

Configure via environment variables:

See $SKILL_DIR/references/data_sources.md for details and production notes.

How the enrichment pipeline improves stop quality

Wikidata sitelink counts

Each place in Wikidata has a "sitelinks" count — the number of Wikipedia language editions that have an article about it. The Eiffel Tower has 200+ sitelinks; a random café has 0. This is a strong proxy for worldwide fame and tourist interest.

Wikipedia pageview signals

For stops that have a wikipedia tag, the Wikimedia pageviews API returns monthly view counts for the last 3 months. A place with 500k+ monthly views is genuinely world-famous; one with 2k is locally known. The score boost uses a log10 scale.

Claude LLM curation

The curation step is the final safety net. Claude reviews the proposed stop list and:

• Flags stops that are not genuine tourist attractions
• Notes world-famous attractions in the area that should be considered
• Returns a ranked order by must-see value for a tourist

The curation only removes flagged stops if confidence ≥ 70%. All curation actions are recorded in summary.notes.

Common edge cases

• Tiny time budget (<= 60 min): pick 3-5 stops max, keep it compact.
• Rural areas: prefer viewpoints, trails, natural features, and historic sites.
• OSM sparse coverage: Wikidata fill-in becomes especially valuable; output will be smaller but accurate.
• Overpass API overloaded (504): automatically retries with fallback mirrors; user is notified of the switch.
• Routing failure: fall back to haversine distances and label as approximate.
• Wikidata/pageviews timeout: gracefully skipped; OSM-only result still delivered.
• No ANTHROPIC_API_KEY: LLM curation skipped; a note is added to summary.

See $SKILL_DIR/references/edge_cases.md.

How personalization works

• Interest mapping: $SKILL_DIR/assets/interests.json
• Scoring and diversity rules: $SKILL_DIR/references/scoring.md
• Each POI gets a base score by type and notability signals (OSM tags, Wikidata sitelinks, Wikipedia pageviews)
• Interest boosts are applied per the user profile
• LLM curator does a final pass on the classic variant

Safety and user trust rules

• Do not invent opening hours, ticketing, or closures.
• If you cannot verify something, say so and provide a safer alternative.
• Be transparent about assumptions (pace, start point, visit durations).
• When curation flags a stop as missing, tell the user — they may want to add it manually.

Self-test (no network required)

SKILL_DIR=/home/node/.claude/skills/trip-preparation
node "$SKILL_DIR/scripts/self_test.mjs"