Назад към всички

stormglass-surf-skill

// Fetch surf-relevant ocean conditions from Stormglass by spot name or coordinates, including current snapshot and 1-3 day forecast windows with tides, gusts, and water temperature. Use when users ask for surf reports, wave or swell conditions, tide timing, wind, gusts, or water temperature for a beac

$ git log --oneline --stat
stars:1,933
forks:367
updated:March 4, 2026
SKILL.mdreadonly
SKILL.md Frontmatter
namestormglass-surf-skill
descriptionFetch surf-relevant ocean conditions from Stormglass by spot name or coordinates, including current snapshot and 1-3 day forecast windows with tides, gusts, and water temperature. Use when users ask for surf reports, wave or swell conditions, tide timing, wind, gusts, or water temperature for a beach or surf spot.
version1.0.2
metadata[object Object]

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

ModeSTORMGLASS_API_KEYGOOGLE_GEOCODING_API_KEY
--mocknot requirednot required
live --lat/--lonrequirednot required
live --location with Googlerequiredoptional (preferred when set)
live --location with OSM fallbackrequirednot 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.