natbag

name	natbag
description	This skill should be used when the user asks about "Ben Gurion airport", "TLV flights", "flight status", "departures from Tel Aviv", "arrivals at TLV", "is my flight on time", "flight to Amsterdam", "airport delays", "cancelled flights", "gate info", "terminal 3", "pickup from airport", "weather at destination", "flight delay history", "נתב״ג", "טיסות", "לוח טיסות", "מצב טיסה". Provides live flight data from Ben Gurion Airport (TLV), destination weather via Open-Meteo, and historical delay analysis via local SQLite database. Do NOT use for booking flights, non-TLV airports, or general travel planning.
user-invocable	true
argument-hint	[departures|arrivals|LY001|delayed|weather <city>|history <airline>]
allowed-tools	["Bash(curl)","Bash(python3)","Bash(sqlite3)","Read","Write"]

Natbag — Ben Gurion Airport Flights

Live flight data, destination weather, and historical analysis for Ben Gurion Airport (TLV/LLBG). Data from Israel's open data portal (data.gov.il), covering a rolling ~3-day window.

Query Workflow

Show step progress to the user as each step runs:

1. Step 1: Fetching flights — run query_flights.py with appropriate filters
2. Step 2: Getting weather — fetch destination weather (for single flight or when relevant)
3. Step 3: Checking history — query historical stats (only if user asks about delays/patterns)

Not all steps run every time. Skip steps that aren't relevant to the query:

• Departure board → Step 1 only
• "Is my flight on time?" → Step 1 + Step 2
• "Are El Al flights usually delayed?" → Step 3 only
• "Next flight to London with weather" → Step 1 + Step 2

Display each step label before running it so the user sees progress.

Data Sources

1. Live flights: data.gov.il API — departures, arrivals, status, gates
2. Weather: Open-Meteo API — free, no API key — current conditions at destination
3. Historical: Local SQLite DB at ~/.natbag/flights.db — accumulated via daily snapshots

Daily Snapshot (Automatic)

A PreToolUse hook runs snapshot.py automatically whenever this skill is invoked. On first run, it copies the shipped data/db.db (airlines + airports) to ~/.natbag/flights.db, adds the flights table, and fetches live flights. On subsequent runs, it self-guards: skips if it already ran today or if the user disabled snapshots.

After the first invocation, inform the user: "Natbag initialized. Flight data and IATA reference loaded. Historical data will accumulate automatically on each use. To disable daily snapshots, set daily_snapshot: false in ~/.natbag/config.json."

Replace SKILL_DIR with the resolved path to this skill's directory (where this SKILL.md lives).

Querying Live Flights

Use the composable query_flights.py script for live API queries:

python3 SKILL_DIR/scripts/query_flights.py --departures --date YYYY-MM-DD
python3 SKILL_DIR/scripts/query_flights.py --arrivals --date YYYY-MM-DD --upcoming
python3 SKILL_DIR/scripts/query_flights.py --arrivals --airline LY --date YYYY-MM-DD
python3 SKILL_DIR/scripts/query_flights.py --destination JFK --upcoming
python3 SKILL_DIR/scripts/query_flights.py --flight LY001
python3 SKILL_DIR/scripts/query_flights.py --status DELAYED
python3 SKILL_DIR/scripts/query_flights.py --search "London"

Flags can be combined. All scripts return JSON — Claude handles formatting for the user.

CRITICAL: Always use --date YYYY-MM-DD when counting or listing flights for a specific day. Without it, the API returns a rolling ~3-day window, inflating counts. When --date is set, the script automatically pages through all API results before filtering, so counts are accurate. Replace YYYY-MM-DD with the actual date (e.g., 2026-04-03).

For raw API access, use curl directly — see references/api.md for filter patterns.

Resolving Ambiguous Queries

The local DB at ~/.natbag/flights.db includes airlines and airports tables (from data/db.db) for resolving user input:

• Airline name → code: User says "El Al" or "Wizz Air" → look up IATA code:

  python3 SKILL_DIR/scripts/query_history.py --airline-lookup "El Al"
  

• Multi-airport cities: User says "flights to London" → find all London airports:

  python3 SKILL_DIR/scripts/query_history.py --airports London
  

  Then query each relevant code (LHR, LGW, STN, LTN, LCY) or use full-text search --search London.
• Partial flight numbers: User says "flight 001" without airline → use --search 001 to match across all airlines.
• Hebrew city names: User types "לונדון" → use --search לונדון. Supports partial prefix matching (e.g., --search לונ finds לונדון).
• Empty results: If a filtered query returns 0 results, try broadening: drop the direction filter, switch from exact filter to --search, or check if the city has multiple airport codes.

Output Fields

query_flights.py returns clean JSON with these fields:

Field	Content
flight	Airline code + number (e.g., "LY 1008")
airline	Airline full name
date	Scheduled date (YYYY-MM-DD)
time	Scheduled time (HH:MM)
updated_time	Actual/updated time (compare with time to detect delays)
direction	"departure" or "arrival"
city / city_he	City name (English / Hebrew)
country / country_he	Country (English / Hebrew)
airport	IATA airport code
terminal	Terminal number
gate	Gate assignment (null if unassigned)
checkin_zone	Check-in zone (null if N/A)
status / status_he	Flight status (English / Hebrew)

Full field reference and curl examples: see references/api.md. For complete output examples: see examples/ (departure board, single flight, historical stats).

Destination Weather

After showing flight info, offer weather at the destination. Uses Open-Meteo (free, no key).

Steps:

1. Get the city field from the flight JSON (e.g., "BERLIN")
2. Geocode: curl -s 'https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1'
3. Extract latitude and longitude from results[0]
4. Fetch weather: curl -s 'https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current_weather=true'
5. Display: temperature, weather description, wind speed

Open-Meteo returns the most populated city match, so "Berlin" → Berlin Germany (not Berlin NH). Tested and correct for all TLV route cities.

Weather codes: 0=Clear, 1-3=Partly cloudy, 45/48=Fog, 51-55=Drizzle, 61-65=Rain, 71-75=Snow, 80-82=Showers, 95=Thunderstorm.

Historical Analysis

Use the composable query_history.py script for historical queries:

python3 SKILL_DIR/scripts/query_history.py --coverage                    # data range
python3 SKILL_DIR/scripts/query_history.py --ontime                      # all airlines
python3 SKILL_DIR/scripts/query_history.py --ontime --airline LY          # specific airline
python3 SKILL_DIR/scripts/query_history.py --delays --route JFK           # delays by route
python3 SKILL_DIR/scripts/query_history.py --cancellations                # cancellation rates
python3 SKILL_DIR/scripts/query_history.py --airports London              # multi-airport lookup
python3 SKILL_DIR/scripts/query_history.py --airline-lookup "Wizz"        # airline code lookup

Add --days N to change the lookback period (default: 30). All output is JSON.

Flight Change History

Track how flights evolve over time — status changes, time updates, gate reassignments:

python3 SKILL_DIR/scripts/query_history.py --flight-history LY001         # all changes for a flight
python3 SKILL_DIR/scripts/query_history.py --delay-patterns               # when are delays announced?
python3 SKILL_DIR/scripts/query_history.py --delay-patterns --airline LY   # per-airline patterns
python3 SKILL_DIR/scripts/query_history.py --status-transitions            # status paths (e.g., DELAYED -> CANCELED)

Change history accumulates from version 1.1.0 onward. Older flights (captured before the upgrade) will not have change records.

Use --flight-history when the user asks about a specific flight's progression. Use --delay-patterns when they ask about how early delays are typically announced. Use --status-transitions when they ask about flights that were delayed then cancelled, or other status paths.

If the database doesn't exist or is empty, inform the user: "Historical data accumulates from install date via daily snapshots. Run python3 SKILL_DIR/scripts/snapshot.py --force to start collecting now."

For custom SQL queries, use sqlite3 ~/.natbag/flights.db directly. The DB also has airlines, airports, and flight_changes tables for JOINs. See references/api.md for query patterns.

Output Formatting

Departure/Arrival Board

Ben Gurion Departures — March 21, 2026

Time    Flight    Airline     To               Gate     Status
14:10   LY 001    El Al       London (LHR)     B2-B4    ON TIME
14:30   IZ 1511   Arkia       Larnaca (LCA)    G11      DELAYED → 15:04
15:00   6H 996    Israir      Amsterdam (AMS)   —       CANCELED

• Sort by date + time
• For DELAYED flights, show updated_time
• Use — for null gate/checkin_zone values
• Omit past flights (status DEPARTED/LANDED) unless the user explicitly asks for all

Single Flight Detail

Flight LY 001 — El Al Israel Airlines
Route:     Tel Aviv (TLV) → London Heathrow (LHR)
Scheduled: 14:10  |  Updated: 14:10
Terminal:  3      |  Gate: B2-B4  |  Check-in: B
Status:    ON TIME

London Weather: 12°C, Partly Cloudy, Wind 15 km/h

Historical Stats

El Al to JFK — Last 30 Days (from local DB)
Total: 28  |  On time: 19 (68%)  |  Avg delay: 22 min
Cancellations: 1 (3.6%)

Hebrew Support

When the user writes in Hebrew, respond in Hebrew and use the Hebrew fields from the JSON:

• City names: city_he instead of city
• Country names: country_he instead of country
• Status: status_he instead of status
• Board header: לוח טיסות נתב"ג — יציאות / הגעות

Smart Behaviors

• "my flight": Ask for flight number or destination to narrow down
• Pickup planning: Show arrival time + suggest arriving 30 min after expected landing. If DELAYED, use updated_time instead of time
• Delay detection: When updated_time > time, calculate and show delay duration in minutes
• Weather proactively: When showing a single flight detail, include destination weather automatically
• First use: Mention that historical data accumulates over time via daily snapshots. The user can disable this in ~/.natbag/config.json by setting daily_snapshot: false

Snapshot Management

The scripts/snapshot.py script fetches current flights and stores them in SQLite:

• Runs automatically via PreToolUse hook on each skill invocation (self-guards to once daily)
• python3 SKILL_DIR/scripts/snapshot.py --force to run manually anytime
• Opt-out: set daily_snapshot: false in ~/.natbag/config.json
• First run copies shipped data/db.db (airlines + airports) to ~/.natbag/flights.db
• Data deduplicates by airline+flight+scheduled time
• Status and gate info are updated on each snapshot

Gotchas

• Field names are cryptic: All fields start with CH (Hebrew abbreviation for "חברה"/company). Always refer to the field reference, never guess. Common mistake: using STATUS instead of CHRMINE.
• Rolling window inflates counts: API returns ~3 days of data, NOT just today. When counting flights for a specific day, ALWAYS pass --date YYYY-MM-DD to filter. Without it, "how many flights today?" will return 3x the real number. This has caused wrong answers repeatedly.
• Uppercase values: Filter values must be uppercase. filters={"CHRMINE":"delayed"} returns 0 results silently — use "DELAYED". Same for airline codes: "ly" → no results, "LY" → works.
• API timeout: data.gov.il can be slow (5-15s). If curl hangs, retry once. Error: curl: (28) Operation timed out — fix with curl -s --max-time 30.
• Bad resource ID: Returns {"success": false, "error": {"__type": "Not Found Error", "message": "לא נמצא: Resource was not found."}}. Fix: verify the resource_id constant hasn't changed.
• Malformed filters JSON: Returns {"success": false, "error": {"filters": ["Cannot parse JSON"], "__type": "Validation Error"}}. Fix: ensure filters value is valid JSON with properly escaped quotes in the URL.
• Empty result confusion: "total": 0 with "success": true means the filter matched nothing — not an error. Check: is the value uppercase? Is the field name correct? Is the flight within the 3-day window?
• Gate availability: CHCINT and CHCKZN are often null for flights >24h away or for arrivals. Don't treat null gate as an error.
• "NOT FINAL": Many future flights show status "NOT FINAL" — this means the schedule isn't confirmed yet, not that the flight is cancelled. Don't alarm the user.
• No booking: This skill provides information only. Cannot book, modify, or cancel flights. If asked, clearly say so.