at-transport

Files (6)

• SKILL.md
• source-notes.md · references/
• cli.py · scripts/
• smoke_test.py · scripts/
• test_contract.py · scripts/
• contract.json · tests/fixtures/

SKILL.md (first lines)

# Auckland Transport

## Goal

Query live Auckland public transport data from the AT API through a CLI that is easy for agents to script and easy for humans to scan. Covers real-time departures, service alerts, stop search, nearby stops, vehicle tracking, and network status.

## Use this when

- A user asks about Auckland public transport — buses, trains, ferries
- A user wants real-time departure information from a specific stop
- A user asks about service disruptions or alerts in Auckland
- A user wants to find nearby stops or search for a stop by name
- A user asks about live vehicle positions on the Auckland network
- A user wants a quick overview of Auckland Transport network status

## Do not use this for

- Transport outside Auckland / New Zealand
- Route planning or journey directions (use AT's journey planner)
- Historical schedule data or timetable lookups
- Fares or ticketing information
- Traffic or road conditions

## Preferred workflow

1. Run `scripts/cli.py` with the narrowest subcommand that answers the task
2. Use default human output for direct answers
3. Use `--json` when another tool or agent needs machine-readable output

## CLI

Run with:

```bash
python3 skills/at-transport/scripts/cli.py <command> [flags]
```

### `alerts [--limit N] [--json]`

Active service alerts and disruptions across the Auckland network.

JSON shape:
- `timestamp`
- `total_active`
- `returned`
- `alerts[]` with `id`, `severity_level`, `cause`, `effect`, `header_text`, `description_text`, `active_period`, `informed_entity`

Examples:

```bash
python3 skills/at-transport/scripts/cli.py alerts
python3 skills/at-transport/scripts/cli.py alerts --limit 5
python3 skills/at-transport/scripts/cli.py alerts --json
```

### `departures <stop_id> [--limit N] [--json]`

Real-time departures from a stop. Uses stop code (e.g. `11814`) or full stop ID. Shows route, expected time, and delay. For parent stations, includes all child platform stops.

JSON shape:
- `stop` with stop details
- `total_departures`
- `returned`
- `departures[]` with `route_id`, `route_short_name`, `route_type`, `trip_id`, `stop_id`, `stop_name`, `direction_id`, `scheduled_time`, `expected_time`, `delay_seconds`, `vehicle_id`, `vehicle_label`

Key stop codes:
- `11814` — Britomart (bus terminal)
- `11815` — Customs St/Britomart
- `11895` — Britomart Queens Arcade
- `31986` — Britomart Lower Albert

Examples:

```bash
python3 skills/at-transport/scripts/cli.py departures 11814
python3 skills/at-transport/scripts/cli.py departures 7155 --limit 5
python3 skills/at-transport/scripts/cli.py departures 11814 --json
```

### `stops <query> [--limit N] [--json]`

Search stops by name, code, or ID. Returns matching stops with location and type info.

JSON shape:
- `query`
- `total_matches`
- `returned`
- `stops[]` with `stop_id`, `stop_code`, `stop_name`, `stop_lat`, `stop_lon`, `location_type`, `parent_station`, `platform_code`

Examples:

```bash
python3 skills/at-transport/scripts/cli.py stops Britomart
python3 skills/at-transport/scripts/cli.py stops Newmarket
python3 skills/at-transport/scripts/cli.py stops 7155 --json
```

### `nearby <lat,lon> [--radius N] [--limit N] [--json]`

Find stops near a geographic location. Radius in meters, defaults to 500m.

JSON shape:
- `location` with `lat`, `lon`
- `radius_m`
- `total_nearby`
- `returned`
- `stops[]` with stop details plus `distance_m`

Examples:

```bash
python3 skills/at-transport/scripts/cli.py nearby --location=-36.844,174.768
python3 skills/at-transport/scripts/cli.py nearby --location=-36.844,174.768 --radius 1000
python3 skills/at-transport/scripts/cli.py nearby --location=-36.844,174.768 --json
```

### `route <route_id> [--json]`

Show details for a specific route. Use full route ID (e.g. `STH-201`).

From thecolab-ai/.skills, MIT.

More from thecolab-ai/.skills