What this skill does

Finds the best public transport route in Hong Kong by combining Google Maps directions with real-time bus ETAs. Routes are ranked by effective total time (real-time wait + travel duration), not just schedule data.

Required environment

Requirement	Details
GOOGLE_MAPS_API_KEY	Google Maps API key with Directions API enabled
node >= 18	Runtime for the bundled script

External endpoints

This skill makes network requests to:

Endpoint	Purpose	Credentials
maps.googleapis.com (Google Directions API)	Transit route planning	GOOGLE_MAPS_API_KEY
HK government & operator APIs via hk-bus-eta (DATA.GOV.HK, KMB, CTB, etc.)	Real-time bus arrival times	None (public APIs)

No other network calls are made. The ETA database is cached locally at ~/.cache/hk-route/etaDb.json (refreshed every 24h).

Source code

The bundled scripts/hk-route.cjs is built from readable TypeScript source at github.com/7ito/hkroute. Build command: esbuild src/index.ts --bundle --platform=node --format=cjs.

How to invoke

node /path/to/skill/scripts/hk-route.cjs \
  --origin "" \
  --destination ""

The scripts/hk-route.cjs bundle is self-contained — no npm install needed. Just node >= 18.

Optional flags

• --departure-time "" — plan a future trip (e.g., --departure-time "2026-03-26T08:00:00+08:00")

Input formats

• Coordinates: "22.2822,114.1875" (lat,lng — no space after comma)
• Place name: "Causeway Bay", "Hong Kong Airport", "Stanley Market"
• Both origin and destination accept either format.

Conversational flows

One-shot (user provides both locations)

User: "How do I get from Causeway Bay to Stanley?" → Run the CLI with --origin "Causeway Bay" --destination "Stanley", format the output.

Multi-turn (e.g., WhatsApp via OpenClaw)

• User sends /hkroute
• Ask: "Where are you now? Send a location pin or type your location."
• User sends a coordinate pin (e.g., 22.2822,114.1875) or text (e.g., "Tin Hau MTR")
• Ask: "Where do you want to go?"
• User sends destination as text or coordinates.
• Run the CLI, format the output.

If the user provides invalid input at any step, ask them to try again with a valid location.

Implicit activation

Activate this skill when the user asks about getting somewhere in Hong Kong by public transport, even without using /hkroute. Look for intent like "how do I get to...", "best way to...", "bus from...", etc., in a Hong Kong context.

Output format

The CLI outputs JSON to stdout. Format it for the user as follows:

WhatsApp / messaging format template

🚌 Routes from {origin} to {destination}
⭐ Route 1 (Recommended) — {effective_total_min} min
{for each leg:}
  🚶 Walk {duration_seconds/60} min — {instructions}
  🚌 Bus {route_number} from {departure_stop} — Next bus: {etas[0] formatted as relative time} (then {etas[1]})
     {num_stops} stops → {arrival_stop}
  🚇 MTR {route_number} from {departure_stop}
     {num_stops} stops → {arrival_stop}
  ⛴️ Ferry ...
  🚊 Light Rail / Tram ...
📍 Route 2 — {effective_total_min} min
{same leg format}
📍 Route 3 — {effective_total_min} min
{same leg format}

Formatting rules

• Recommended route: Mark with ⭐ and "(Recommended)"
• Actionable leg: The leg with actionable: true is the one that determines when the user needs to leave. Call it out prominently: "Next bus in X min — leave now!" or "Next bus in X min — you have time."
• ETAs: Format as relative time ("in 3 min", "in 12 min"). Show up to 2 ETAs per bus leg.
• Walking legs: Always show with duration. Use 🚶 emoji.
• Transport emojis: 🚌 bus, 🚇 MTR/subway, ⛴️ ferry, 🚊 light rail/tram, 🚶 walk
• Bold: Use bold for ETAs, route numbers, and the recommended route label.
• Unavailable ETAs: If eta_source is "unavailable", show "ETA unavailable (scheduled: {departure_time})" instead of a real-time ETA.
• Schedule-only: If eta_source is "schedule", show the scheduled departure time without a real-time label.

Error handling

If the CLI returns error: true:

• NO_TRANSIT_ROUTES: Tell the user no transit routes were found. Suggest trying a different departure time or considering a taxi.
• GOOGLE_API_ERROR: Tell the user there was an issue fetching routes. Suggest trying again.
• INVALID_INPUT: Tell the user what was wrong with their input.

node /path/to/skill/scripts/hk-route.cjs \
  --origin "" \
  --destination ""

🚌 Routes from {origin} to {destination}
⭐ Route 1 (Recommended) — {effective_total_min} min
{for each leg:}
  🚶 Walk {duration_seconds/60} min — {instructions}
  🚌 Bus {route_number} from {departure_stop} — Next bus: {etas[0] formatted as relative time} (then {etas[1]})
     {num_stops} stops → {arrival_stop}
  🚇 MTR {route_number} from {departure_stop}
     {num_stops} stops → {arrival_stop}
  ⛴️ Ferry ...
  🚊 Light Rail / Tram ...
📍 Route 2 — {effective_total_min} min
{same leg format}
📍 Route 3 — {effective_total_min} min
{same leg format}