---
name: nws-weather-forecast
description: Fetch National Weather Service forecast evidence through the governed HTTP front, producing a sealed provider packet for downstream weather planning.
runx:
  category: data
---

# NWS Weather Forecast

Fetch public National Weather Service forecast evidence through runx HTTP.

This is a branded provider skill for the canonical `weather-forecast` verb. It
uses the governed HTTP front, not an ad hoc client: the receipt records the NWS
endpoint, response status, graph step receipts, and the exact authority surface.
No API key is required. The default runner fetches the actual NWS gridpoint
forecast; the `locate` runner discovers the gridpoint for a latitude/longitude.

## What this skill does

`nws-weather-forecast` makes read-only calls to `api.weather.gov`. The `locate`
runner calls `/points/{lat},{lon}` to discover `gridId`, `gridX`, `gridY`, and
forecast URLs. The default `forecast` runner calls
`/gridpoints/{office}/{grid_x},{grid_y}/forecast` to fetch forecast periods. The
output is provider evidence; use `weather-forecast` when an agent needs to
normalize that evidence for a planning decision.

## When to use this skill

- You need real public weather evidence with no credentials.
- A graph needs to prove a weather data read went through runx's governed HTTP
  path.
- You have an NWS office/gridpoint and need the current public forecast.
- You have latitude and longitude in the United States and need the NWS gridpoint
  before running the forecast path.

## When not to use this skill

- For locations outside NWS coverage. Return `needs_input` with the coverage
  limitation.
- For emergency, medical, aviation, maritime, evacuation, or life-safety
  decisions.
- To notify users, reschedule events, deploy changes, or mutate operations based
  on weather. Those actions need their own authority gate.
- To call private networks, untrusted hosts, or non-NWS endpoints.

## Procedure

1. If the caller has only coordinates, run `locate` with `lat` and `lon`.
2. Extract `gridId`, `gridX`, and `gridY` from the sealed locate output.
3. Run the default `forecast` runner with `office`, `grid_x`, and `grid_y`.
4. Confirm the HTTP status is 2xx and the response contains forecast periods.
5. Preserve the NWS source URL, generated timestamp, gridpoint, and receipt refs.
6. If an agent needs planning prose, pass the provider evidence to
   `weather-forecast`. Do not invent guidance inside this provider fetch.
7. Return `needs_input` for malformed coordinates or gridpoints; return
   `needs_more_evidence` for NWS outages, missing periods, or stale data.

## Edge cases and stop conditions

- **Invalid coordinates:** return `needs_input`; NWS point lookup requires
  decimal latitude and longitude.
- **Unsupported location:** return `needs_input`; NWS coverage is not global.
- **Provider outage or non-2xx response:** return `needs_more_evidence` and
  preserve the HTTP status in the receipt.
- **Missing forecast periods:** return `needs_more_evidence`; do not summarize a
  forecast that is not present.
- **Life-safety use:** return `refused` and direct the user to official weather
  or emergency channels.
- **Action requested from weather:** stop at provider evidence and require the
  downstream action skill with its own gate and receipt.

## Output schema

```yaml
decision: ready | needs_input | needs_more_evidence | refused
canonical_skill: runx/weather-forecast
runtime_path: http
provider: national-weather-service
provider_evidence:
  endpoint: string
  http_status: string
  gridpoint:
    office: string
    grid_x: string
    grid_y: string
  generated_at: string
  forecast_periods: array
receipt_refs: array
stop_conditions: array
```

## Worked example

1. Run `locate` for `38.8894,-77.0352`.
2. The sealed NWS points response returns `gridId: LWX`, `gridX: 97`,
   `gridY: 71`, and a forecast URL.
3. Run the default `forecast` runner with `office: LWX`, `grid_x: "97"`,
   `grid_y: "71"`.
4. Use the sealed forecast JSON as `forecast_evidence` for `weather-forecast`
   when a downstream agent needs a planning packet.

## Inputs

- `office` (default runner, required): NWS office id such as `LWX`.
- `grid_x` (default runner, required): NWS grid X coordinate.
- `grid_y` (default runner, required): NWS grid Y coordinate.
- `lat` (`locate` runner, required): decimal latitude for point lookup.
- `lon` (`locate` runner, required): decimal longitude for point lookup.
