opencode-skills-collection 4.0.71 → 4.0.73

package/bundled-skills/weather-model-run-discovery/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: weather-model-run-discovery
+description: "Resolve the newest complete numerical weather prediction cycle and forecast objects across provider mirrors without downloading full payloads."
+category: data
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-24"
+author: ShianMike
+tags: [weather, nwp, model-cycle, aws-s3, nomads, herbie]
+tools: [claude, cursor, gemini, codex]
+---
+
+# Weather Model Run Discovery
+
+## Overview
+
+Resolve a numerical weather prediction run before downloading model fields.
+Probe exact objects or narrow prefixes, verify a request-specific completion
+contract, and return the newest qualifying initialization with its source
+metadata.
+
+This skill decides *which run and objects exist*. Use
+`weather-model-data-fetching` afterward to transfer or subset the data.
+
+## When to Use This Skill
+
+- An application needs the newest usable GFS, GEFS, HRRR, RAP, NAM, or similar
+  model cycle.
+- The nominal latest cycle returns `404`, has only early forecast hours, or is
+  still changing.
+- Equivalent AWS, NOMADS, Google, Azure, or other mirrors must be compared
+  without silently mixing runs.
+- A scheduled job needs a bounded fallback to an older complete cycle.
+- The resolved run and provider must be recorded for later reproduction.
+
+Do not activate this skill when the initialization is already fixed or when the
+task is to download, decode, or interpret model variables.
+
+## Define Complete Before Probing
+
+Collect the following request contract:
+
+- model, domain, product, and ensemble member;
+- legal UTC cycle hours and cycle interval;
+- required forecast hours;
+- required companion objects, such as pressure and surface products;
+- required inventory or index sidecars;
+- provider priority and whether cross-provider fallback is allowed;
+- maximum lookback, maximum probes, and freshness requirement.
+
+A run is complete only when every sentinel required by the consumer exists.
+Examples include:
+
+- one product at one forecast hour for a single-image job;
+- both pressure-level and surface files for a sounding;
+- the terminal forecast hour needed by a time series;
+- every required member for an ensemble statistic.
+
+The presence of forecast hour zero does not prove that a run is complete.
+
+## Discovery Workflow
+
+1. Normalize the current time and all candidate initialization times to UTC.
+2. Enumerate only legal cycles, newest first, within the lookback bound.
+3. Build documented object keys for the exact model, product, member, and
+   forecast hour. Never recursively scan an entire bucket.
+4. Probe exact objects with `HeadObject`, HTTP `HEAD`, or a narrow paginated
+   prefix listing. A probe should retrieve metadata, not the model payload.
+5. Require every sentinel and sidecar in the completion contract. Reject zero-
+   length or obviously placeholder objects.
+6. For a live mirror that may expose objects before publication finishes,
+   repeat the metadata probe after a short bounded interval and require stable
+   size and object identity.
+7. Select the first complete candidate. A fallback provider must refer to the
+   same initialization, product, member, and forecast hour.
+8. Emit a resolution record before starting the download.
+
+Use a provider's documented cycle status page as supporting evidence, not as a
+substitute for probing the exact objects the consumer requires.
+
+## Minimal Resolver Example
+
+Keep provider-specific key construction separate from the selection rule. This
+example accepts a metadata-only `probe` callback so it can be used with S3,
+HTTP, or a test fixture.
+
+```python
+from datetime import datetime, timedelta, timezone
+
+
+def candidate_cycles(now, cycle_hours, lookback):
+    now = now.astimezone(timezone.utc).replace(minute=0, second=0, microsecond=0)
+    allowed = sorted(set(cycle_hours), reverse=True)
+    candidates = []
+    for days_back in range((lookback // 24) + 2):
+        day = (now - timedelta(days=days_back)).date()
+        for hour in allowed:
+            cycle = datetime(day.year, day.month, day.day, hour, tzinfo=timezone.utc)
+            if cycle <= now and now - cycle <= timedelta(hours=lookback):
+                candidates.append(cycle)
+    return sorted(set(candidates), reverse=True)
+
+
+def resolve_latest(now, cycle_hours, lookback, required_objects, probe):
+    """Return one complete run; probe(uri) returns metadata or None."""
+    attempts = []
+    for cycle in candidate_cycles(now, cycle_hours, lookback):
+        requested = required_objects(cycle)
+        found = {name: probe(uri) for name, uri in requested.items()}
+        missing = [name for name, metadata in found.items() if not metadata]
+        attempts.append({"cycle": cycle.isoformat(), "missing": missing})
+        if not missing:
+            return {
+                "initialization": cycle.isoformat(),
+                "objects": [
+                    {"role": name, "uri": requested[name], **found[name]}
+                    for name in requested
+                ],
+                "attempts": attempts,
+            }
+    raise LookupError(f"no complete run within {lookback} hours: {attempts}")
+```
+
+The caller must make `required_objects` express the real completion contract;
+checking a single convenient file defeats the purpose of discovery.
+
+## Public S3 Diagnostics
+
+For public NOAA Open Data buckets, inspect exact objects without loading AWS
+credentials:
+
+```bash
+aws s3api head-object --no-sign-request \
+  --bucket BUCKET \
+  --key "EXACT/DOCUMENTED/OBJECT"
+
+aws s3api list-objects-v2 --no-sign-request \
+  --bucket BUCKET \
+  --prefix "MODEL.DATE/DOMAIN/PRECISE-RUN-PREFIX" \
+  --max-items 100
+```
+
+Paginate narrow listings. S3 returns at most one page at a time, and a
+successful listing still needs defensive response parsing. `403` and `404`
+from `HeadObject` can be intentionally nonspecific; distinguish a missing
+public object from a permission or endpoint error before falling back.
+
+## Resolution Record
+
+Return enough information for the fetcher and provenance layer to use the exact
+same objects:
+
+```json
+{
+  "requested_at_utc": "2026-09-18T08:45:00Z",
+  "model": "hrrr",
+  "product": "prs",
+  "initialization": "2026-09-18T06:00:00Z",
+  "required_forecast_hours": [0, 6, 18],
+  "provider": "aws",
+  "objects": [
+    {
+      "role": "pressure_f018",
+      "uri": "s3://bucket/exact-key",
+      "size_bytes": 123456,
+      "etag": "opaque-object-identity",
+      "last_modified": "2026-09-18T07:12:34Z"
+    }
+  ],
+  "fallback_cycles_rejected": []
+}
+```
+
+Keep ETags as opaque identity values. They are not guaranteed to be full-file
+MD5 checksums.
+
+## Reliability and Caching
+
+- Cache positive results only briefly enough for the model cadence and
+  publication latency. Cache negative probes for a shorter interval.
+- Retry timeouts, `408`, `429`, and transient `5xx` responses with bounded
+  exponential backoff and jitter; honor `Retry-After`.
+- Bound lookback and total probes so a provider outage cannot create an
+  unbounded bucket walk.
+- Do not treat one mirror's lag as proof that the run is absent everywhere.
+- Do not mix objects from different providers unless their run identity and
+  product semantics have been verified equivalent.
+- Record rejected cycles and missing sentinels so fallback is visible.
+
+## Verification Checklist
+
+- Candidate cycles are legal for the requested model and expressed in UTC.
+- Every required product, member, forecast hour, and sidecar is present.
+- Object sizes are nonzero and stable when a stabilization check is required.
+- The resolved provider and exact object identities are recorded.
+- The selected run satisfies the user's freshness and lookback bounds.
+- No model payload was downloaded merely to discover availability.
+- A failure reports which cycles were checked and which sentinels were absent.
+
+## Security & Safety Notes
+
+- Probe only public datasets or resources the user is authorized to access.
+- Never embed cloud credentials, signed URLs, session tokens, or private
+  endpoint details in a resolution record.
+- Keep TLS verification enabled. Unsigned public S3 access is not the same as
+  disabling certificate verification.
+- Bound prefix width, pagination, retries, and request rate before probing.
+- Treat provider object names and metadata as untrusted input when writing logs
+  or constructing local paths.
+
+## Common Pitfalls
+
+- **Newest cycle has `f000`:** Later required forecast hours are still
+  publishing. Test the actual terminal sentinels.
+- **A provider fallback changes the forecast:** The fallback changed a product,
+  member, or cycle as well as the mirror. Reject it.
+- **A listing found an object but the download changes:** The publisher was
+  still updating it. Require stable metadata or conditional reads.
+- **Discovery is slow and expensive:** The prefix is too broad or pagination is
+  unbounded. Construct exact keys wherever possible.
+- **Local time selected the wrong day:** Perform cycle arithmetic in UTC and
+  convert only for display.
+
+## Limitations
+
+- Publication schedules, provider retention, key layouts, and mirror status can
+  change; verify them against current provider documentation.
+- Metadata stability reduces the chance of a partial publication but does not
+  prove that the model contents are scientifically valid.
+- This skill does not fetch GRIB2 fields, decode model data, or assess forecast
+  quality.
+
+## Additional Resources
+
+- [NCEP NOMADS data availability](https://nomads.ncep.noaa.gov/)
+- [NCEP NOMADS status](https://nomads.ncep.noaa.gov/status.php)
+- [Herbie latest model run guidance](https://herbie.readthedocs.io/en/latest/user_guide/tutorial/latest.html)
+- [Amazon S3 `HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)
+- [Amazon S3 `ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html)
+- [Amazon S3 conditional requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-requests.html)

package/bundled-skills/weather-pipeline-performance-diagnosis/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: weather-pipeline-performance-diagnosis
+description: "Diagnose slow weather-data workflows by measuring discovery, transfer, parsing, scientific processing, and rendering separately before changing code."
+category: data
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-24"
+author: ShianMike
+tags: [weather, performance, profiling, diagnostics, pipelines]
+tools: [claude, cursor, gemini, codex]
+---
+
+# Weather Pipeline Performance Diagnosis
+
+## Overview
+
+Find the stage that actually makes a weather workflow slow before optimizing it.
+Measure the real runtime path from source discovery through the final artifact,
+including optional companion data and fallback work.
+
+This skill diagnoses latency and throughput. It does not prescribe a particular
+data provider, file format, decoder, or optimization.
+
+## When to Use This Skill
+
+- A fetch, sounding, map, animation, or batch job feels slower than before.
+- A parser or native backend is blamed without stage-level timing evidence.
+- Local runs and packaged or hosted runs have different performance.
+- A cache, provider fallback, optional enrichment, or rendering step may hide
+  the real cost.
+- A proposed performance fix needs a repeatable before-and-after comparison.
+
+Do not activate this skill for a correctness bug unless performance is also part
+of the observed failure.
+
+## Reproduce the Real Path
+
+Record one fixed workload before editing code:
+
+- requested source, time, location, variables, and output;
+- application commit and runtime version;
+- active implementation or backend, including fallback reason;
+- cold-cache or warm-cache state;
+- machine, operating system, worker count, and relevant resource limits;
+- bytes transferred and final artifact size;
+- whether optional guidance, overlays, or secondary sources were enabled.
+
+Use the same workload for the baseline and candidate measurement. A faster run
+with fewer inputs or a warm cache is not evidence that the original path
+improved.
+
+## Divide the Pipeline into Stages
+
+At minimum, time these boundaries independently:
+
+1. request validation and source discovery;
+2. availability checks and fallback selection;
+3. network transfer or cache read;
+4. parsing or decoding;
+5. supplemental-data retrieval;
+6. profile, grid, or derived-value construction;
+7. visualization or export;
+8. cleanup and final publication.
+
+Add sub-stages only where the first pass shows meaningful time. Preserve the
+existing behavior while instrumenting; diagnostics must not silently disable
+expensive work.
+
+## Lightweight Timing Example
+
+Use a monotonic clock and emit structured records that can be compared across
+runs:
+
+```python
+import json
+import time
+from contextlib import contextmanager
+
+
+@contextmanager
+def timed_stage(name, report):
+    started = time.perf_counter()
+    outcome = "ok"
+    try:
+        yield
+    except BaseException:
+        outcome = "error"
+        raise
+    finally:
+        report.append({
+            "stage": name,
+            "outcome": outcome,
+            "seconds": round(time.perf_counter() - started, 6),
+        })
+
+
+timings = []
+with timed_stage("source_discovery", timings):
+    source = discover_source()
+with timed_stage("transfer", timings):
+    local_path = fetch_source(source)
+with timed_stage("processing", timings):
+    result = build_result(local_path)
+
+print(json.dumps(timings, sort_keys=True))
+```
+
+Instrument production boundaries or the same public APIs used by production.
+Avoid a benchmark helper that bypasses the path users report as slow.
+
+## Interpret the Evidence
+
+- Long discovery with little transfer suggests broad listings, excessive
+  retries, provider timeouts, or repeated availability probes.
+- Long transfer with expected parsing time suggests bandwidth, object size,
+  throttling, or failure to reuse a valid cache.
+- Long parsing requires proof that the intended backend is active and that the
+  input volume is comparable.
+- Long processing after parsing points to interpolation, secondary retrieval,
+  profile construction, or repeated computation.
+- Long rendering can come from layout, rasterization, font loading, excessive
+  redraws, or large output dimensions.
+- High variance across identical runs suggests external services, contention,
+  cold starts, garbage collection, or uncontrolled parallelism.
+
+Measure wall time, CPU time, bytes, item counts, cache state, and worker count
+where they explain the result. A single total duration cannot locate a
+bottleneck.
+
+## Validate a Fix
+
+1. Preserve the baseline report and environment description.
+2. Change the smallest shared cause supported by the measurements.
+3. Rerun the identical workload several times in the same cache state.
+4. Compare the affected stage, total duration, output identity, and resource
+   use.
+5. Run correctness tests for the changed path.
+6. Report both improvement and measurement variability.
+
+Do not call a slowdown fixed when only a suspected backend, log message, or
+microbenchmark changed. Require an end-to-end result from the reported path.
+
+## Verification Checklist
+
+- The measured workload matches the user's slow workflow.
+- Active backend and fallback state are observed, not inferred.
+- Network, parsing, processing, rendering, and cleanup are separate timings.
+- Cold and warm cache results are labeled.
+- Optional or supplemental work remains visible.
+- Baseline and candidate use equivalent inputs, outputs, and worker settings.
+- The fix has correctness checks plus repeatable before-and-after evidence.
+
+## Security & Safety Notes
+
+- Remove credentials, signed URLs, private paths, and sensitive coordinates
+  from timing reports before sharing them.
+- Bound benchmark repetitions, downloads, concurrency, and disk usage.
+- Do not disable certificate verification or safety checks to improve timing.
+- Avoid profiling production services in a way that increases load without
+  authorization.
+- Keep diagnostic logs from capturing raw private datasets unnecessarily.
+
+## Common Pitfalls
+
+- **The decoder is blamed first:** Transfer or supplemental data dominates.
+  Measure each boundary before changing the decoder.
+- **The candidate looks faster:** It used a warm cache or smaller request.
+  Restore equivalent conditions.
+- **A unit benchmark passes:** The real application takes a fallback or render
+  path the benchmark omits. Measure the application entry point.
+- **A timing limit is raised:** No stage-level regression analysis was done.
+  Inspect evidence and rerun before changing a budget.
+- **Parallelism increases latency:** Workers contend for network, memory, or
+  decoder resources. Measure throughput and resource saturation together.
+
+## Limitations
+
+- External-service latency and hosted-runner capacity can remain variable even
+  with correct instrumentation.
+- Instrumentation has overhead; keep it lightweight and measure coarse stages
+  before adding fine-grained probes.
+- This skill identifies bottlenecks but does not determine whether an expensive
+  scientific operation is necessary or meteorologically appropriate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-collection",
-  "version": "4.0.71",
+  "version": "4.0.73",
   "description": "OpenCode CLI plugin that automatically downloads and keeps skills up to date.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",