git:20260609.7560e07 to git:20260614.0ac8a9e

---

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:

---

# 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.