stormglass-surf-skill

# 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:

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

Direct coordinates:

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

Offline test run:

```bash
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 extrem...

# Stormglass Surf Skill

An OpenClaw-friendly surf data skill that fetches current and 1-3 day ocean forecasts from Stormglass, including:

- wave height
- swell height/period/direction
- wind speed/direction
- wind gusts
- water temperature
- high/low tide extremes

It supports querying by:

- surf spot name (`--location`, with geocoding), or
- direct coordinates (`--lat` + `--lon`).

## Project Layout

- `SKILL.md` - skill contract and agent handoff guidance
- `scripts/surf_report.py` - main CLI
- `scripts/test_surf_report.py` - CLI test runner
- `scripts/normalize_surf_data.py` - optional schema normalizer
- `examples.md` - practical command/pipeline examples
- `reference.md` - API mapping, schema, and behavior details

## Requirements

- Python 3.10+
- Stormglass API key for non-mock runs
- Google Geocoding key optional (if absent, location mode falls back to OpenStreetMap Nominatim)

## Environment Variables

- `STORMGLASS_API_KEY` - required for live Stormglass requests
- `GOOGLE_GEOCODING_API_KEY` - optional; used when present for `--location`

### Credential Matrix

| Mode | `STORMGLASS_API_KEY` | `GOOGLE_GEOCODING_API_KEY` |
|---|---|---|
| `--mock` (offline tests) | not required | not required |
| live with `--lat/--lon` | required | not required |
| live with `--location` + Google geocoder | required | optional (preferred when set) |
| live with `--location` + OSM fallback | required | not required |

Primary credential for this skill is `STORMGLASS_API_KEY`.

## Quick Start

From repository root:

```bash
# 1) Offline smoke test (no keys required)
python3 scripts/surf_report.py --location "Highcliffe Beach" --horizon now --mock --output pretty

# 2) Live request by coordinates (Stormglass key required)
export STORMGLASS_API_KEY="..."
python3 scripts/surf_report.py --lat 50.735 --lon -1.705 --horizon 24h --output json

# 3) Live request by location (Google optional; OSM fallback if missing)
python3 scripts/surf_report.py --location "Highcliffe Beach" --ho...