@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/weather.md

@@ -0,0 +1,513 @@
+# Skill Deep-Dive: weather
+
+**Skill**: `weather`
+**Category**: Free Utility
+**Setup Difficulty**: 🟢 Easy
+**Time Estimate**: ~1 minute
+**Platform**: Cross-platform (macOS, Windows, Linux)
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| Current weather | Get current conditions for any location | `curl "wttr.in/London?format=3"` |
+| Weather forecast | Multi-day forecast with details | `curl "wttr.in/London"` |
+| Custom formatting | Choose what data to display | `curl "wttr.in/London?format=%l:+%c+%t+%h"` |
+| Airport codes | Query by airport code | `curl "wttr.in/JFK"` |
+| PNG export | Generate weather image | `curl "wttr.in/Berlin.png" -o weather.png` |
+| No API key needed | Free service, no registration | Works immediately |
+| Programmatic access | JSON output for scripting | Open-Meteo API |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] `curl` — For making HTTP requests (pre-installed on most systems)
+
+### Soft Dependencies (Recommended)
+- None
+
+### This Skill Enables
+- [ ] Morning briefings — Include weather in daily summaries
+- [ ] Travel planning — Check weather at destination
+- [ ] Context awareness — Agent knows local conditions
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check for curl (should be pre-installed)
+which curl && echo "✅ curl available" || echo "❌ Need curl"
+
+# Verify internet connection
+curl -s wttr.in/London?format=3 && echo "✅ Can access wttr.in"
+```
+
+### Installation Steps
+
+```bash
+# No installation needed! Just curl.
+# Test immediately:
+curl "wttr.in/London?format=3"
+# Output: London: ⛅️ +8°C
+```
+
+### Verification
+
+```bash
+# Verify wttr.in works
+curl -s "wttr.in/?format=3"
+# Should show weather for your location
+
+# Verify Open-Meteo works (JSON fallback)
+curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true" | head -5
+# Should return JSON
+```
+
+---
+
+## Configuration
+
+No configuration needed! Works out of the box.
+
+### Optional: Create Aliases
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc for convenience
+alias weather='curl "wttr.in/?format=3"'
+alias weather-full='curl "wttr.in/"'
+alias weather-today='curl "wttr.in/?1"'
+
+# Usage:
+weather
+weather-full
+weather-today
+```
+
+### Optional: Set Default Location
+
+```bash
+# Set default location
+export WTTR_DEFAULT_CITY="San Francisco"
+
+# Use in commands
+curl "wttr.in/$WTTR_DEFAULT_CITY?format=3"
+```
+
+---
+
+## User Actions Required
+
+None! This skill works immediately.
+
+---
+
+## Common Failure Points
+
+### Failure: "Could not resolve host: wttr.in"
+
+**Symptom**: curl returns DNS resolution error
+
+**Cause**: No internet connection or DNS issues
+
+**Recovery**:
+```bash
+# Check internet connection
+ping google.com
+
+# Try alternative DNS
+# Temporarily use Google DNS
+export DNS_SERVER=8.8.8.8
+
+# Or use Open-Meteo as fallback
+curl "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
+```
+
+**Prevention**: Ensure internet connection before querying weather
+
+---
+
+### Failure: "Location not found"
+
+**Symptom**: wttr.in returns error for city name
+
+**Cause**: City name misspelled or not in database
+
+**Recovery**:
+```bash
+# Try different formats:
+# With country code
+curl "wttr.in/Springfield,US?format=3"
+
+# With state
+curl "wttr.in/Springfield,Illinois?format=3"
+
+# Airport code
+curl "wttr.in/SPI?format=3"
+
+# Coordinates (lat,long)
+curl "wttr.in/39.78,-89.65?format=3"
+```
+
+**Prevention**: Use airport codes for unambiguous locations
+
+---
+
+### Failure: Rate limiting
+
+**Symptom**: Too many requests, service blocks temporarily
+
+**Cause**: Excessive API calls in short time
+
+**Recovery**:
+```bash
+# Wait a few minutes, then retry
+
+# Or use Open-Meteo as alternative (no rate limits)
+curl "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
+```
+
+**Prevention**: Cache results, don't query in tight loops
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Query current weather | ✅ Yes | bash | `curl "wttr.in/?format=3"` |
+| Parse weather data | ✅ Yes | bash | Use `jq` for JSON parsing |
+| Schedule weather checks | ✅ Yes | cron | Morning briefing automation |
+| Generate weather image | ✅ Yes | bash | `curl "wttr.in/City.png"` |
+| Cache results | ✅ Yes | bash | Store in `/tmp` with timestamp |
+
+### Automation Script: Morning Weather Briefing
+
+```bash
+#!/bin/bash
+# Get weather for morning briefing
+
+LOCATION="${1:-London}"  # Default to London if no arg
+
+# Get compact weather
+echo "📍 Current weather in $LOCATION:"
+curl -s "wttr.in/$LOCATION?format=%l:+%c+%t+%h+%w"
+echo ""
+
+# Get today's forecast
+echo "📅 Today's forecast:"
+curl -s "wttr.in/$LOCATION?format=j1" | jq -r '.weather[0] | "High: \(.maxtempC)°C, Low: \(.mintempC)°C, \(.hourly[0].weatherDesc[0].value)"'
+```
+
+### Caching Weather Data
+
+```bash
+#!/bin/bash
+# Cache weather to avoid rate limits
+
+CACHE_FILE="/tmp/weather-cache-$(date +%Y%m%d-%H).txt"
+CACHE_AGE=3600  # 1 hour
+
+if [ -f "$CACHE_FILE" ]; then
+    # Cache exists and is fresh
+    cat "$CACHE_FILE"
+else
+    # Fetch fresh data
+    curl -s "wttr.in/?format=3" | tee "$CACHE_FILE"
+
+    # Clean old cache files
+    find /tmp -name "weather-cache-*" -mmin +60 -delete
+fi
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Instant weather | Get weather with zero setup | First time user asks about weather |
+| Unicode art | Full ASCII art weather display | When showing forecast |
+| PNG export | Generate shareable weather image | When creating reports |
+| Global coverage | Works for any city worldwide | When user travels |
+| No API key hassle | Works immediately without signup | Contrast with other weather APIs |
+
+### Demo Script
+
+```
+Agent: "Let me check the weather for you. No API key needed - this just works:"
+
+curl "wttr.in/?format=3"
+
+Agent: "That's your current location. Let me show you the full forecast:"
+
+curl "wttr.in/?0"
+
+Agent: "And I can check weather anywhere in the world. Where are you traveling?"
+
+[User: "Tokyo"]
+
+curl "wttr.in/Tokyo?format=%l:+%c+%t+%h+%w"
+
+Agent: "I can also generate PNG images for weather reports:"
+
+curl "wttr.in/Tokyo.png" -o /tmp/tokyo-weather.png
+open /tmp/tokyo-weather.png
+
+Agent: "All of this works instantly, no setup, no API keys."
+```
+
+---
+
+## Usage Examples
+
+### Quick One-Liner
+
+```bash
+# Current weather, compact
+curl "wttr.in/?format=3"
+# Output: San Francisco: ☀️ +15°C
+
+# With more details
+curl "wttr.in/?format=%l:+%c+%t+(feels+like+%f)+%h+humidity+%w+wind"
+# Output: San Francisco: ☀️ +15°C (feels like +13°C) 65% humidity ↙5km/h wind
+```
+
+### Full Forecast
+
+```bash
+# 3-day forecast with ASCII art
+curl "wttr.in/London"
+
+# Today only
+curl "wttr.in/London?0"
+
+# Tomorrow only
+curl "wttr.in/London?1"
+
+# No ANSI colors (for scripts)
+curl "wttr.in/London?T"
+```
+
+### Custom Format Codes
+
+```bash
+# Available format codes:
+# %c - Weather condition
+# %t - Temperature
+# %f - Feels like temperature
+# %h - Humidity
+# %w - Wind speed and direction
+# %l - Location
+# %m - Moon phase
+# %M - Moon day
+# %p - Precipitation (mm/3h)
+# %P - Pressure (hPa)
+
+# Example: Location with condition, temp, humidity, wind
+curl "wttr.in/Berlin?format=%l:+%c+%t+%h+%w"
+# Output: Berlin: ⛅️ +8°C 71% ↙5km/h
+```
+
+### Units
+
+```bash
+# Metric (default)
+curl "wttr.in/New+York?m"
+
+# USCS (Imperial)
+curl "wttr.in/New+York?u"
+```
+
+### PNG Export
+
+```bash
+# Generate PNG image
+curl "wttr.in/Paris.png" -o /tmp/paris-weather.png
+
+# View it
+open /tmp/paris-weather.png  # macOS
+xdg-open /tmp/paris-weather.png  # Linux
+```
+
+### Airport Codes
+
+```bash
+# Query by airport code
+curl "wttr.in/JFK?format=3"
+curl "wttr.in/LAX?format=3"
+curl "wttr.in/SFO?format=3"
+```
+
+### Coordinates
+
+```bash
+# Query by coordinates (latitude,longitude)
+curl "wttr.in/37.77,-122.42?format=3"
+```
+
+---
+
+## Open-Meteo: JSON Alternative
+
+For programmatic use, Open-Meteo provides structured JSON:
+
+```bash
+# Current weather
+curl "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
+
+# Returns JSON:
+{
+  "latitude": 51.5,
+  "longitude": -0.12,
+  "current_weather": {
+    "temperature": 8.0,
+    "windspeed": 5.0,
+    "winddirection": 225,
+    "weathercode": 3,
+    "time": "2026-01-12T12:00"
+  }
+}
+
+# Parse with jq
+curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true" | \
+  jq '.current_weather | "Temp: \(.temperature)°C, Wind: \(.windspeed)km/h"'
+```
+
+### Weather Code Mapping
+
+```bash
+# Open-Meteo weather codes:
+# 0: Clear sky
+# 1, 2, 3: Mainly clear, partly cloudy, overcast
+# 45, 48: Fog
+# 51, 53, 55: Drizzle (light, moderate, dense)
+# 61, 63, 65: Rain (slight, moderate, heavy)
+# 71, 73, 75: Snow fall (slight, moderate, heavy)
+# 80, 81, 82: Rain showers
+# 95: Thunderstorm
+# 96, 99: Thunderstorm with hail
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **cron** | Schedule morning weather check | Add to daily briefing |
+| **comms** | Include in morning summary | "Weather today: ..." |
+| **qmd** | Index weather data for trends | Track weather over time |
+
+---
+
+## Testing Checklist
+
+- [ ] curl installed: `which curl`
+- [ ] wttr.in accessible: `curl "wttr.in/?format=3"`
+- [ ] Current weather works: `curl "wttr.in/London?format=3"`
+- [ ] Full forecast works: `curl "wttr.in/London"`
+- [ ] Custom format works: `curl "wttr.in/London?format=%l:+%c+%t"`
+- [ ] Airport code works: `curl "wttr.in/JFK?format=3"`
+- [ ] PNG export works: `curl "wttr.in/Berlin.png" -o /tmp/test.png`
+- [ ] Open-Meteo works: `curl "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"`
+- [ ] JSON parsing works: Use jq with Open-Meteo
+- [ ] Caching script works: Test weather cache
+
+---
+
+## Notes for Onboarding Agent
+
+- **Zero setup**: Emphasize this works IMMEDIATELY with no API keys
+- **Always available**: Recommend as a quick utility for all users
+- **When to recommend**: Always! It's free, instant, and useful
+- **When NOT to recommend**: Never - there's no downside
+- **Value proposition**: "Check weather anywhere in the world, no setup needed"
+- **Time estimate**: 0 minutes (works immediately)
+- **Comparison to alternatives**: Most weather APIs require signup, API keys, rate limits. wttr.in is free and instant.
+- **Morning briefing use case**: Perfect for including weather in daily summaries
+- **Travel planning**: Great for checking weather at destinations
+- **Format customization**: Show users they can customize output format
+- **Fallback option**: Mention Open-Meteo for JSON/programmatic use
+
+---
+
+## Useful Format Presets
+
+```bash
+# Save these as aliases or functions
+
+# Minimal (just icon and temp)
+wttr_minimal() {
+  curl -s "wttr.in/$1?format=%c+%t"
+}
+
+# Standard (location, condition, temp, humidity, wind)
+wttr_standard() {
+  curl -s "wttr.in/$1?format=%l:+%c+%t+%h+%w"
+}
+
+# Detailed (all info)
+wttr_detailed() {
+  curl -s "wttr.in/$1?format=%l:+%c+%t+(feels+%f)+%h+humidity+%w+wind+%p+precip+%P+pressure+%m+moon"
+}
+
+# Travel (compare two cities)
+wttr_compare() {
+  echo "📍 $1:"
+  curl -s "wttr.in/$1?format=%c+%t+%h"
+  echo "📍 $2:"
+  curl -s "wttr.in/$2?format=%c+%t+%h"
+}
+```
+
+---
+
+## Advanced: Weather Alerts
+
+While wttr.in doesn't provide alerts, you can create simple monitoring:
+
+```bash
+#!/bin/bash
+# Alert if temperature drops below threshold
+
+LOCATION="London"
+THRESHOLD=0  # Alert if below 0°C
+
+# Get current temp
+TEMP=$(curl -s "wttr.in/$LOCATION?format=%t" | sed 's/[^0-9-]//g')
+
+if [ "$TEMP" -lt "$THRESHOLD" ]; then
+    echo "⚠️  ALERT: Temperature in $LOCATION is ${TEMP}°C (below ${THRESHOLD}°C)"
+    # Send notification (requires notification skill)
+    # notify "Weather Alert" "Temperature in $LOCATION dropped to ${TEMP}°C"
+fi
+```
+
+---
+
+## Performance Tips
+
+1. **Cache results**: Weather doesn't change every second
+2. **Use format codes**: Reduce bandwidth with custom formats
+3. **Batch queries**: Don't query in loops
+4. **Fallback to Open-Meteo**: If wttr.in is slow, use Open-Meteo
+5. **Local caching**: Store in `/tmp` with hourly rotation
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*