Windsensei

Check wind and weather conditions for wind sports (kitesurfing, wingfoiling, surfing). Get forecasts, find spots nearby, view session history, and request new spots.

# WindSensei - Wind Forecast Assistant

Check wind conditions at your favorite spots and take action on good forecasts.

## When to Use This Skill

Activate when the user asks about:
- Wind conditions, wind forecast, or weather for wind sports
- "How's the wind?", "Should I go kiting?", "Any good wind this weekend?"
- "What's it looking like at [spot name]?", "Wind report"
- Kiting, kitesurfing, wingfoiling, windsurfing, surfing conditions
- Blocking off time or adding sessions to their calendar based on wind
- Finding spots near a location or exploring new spots
- Session history, stats, or activity logs
- What friends are riding right now (live sessions)

## Configuration

### Credentials

- `WINDSENSEI_API_KEY`: An API key starting with `ss_`. **Optional — the skill works fully without it.** Without it, you can still query any public spot by name, search for spots, and find spots nearby. With it, you get personalized forecasts, dashboard overview, session history, and social features.
- **No other credentials are required.** This skill only makes HTTPS requests to the WindSensei API. Calendar features (if requested by the user) use the host agent's own calendar tools — this skill does not request or store any calendar credentials.

### Getting an API Key

If the user wants personalized forecasts, guide them:
1. Sign up at **windsensei.com**
2. Add their favorite spots and set activity preferences
3. Go to their **Profile page** at **windsensei.com/dashboard/profile** — the API key manager is at the bottom of that page
4. Click **"Create API Key"**, give it a name (e.g., "Claude" or "OpenClaw"), and copy the key
5. The key starts with `ss_` — set it as `WINDSENSEI_API_KEY` in the agent's environment config

**Direct link:** `https://windsensei.com/dashboard/profile` (scroll to "API Keys" section)

## Two Modes

### Public Mode (no API key)
- Query any public spot by name using the `spot` parameter
- Search for spots by name
- Find spots near a latitude/longitude
- Uses default kiting preferences (12-40kt, 8am-8pm)
- Response includes a `hint` field suggesting signup for personalized results

### Authenticated Mode (with API key)
- Everything in public mode, plus:
- Dashboard overview of all favorite spots in one call
- Personalized forecasts using the user's activity preferences, wind speed ranges, time windows
- Session history and stats
- Live session feed from followed users
- Favorites list
- No signup hint in response

## Authentication

For all authenticated endpoints, include the API key as a Bearer token:
```
Authorization: Bearer {WINDSENSEI_API_KEY}
```

The API also accepts `X-API-Key: {key}` header or `?api_key={key}` query param.

---

## API Endpoints

### 1. Wind Report (Quick Summary)

The simplest way to check conditions. Returns a natural language summary plus structured data.

```
GET https://windsensei.com/api/v1/wind-report?when={when}
```

| Param | Values | Default | Description |
|-------|--------|---------|-------------|
| `when` | `today`, `tomorrow`, `weekend`, `week` | `today` | Time window |
| `spot` | string (e.g., `Cherry Beach`) | — | Search public spots by name. Not needed with API key. |
| `locationId` | string | — | Specific spot by ID |
| `format` | `text`, `full` | `full` | `text` returns just the summary string |

**Auth:** Optional. With API key, returns forecasts for all the user's favorite spots automatically.

**Response:**
```json
{
  "success": true,
  "text": "Cherry Beach: Great conditions 2-6pm — 18-22kt SW, 24°C, water 19°C. Good for Kitefoil, Twintip.",
  "when": "today",
  "authenticated": false,
  "hint": "Personalize your forecast with your own spots and activity preferences at windsensei.com",
  "locations": [
    {
      "locationId": "abc123",
      "name": "Cherry Beach",
      "timezone": "America/Toronto",
      "blocks": [
        {
          "date": "2026-02-21",
          "dateLabel": "Saturday, Feb 21",
          "start": "14:00",
          "end": "18:00",
          "quality": "good",
          "windSpeed": { "avg": 20, "gust": 25 },
          "windDirection": "SW",
          "windQuality": "good",
          "temperature": 24,
          "waterTemp": 19,
          "activities": ["Kitefoil", "Twintip"]
        }
      ]
    }
  ]
}
```

**When no spot specified and no API key:**
```json
{
  "success": true,
  "text": "Provide a spot name to check conditions. Example: ?spot=Cherry Beach",
  "locations": [],
  "hint": "Personalize your forecast with your own spots and activity preferences at windsensei.com"
}
```

---

### 2. Dashboard (All Spots Overview)

**Auth: Required.** Single call to get current conditions for all the user's favorite spots, sorted best-first. The most efficient way to answer "how's the wind?" for authenticated users.

```
GET https://windsensei.com/api/v1/dashboard
```

**Response:**
```json
{
  "success": true,
  "spots": [
    {
      "locationId": "abc123",
      "name": "Cherry Beach",
      "current": {
        "windSpeed": 18,
        "windGust": 24,
        "windDirection": 225,
        "temperature": 22,
        "quality": "good"
      },
      "observed": {
        "stationName": "Toronto Island",
        "observationTime": "2026-02-21T14:00:00Z",
        "windSpeed": 20,
        "windDirection": 210,
        "windGust": 26,
        "temperature": 21,
        "waterTemp": { "temperature": 18.5, "units": "C" }
      },
      "nextGoodWindow": {
        "start": "2026-02-21T14:00",
        "end": "2026-02-21T18:00",
        "quality": "good",
        "activities": ["Kitefoil", "Twintip"]
      },
      "modelConsensus": {
        "agreement": "high",
        "models": ["GFS", "ICON", "GEM"]
      }
    }
  ],
  "generatedAt": "2026-02-21T12:00:00Z"
}
```

**Key fields:**
- `current`: Forecast-based current conditions
- `observed`: Real weather station data (if available for the spot) — more accurate than forecast
- `nextGoodWindow`: Next rideable time window based on the user's activity preferences. Times are in the spot's local timezone.
- `modelConsensus`: Whether forecast models agree on conditions
- Spots are sorted by quality (best first), then by wind speed

**When to use dashboard vs wind-report:**
- Use **dashboard** when the user has an API key and asks a general "how's the wind?" — it covers all their spots in one call
- Use **wind-report** when querying a specific spot by name, or when there's no API key

---

### 3. Best Conditions (Ranked Spots)

Find the best spots right now. Works with or without auth.

```
GET https://windsensei.com/api/v1/best-conditions
```

| Param | Values | Default | Description |
|-------|--------|---------|-------------|
| `when` | `now`, `today`, `tomorrow`, `weekend` | `now` | Time window. `now` = current hour onward. |
| `lat` | number | — | Latitude (required if no API key) |
| `lng` | number | — | Longitude (required if no API key) |
| `radius` | number | 100 | Search radius in km (max 500). Only used with lat/lng. |
| `limit` | number | 5 | Max results (max 20) |

**Auth:** Optional.
- **With API key:** Evaluates the user's favorite spots using their activity preferences. No lat/lng needed.
- **Without API key:** Requires lat/lng. Finds nearby public spots and evaluates with default kiting preferences.
- If authenticated but no favorites, falls back to lat/lng nearby search.

**Response:**
```json
{
  "success": true,
  "when": "now",
  "spots": [
    {
      "locationId": "abc123",
      "name": "Cherry Beach",
      "timezone": "America/Toronto",
      "distance": 4.2,
      "current": {
        "windSpeed": 20,
        "windGust": 26,
        "windDirection": "SW",
        "windQuality": "good",
        "temperature": 22,
        "quality": "good"
      },
      "waterTemp": 18.5,
      "bestBlock": {
        "date": "2026-02-21",
        "dateLabel": "Saturday, Feb 21",
        "start": "14:00",
        "end": "18:00",
        "quality": "good",
        "windSpeed": { "avg": 20, "gust": 26 },
        "windDir