BVG (Berliner Verkehrsbetriebe) Route Planner

Route planning for Berlin public transport (BVG) using the v6.bvg.transport.rest API. Use when the user asks for: (1) route suggestions between two addresses or stops, (2) live next-departure info for a stop, (3) arrival-time–based journey planning (arrive-by or depart-at). Supports outputting 2–3 options ranked by travel time, transfers, and walking, and returning step-by-step directions and refresh tokens for live updates.

Security Scan

The skill's purpose (BVG routing) matches its instructions, but there are several coherence issues (undeclared runtime binaries, an inconsistent IBNR description, and SKILL.md vs script mismatches) that should be clarified before trusting or installing it.

Purpose & Capability

The name/description say it will call the v6.bvg.transport.rest API for journeys, departures, and refreshes — and the SKILL.md and references describe exactly those endpoints. The claimed capability (route planning for Berlin) is consistent with the code and documentation.

Instruction Scope

SKILL.md stays within the BVG API surface and does not request unrelated files, env vars, or external endpoints. However, the SKILL.md includes implementation guidance (resolve stops to base IBNR, use refreshToken, prefer stop IDs, etc.) that the provided script does not fully implement (the script directly calls /journeys with the raw from/to and does not perform a /stops or /locations lookup nor implement refresh behavior). This is a scope mismatch between instructions and the helper script.

Install Mechanism

The skill has no install spec (instruction-only), but the included script requires runtime binaries (python3 for URL encoding, curl, and jq) which the skill metadata does not declare. That mismatch can cause runtime failures and indicates the metadata is incomplete. No remote download/execute URLs are used, so there is no high-risk installer, but undeclared dependencies are a practical issue.

Credentials

The skill requests no environment variables or credentials (the API is public and no auth is required according to references). No secrets or unrelated credentials are requested. This is proportionate to a public transit routing skill.

Persistence & Privilege

always is false and the skill does not request persistent system privileges or claim to modify other skills or global agent settings. It does not store credentials or request special config paths.

What to consider before installing

What to consider before installing/using this skill: - Missing runtime dependencies: The bundled script uses python3 (for URL encoding), curl, and jq, but the skill metadata lists no required binaries. Ensure your environment provides python3, curl, and jq or the script will fail. Ask the author to declare these in the metadata or provide an install step. - IBNR inconsistency: SKILL.md says "base IBNR codes only (6 digits)" but the example given (900110001) is not 6 digits. This is a documentation bug that can cause incorrect stop IDs to be used. Confirm with the author which ID format the API actually expects and update the docs or the code. - Script vs docs mismatch: The README/ SKILL.md recommends resolving names to stop IDs (/stops or /locations), using refresh tokens, and adding entrances=true when needed. The provided scripts/journeys.sh is a minimal wrapper that skips the /stops resolution and does not implement refresh handling. If you rely on the skill to automatically resolve names to deterministic stop IDs or to refresh journeys, request an updated implementation. - No obvious exfiltration or secret requests: The skill only calls the public v6.bvg.transport.rest API and does not attempt to read files or environment secrets. There are no suspicious remote install URLs. That limits security risk, but the metadata omissions and doc inconsistencies reduce trustworthiness. Recommendations: - Ask the publisher to (1) declare required binaries (python3, curl, jq) in the metadata or provide an install spec, (2) fix the IBNR description and examples, and (3) align the helper script with SKILL.md guidance (resolve stops, support refresh tokens, or clearly mark the script as a minimal example). - If you will run the included script, do so in an environment where you control/examine inputs and have the required binaries installed. If you need a fully-featured skill, request an updated release that addresses the points above.

BVG Route Planner Skill

Purpose

• Provide concise, actionable public-transport directions in Berlin using the v6.bvg.transport.rest API.

When to use

• User asks for directions between two places in Berlin (addresses, stop names, or coordinates).
• User asks for next departures from a stop/station.
• User requests to arrive by a specific time (arrive-by) or depart at a specific time.

Core behavior

1. Resolve from and to into either stop IDs (preferred) or address/POI objects using GET /locations or /locations/nearby.
2. Call GET /journeys with arrival or departure parameter as requested, request results=3 and stopovers=true to construct step-by-step legs.
3. Format 2–3 options: show total travel time, number of transfers, walking time, and estimated departure/arrival times.
4. Provide step-by-step instructions for the selected journey: walk to stop A (distance/time), take line X toward Y, get off at stop B (platform if available), final walk to destination.
5. When appropriate, include the journey refreshToken and a GET /journeys/:ref refresh step to update realtime delays.
6. For simple next-departure queries, use GET /stops/:id/departures with duration=20 (or configurable) and return the nearest 3 departures.

Outputs

• Human-readable routes with departure times, transfers, walking distances, estimated arrival, and concise step list.
• Machine-friendly JSON (optional) containing journey id, refreshToken, legs, and stop IDs for programmatic refreshes.

References

• The skill expects to use the v6.bvg.transport.rest API (https://v6.bvg.transport.rest/api.html). See references/API.md for summary and examples.

Examples (triggers)

• "How do I get from Invalidenstraße 43 10115 to Leibnizstraße 62 by public transport?"
• "When is the next U-Bahn from U Rosenthaler Platz?"
• "Find journeys that arrive at Deutsche Oper by 17:50 tonight, fastest option first."

Notes for implementers

• IBNR format (CRITICAL): The /journeys endpoint requires base IBNR codes only (6 digits), not the full ID with :: suffixes.
  • ❌ Wrong: de:11000:900110001::3 or de:11000:900110001
  • ✅ Correct: 900110001 (extract base 6-digit code from /stops results)
  • Process: Call /stops?query=... first, extract the 6-digit id from results, use that for /journeys.
• URL encoding (CRITICAL): All query string parameters must be properly URL-encoded using urllib.parse.quote() or equivalent. Examples:
  • Space → %20
  • ö → %C3%B6
  • ü → %C3%BC
  • Ä → %C3%84
  • Special chars like &, ?, # → their percent-encoded equivalents
  • Example: Schönhauser Allee → Sch%C3%B6nhauser%20Allee
  • Every API call with address/stop name strings in query params must encode before building the URL.
• Prefer stop/station IDs when calling /journeys (more reliable than fuzzy names): Use /stops?query=... to resolve names → base IBNR.
• Use stopovers=true to build readable step lists; include entrances=true when walking-to-entrance accuracy is important.
• Request results=3 then offer the top 2–3 to the user.
• Handle timezone-aware ISO datetimes; default to Europe/Berlin if none provided.