weather-skill

Files (5)

• README.md
• SKILL.md
• clothing_guide.md · references/
• fetch_weather.py · scripts/
• geocode.py · scripts/

SKILL.md (first lines)

# Weather Skill

Provides current weather and forecasts for any location using two free APIs:
- **Nominatim** (OpenStreetMap) for geocoding locations → `scripts/geocode.py`
- **Open-Meteo** for weather data → `scripts/fetch_weather.py`

---

## Workflow

1. **Understand the user's request.** Extract the location, time range, and whether they're planning travel. See examples below.
2. **Geocode the location** by running `scripts/geocode.py "<location>"`. It returns JSON with `display_name`, `lat`, `lon`, and an `ambiguous` flag. If ambiguous, ask the user to clarify.
3. **Fetch weather** by running `scripts/fetch_weather.py` with the lat/lon and appropriate flags. See script usage below.
4. **Respond to the user** with a clear summary. See example outputs below.
5. **If travel intent is detected**, also read `references/clothing_guide.md` and include relevant clothing advice.

---

## Scripts

### Geocode: `scripts/geocode.py`

Converts a location string to coordinates.

```bash
python scripts/geocode.py "Tokyo"
python scripts/geocode.py "King Abdullah Financial District, Riyadh"
python scripts/geocode.py "Times Square, New York"
```

Returns JSON:
```json
{
  "display_name": "Tokyo, Japan",
  "lat": 35.6764,
  "lon": 139.6500,
  "importance": 0.82,
  "ambiguous": false
}
```

If `ambiguous` is `true`, an `alternatives` list is included — ask the user which they meant.

### Weather: `scripts/fetch_weather.py`

Fetches weather data for given coordinates.

```bash
# Current conditions only
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution current

# Hourly forecast (good for today, tomorrow, next 12 hours, specific day)
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution hourly

# Daily forecast (good for multi-day ranges, next week, etc.)
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution daily

# Custom timezone (default is "auto" which uses the location's timezone)
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution hourly --timezone Asia/Tokyo

# Include historical data when user asks about past weather
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution daily --past-days 7
```

Returns JSON with `meta`, `current`, `hourly`, and/or `daily` sections depending on resolution.

Example JSON response (`--resolution current`):
```json
{
  "meta": {
    "lat": 35.6764,
    "lon": 139.65,
    "timezone": "Asia/Tokyo",
    "resolution": "current",
    "forecast_days": 16,
    "past_days": 0
  },
  "current": {
    "time": "2026-02-25T14:00",
    "temperature_c": 12.3,
    "apparent_temperature_c": 10.8,
    "weather_code": 1,
    "weather_description": "Mainly clear",
    "wind_speed_kmh": 14.2,
    "humidity_pct": 48,
    "precipitation_mm": 0.0
  },
  "hourly": null,
  "daily": null
}
```

The script always requests `forecast_days=16` (max forecast horizon).
Use `--past-days` only for past weather requests (`0..92`).

---

## How to Interpret User Requests

The agent should interpret the user's natural language to determine three things:

### 1. Location
Extract the place name from the query. Examples:
- "Weather in **Jeddah** now" → `"Jeddah"`
- "Forecast for **London** this weekend" → `"London"`
- "I'm going to **Tokyo** next week" → `"Tokyo"`
- "How windy will it be in **AlUla** on Friday?" → `"AlUla"`

If no location is mentioned, ask the user.

### 2. Time Range, Resolution, and Past Weather

| User says | Resolution | `past_days` | Notes |
|---|---|---|---|
| "now" / "current" / no time specified | `current` (also include hourly for next 24h) | `0` | Forecast request always uses 16 days. |
| "today" / "tonight" / "tomorrow" / "tomorrow morning" | `hourly` | `0` | Use hourly data to answer specific time windows. |
| "this weekend" / "on Friday" / "hourly for next 12 hours" | `hourly` | `0` | Filter the returned series in the response. |
| "next 3 days" | `hourly` | `0` | Summarize from hourly data. |
| "next 7 days" / "next week" / "first week of March" | `daily` | `0` | Summarize relevant days from daily data. |

From zjwan461/ruoyi-langchain4j, MIT.

More from zjwan461/ruoyi-langchain4j