# OpenWeather Skill for OpenClaw

## Overview

The **OpenWeather Skill** is a lightweight, security-conscious weather and forecast integration for OpenClaw agents.
It provides current conditions, short-term, and extended forecasts using the **OpenWeather One Call API 3.0**, optimized for conversational use rather than raw data delivery.

The skill is intentionally implemented as a **small Python CLI (stdlib only)** to keep behavior transparent, auditable, and easy to reason about in security reviews.

It is designed to be:
- Predictable
- Low-risk
- Easy to sandbox
- Suitable for public ClawHub distribution

---

## What This Skill Does

This skill enables an OpenClaw agent to answer weather-related questions such as:

- “What’s the weather right now?”
- “What’s the forecast for the next few days?”
- “Will it rain later today?”
- “How hot will it get tomorrow?”

It resolves human-readable locations to coordinates using OpenWeather Geocoding, then retrieves a **single unified forecast payload** from the One Call 3.0 API.

Each request uses:
- **1 geocoding call**
- **1 One Call API call**

No additional endpoints are accessed.

---

## Why OpenWeather One Call 3.0

OpenWeather One Call 3.0 provides a stable and comprehensive dataset in a single response, which is especially well suited for agent workflows.

Advantages:
- Current, hourly, and daily forecasts in one response
- Consistent field structure across time horizons
- Up to 8 days of forecast data
- Contextual signals such as UV index and moon phase
- Fewer API calls and fewer edge cases

This allows OpenClaw agents to produce clearer, more reliable answers with minimal glue logic.

---

## Changelog

### 1.0.2 — Packaging cleanup

- Removed duplicate top-level `weather.py` file.
- Skill now ships with a single executable CLI at `scripts/weather.py`.
- No behavioral or configuration changes.
- Improves clarity during security scans and code review.

### 1.0.1 — Documentation and behavior alignment

- Implemented true “default home location” behavior via `OPENWEATHER_DEFAULT_LOCATION`.
- CLI now uses the default location when no city is provided.
- Removed incorrect references to `curl`; implementation uses Python `urllib` only.
- Explicitly documented all configuration via environment variables.
- Ensured documented behavior matches runtime behavior exactly.

### 1.0.0 — Initial public release

- Initial OpenClaw-compatible weather skill.
- Supports current, hourly, and daily forecasts.
- Uses OpenWeather Geocoding + One Call API 3.0.
- Designed for low-risk, on-demand execution.

---

## Configuration

All configuration is done via environment variables.

Required:
- `OPENWEATHER_API_KEY`
OpenWeather API key with One Call 3.0 enabled.

Optional:
- `OPENWEATHER_UNITS`
Measurement units: `imperial`, `metric`, or `standard` (default: `imperial`)
- `OPENWEATHER_DEFAULT_LOCATION`
Default “home” location used when no city is provided (e.g. `Johnstown, PA, US`)

There are:
- No config files
- No hidden state
- No persistent storage

---

## Security Model

This skill is intentionally conservative.

- Uses Python standard library only
- No package installs
- No external downloads
- No file system access beyond execution
- No user data storage
- No background execution
- No elevated privileges

Network behavior:
- HTTPS only
- Requests restricted to OpenWeather domains
- Maximum of 2 API calls per request

Credentials:
- Reads only declared environment variables
- Does not transmit credentials outside OpenWeather endpoints