hkroute

Smart public transport routing for Hong Kong with real-time bus ETAs. Queries Google Maps for transit alternatives, enriches bus legs with live arrival times...

Security Scan

The skill's code, runtime instructions, and required credential (Google Maps API key) are coherent with its stated purpose of querying Google Directions and enriching bus legs with public HK ETA data; nothing in the package indicates unexplained access or hidden endpoints.

Purpose & Capability

Name/description match behavior: the skill calls Google Directions (requires GOOGLE_MAPS_API_KEY) and the hk-bus-eta library to fetch public HK ETA data. Required binaries (node) and the single required env var are proportionate to the described functionality. The included bundle/script implements the declared features.

Instruction Scope

SKILL.md instructs running the bundled Node script and documents the network endpoints used (maps.googleapis.com and public HK ETA APIs). The runtime instructions and code only read/write a local cache (~/.cache/hk-route/etaDb.json), use the declared env var, and make network calls to the declared services. There are no instructions to read unrelated files or exfiltrate data to unknown endpoints.

Install Mechanism

No install spec (instruction-only) but a self-contained bundled script is provided (scripts/hk-route.cjs) that appears to embed its Node deps. There is no download-from-untrusted-URL behavior or extract-on-install step in the package metadata. This is low-to-moderate risk and consistent with the SKILL.md claim that no npm install is required.

Credentials

Only GOOGLE_MAPS_API_KEY is required and declared as the primary credential; this directly supports Google Directions usage. No other secrets or unrelated environment variables are requested. The code writes a cache file in the user's home directory, which is reasonable for this use case but worth noting (it does not access other credentials).

Persistence & Privilege

always is false and the skill does not request permanent platform-level privileges. It creates and updates a local cache (~/.cache/hk-route/etaDb.json) under the user's home directory, which is appropriate for caching ETA DBs. It does not modify other skills or global agent settings.

Assessment

This skill appears to do what it says: it needs a Google Maps API key and Node to run the provided bundled script, and it fetches public HK ETA data and caches it at ~/.cache/hk-route/etaDb.json. Before installing/providing your API key: (1) confirm the Google API key has only the permissions you intend (Directions API) and limit quotas where possible; (2) verify the bundle/source checksum or review the upstream repository (SKILL.md points to github.com/7ito/hkroute) to ensure the published bundle matches the upstream code; (3) be aware the skill will create/overwrite a cache file in your home directory; (4) if you will run this in a shared or production environment, consider running it with a key that has restricted usage and billing limits. Overall the package is internally consistent; if you need higher assurance, inspect the provided scripts/hk-route.cjs bundle locally before execution.

HK Route — Hong Kong Transit Routing with Real-Time ETAs

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 "<origin>" \
  --destination "<destination>"

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

Optional flags

• --departure-time "<ISO 8601 datetime>" — 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)

1. User sends /hkroute
2. Ask: "Where are you now? Send a location pin or type your location."
3. User sends a coordinate pin (e.g., 22.2822,114.1875) or text (e.g., "Tin Hau MTR")
4. Ask: "Where do you want to go?"
5. User sends destination as text or coordinates.
6. 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.