Stormglass Surf Skill

Purpose

Produce machine-readable surf condition data for cron-driven agent pipelines.

This skill resolves a surf spot name with Google Geocoding (or uses direct coordinates), queries Stormglass, and returns a stable JSON payload for downstream interpretation/rendering.

Inputs

Provide exactly one location mode:

• --location "Spot name" (optional country/region in string), or
• --lat <float> --lon <float>

Optional controls:

• --horizon now|24h|48h|72h (default 72h)
• --output json|pretty (default json, recommended for automation)
• --source <comma-separated provider list>
• --mock (offline deterministic data; useful for tests)

Required Environment Variables

• STORMGLASS_API_KEY for Stormglass requests
• GOOGLE_GEOCODING_API_KEY optional for --location (if absent, script falls back to OpenStreetMap Nominatim)

In --mock mode, no API keys are required.

Credential Matrix

Mode	STORMGLASS_API_KEY	GOOGLE_GEOCODING_API_KEY
--mock	not required	not required
live --lat/--lon	required	not required
live --location with Google	required	optional (preferred when set)
live --location with OSM fallback	required	not required

Primary credential is STORMGLASS_API_KEY.

Execution Commands

JSON output for cron:

python scripts/surf_report.py --location "Highcliffe Beach" --horizon 72h --output json

Direct coordinates:

python scripts/surf_report.py --lat 50.735 --lon -1.705 --horizon 24h --output json

Offline test run:

python scripts/surf_report.py --location "Highcliffe Beach" --horizon now --mock --output json

Output Contract (JSON-first)

Top-level keys are stable:

• meta: request metadata, timestamps, input mode, optional warnings
• location: resolved place details and coordinates
• now: instantaneous surf-relevant metrics
• forecast: horizon summaries and best windows
• tides: tide extremes and inferred current tide trend

Expected metric coverage (null if unavailable):

• waveHeightM
• swellHeightM
• swellPeriodS
• swellDirectionDeg
• windSpeedMps
• windDirectionDeg
• windGustMps
• waterTemperatureC

Exit Codes

• 0: success
• 2: invalid CLI usage/arguments
• 3: missing API keys/configuration
• 4: external API failure (geocoding/Stormglass)
• 5: response parsing/normalization failure

Agent Handoff Rules

• Prefer --output json for downstream agents.
• Treat null metrics as "not provided by source", not zero.
• Read field-level details in reference.md.
• Use examples.md for prompt and command patterns.
• Use scripts/test_surf_report.py before cron rollout.
• Optional: use scripts/normalize_surf_data.py to enforce strict schema defaults before rendering.