Weather NWS Skill

Get detailed US weather forecasts from the National Weather Service with automatic global fallback, hourly forecasts, air quality data, and structured winter storm accumulations.

What This Skill Does

This skill operates in 8 modes to match your query:

AirNow API Key (Optional but Recommended)

The AirNow API works without a key but has limitations:

Getting an API Key

1. Visit: https://docs.airnowapi.org/account/request/
2. Fill out the request form (free for personal use)
3. Key arrives via email within 1-2 business days

Setting the API Key

Option 1: Environment Variable (Recommended)

export AIRNOW_API_KEY="your-api-key-here"

Option 2: OpenClaw Config (Persistent)

Add to your OpenClaw config under skills.entries.weather-nws.env:

{
  "skills": {
    "entries": {
      "weather-nws": {
        "env": {
          "AIRNOW_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

When to Use

✅ USE this skill when:

• "What's the weather in [US city]?"
• "How much snow is expected?"
• "Winter storm forecast for [location]"
• "Will it rain tomorrow in [US city]?"
• "What time will the rain stop?"
• "Air quality in [city] today"
• Any US-based weather query

🔄 Automatic fallback:

• Non-US locations → wttr.in
• NWS API unavailable → wttr.in
• Both sources fail → clear error message

Quick Start

# Run the unified weather script
python3 ./scripts/get_weather.py "New York, NY"

# Force specific source if needed (normally auto-detected)
python3 ./scripts/get_weather.py "London, UK" --source wttr

# Get hourly forecast (auto-detected or forced)
python3 ./scripts/get_weather.py "Boston at 8 PM"
python3 ./scripts/get_weather.py "Chicago" --hourly

# Include air quality
python3 ./scripts/get_weather.py "Seattle" --aqi

Hourly Auto-Detection

The skill automatically detects time-specific language and switches to hourly forecast:

"Boston at 8 PM"        → ⏰ Hourly mode
"Boston tonight"         → ⏰ Hourly mode
"Boston tomorrow morning" → ⏰ Hourly mode
"Boston at 5:30"         → ⏰ Hourly mode
"When will it stop raining?" → ⏰ Hourly mode

Patterns detected:

• at 8 PM, at 5:30, etc.
• tonight, this afternoon
• tomorrow morning/afternoon/night
• when will..., how long until...

Air Quality (--aqi)

Adds AirNow AQI data to any forecast:

python3 ./scripts/get_weather.py "Boston" --aqi

Output includes:

• Current AQI with color-coded emoji (🟢 🟡 🟠 🔴 🟣 🔵)
• Primary pollutant (PM2.5, O3, etc.)
• Health recommendation based on category
• 3-day AQI forecast

AQI Categories:

Output Format

The script provides consistent output regardless of source:

Header: Location and current alert status

Today → Tonight → Tomorrow: Structured timeline

Accumulation: Specific snow/rain amounts when available

Bottom Line: Actionable summary with timing

Implementation

The script handles:

1. Geocoding location to lat/long
2. Detecting if location is in US
3. Calling NWS API for US locations (detailed accumulation)
4. Falling back to wttr.in for non-US (basic forecast)
5. Formatting consistent output with emojis and structure

Limitations

• NWS: US only, requires internet, rate limited
• wttr.in: Global, less detail on accumulation, no official watches/warnings
• AirNow: US + Canada only, requires API key for reliable access

Examples

US winter storm query:

python3 ./scripts/get_weather.py "Boston, MA"

→ Returns NWS data with accumulation estimates

International location:

python3 ./scripts/get_weather.py "Toronto, Canada"

→ Automatically uses wttr.in, notes it's non-US

With air quality:

python3 ./scripts/get_weather.py "Seattle" --aqi

→ Weather + AQI data with health recommendations

Observed vs Forecast:

python3 ./scripts/get_weather.py "Boston" --current

→ Current station readings with forecast comparison

Combined features:

python3 ./scripts/get_weather.py "Seattle" --aqi --current

→ Full weather report with all data sources

Phase 3 features:

python3 ./scripts/get_weather.py "Boston" --astro       # Sunrise/sunset times
python3 ./scripts/get_weather.py "SFO" --taf           # Aviation forecast
python3 ./scripts/get_weather.py "California" --fire    # Fire weather
python3 ./scripts/get_weather.py "Denver" --astro --aqi --current  # Everything!

Observed vs Forecast (--current)

Shows actual measured conditions from the nearest NWS observation station alongside the forecast:

🌡️ **Observed Conditions**
   **Actually 43°F (3° warmer than 40° forecast)**
   ☁️ Partly Cloudy
   💨 WNW 8 mph • 💧 36% humidity • 🌫️ Dewpoint 18°F • 📊 Pressure 29.86 inHg • 👀 Visibility 10+ mi

Fields shown:

• Temperature with forecast delta
• Conditions description
• Wind speed and direction
• Humidity percentage
• Dewpoint
• Barometric pressure (inHg)
• Visibility

Alert Priorities

When alerts are active, they're displayed with enhanced formatting using severity/urgency/certainty weighting:

Severity Styling:

Alert display includes:

• Event name with severity badge
• Urgency tag: ⏰ Immediate / 📅 Expected / 🔮 Future
• Time range (onset → expires)
• First sentence of description
• Recommended response action

Example:

🟠 [**MODERATE**] **Winter Storm Warning**
   📅 Expected | *Winter Storm Warning from 6 PM to 10 AM EST*
   🕐 6:00 PM → 10:00 AM
   📝 Heavy snow expected with accumulations of 6-10 inches...
   👉 🎒 Prepare now

References

• references/nws-api.md — NWS API endpoint details
• references/airnow-api.md — AirNow API documentation

Phase 3 Features

Astronomical Times (--astro)

Shows sunrise, sunset, civil twilight, and moon phase information:

python3 ./scripts/get_weather.py "Boston" --astro

Output includes:

• 🌅 Sunrise: Time with countdown/ago
• 🌇 Sunset: Time with countdown/ago
• 💡 Civil Twilight: Dawn and dusk times (useful for runners, cyclists)
• ⏱️ Daylight: Total hours of daylight
• 🌙 Moon: Current phase with illumination percentage

Example:

☀️ **Astronomical Times — Boston**

🌅 **Sunrise:** 6:22 AM (12h ago)
🌇 **Sunset:** 5:31 PM (in 2h)
💡 **Civil Twilight:** 5:55 AM – 5:58 PM
⏱️ **Daylight:** 11h 9m
🌙 **Moon:** 🌓 First Quarter (50.0%)

Aviation Forecast (--taf)

Shows Terminal Aerodrome Forecast (TAF) for the nearest aviation weather station:

python3 ./scripts/get_weather.py "SFO" --taf

Note: TAFs are designed for aviation use. The report provides:

• Station identifier
• Wind conditions and direction
• Visibility
• Cloud ceiling information

Important: This is informational only. Always check official sources for flight planning.

Fire Weather (--fire)

Shows fire danger information for wildfire-prone areas:

python3 ./scripts/get_weather.py "California" --fire

Output includes:

• Fire danger level (if elevated)
• 🔥 Red Flag Warnings (if active)
• Fire weather zone forecast
• Source attribution

Red Flag Warnings indicate critical fire weather conditions (low humidity + high winds).

Changelog

v1.3.0 (2026-02-26) - Phase 3

• Added --astro flag for sunrise/sunset, twilight, and moon phase
• Added --taf flag for Aviation Terminal Aerodrome Forecasts
• Added --fire flag for fire weather danger and red flag warnings
• Added moon phase calculation (waxing/waning, illumination %)
• Added daylight hours calculation
• Added civil twilight detection for runners/cyclists

v1.2.0 (2026-02-26) - Phase 2

• Added --current flag for station observations vs forecast comparison
• Enhanced alert formatting with severity/urgency/certainty priority scoring
• Added temperature delta comparison (warmer/cooler than forecast)
• Added full observation details: humidity, dewpoint, pressure, visibility

v1.1.0 (2026-02-26)

• Added hourly forecast with temporal query auto-detection
• Added AirNow AQI integration (--aqi flag)
• Added structured grid data for winter storm accumulations
• Fixed AirNow API endpoint URLs

v1.0.0 (2026-02-22)

• Initial release: NWS API with wttr.in fallback
• 12-hour forecast periods
• Alert integration
• Accumulation estimates from text parsing