feat: ship first-party timesfm-forecasting Agent Skill (agentskills.io)

[borealBytes]

What this adds

A timesfm-forecasting/ directory — a compliant Agent Skill that teaches AI agents how to use the TimesFM API correctly.

Agents that support the open Agent Skills standard (OpenCode, Cursor, Codex, and others) discover and install skills like this:

cp -r timesfm-forecasting/ ~/.cursor/skills/
cp -r timesfm-forecasting/ ~/.claude/skills/

Once installed, the agent reads SKILL.md at startup and gets accurate, production-ready knowledge of the TimesFM API — correct quantile indices, mandatory system check before model load, full ForecastConfig reference — before writing a single line of code.

---

Structure

timesfm-forecasting/          ← skill root (name matches SKILL.md `name` field per spec)
├── SKILL.md                  ← required: frontmatter + instructions
├── scripts/
│   ├── check_system.py       ← mandatory preflight: RAM / GPU / disk / Python / package check
│   └── forecast_csv.py       ← CLI: CSV in → forecast CSV out, any horizon, any columns
├── references/
│   ├── api_reference.md      ← ForecastConfig full docs, output shapes, model options
│   ├── data_preparation.md   ← input formats, NaN handling, CSV loading, covariate setup
│   └── system_requirements.md ← hardware tiers, memory estimation formulas
└── examples/
    ├── global-temperature/   ← basic forecast: NOAA CSV → PNG + animated GIF
    ├── anomaly-detection/    ← two-phase: detrend + Z-score + quantile PI
    └── covariates-forecasting/ ← forecast_with_covariates() XReg demo

AGENTS.md at repo root is a lightweight entry point for agents working directly in this repo (points to the skill and provides install instructions).

---

SKILL.md covers

• When to use TimesFM vs. statsmodels / aeon / scikit-learn
• Mandatory preflight system check (RAM, GPU, disk, Python version)
• Hardware requirements for all model versions (1.0, 2.0, 2.5)
• Full ForecastConfig parameter reference with "when to change" guidance
• Three complete, runnable workflows (single series, batch, evaluation)
• GPU acceleration + batch size tuning + memory-constrained chunking
• Model version history with all HuggingFace checkpoint names
• Quality checklist — 10 items to verify before declaring a task done
• Common mistakes — 8 documented bugs with fixes
• Regression verification commands for all three examples

---

No existing files modified

Everything lives under timesfm-forecasting/ and AGENTS.md. The existing src/, v1/, notebooks/, and README.md are untouched.

---

Testing

All three examples verified (see comments below for output images):

Example	Acceptance criteria
examples/global-temperature/	point_forecast has 12 values; PNG shows context + forecast + PI bands; GIF animates 25 frames
examples/anomaly-detection/	Sep 2023 flagged CRITICAL (z ≥ 3.0); injected anomalies detected in forecast window
examples/covariates-forecasting/	108-row CSV (3 stores × 36 weeks); distinct price arrays per store

Regression commands in SKILL.md under Validation & Verification.

---

CLA

⚠️ Contributor needs to sign the Google CLA before merge: https://cla.developers.google.com/

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[borealBytes]

🌡️ Example 1 — Global Temperature Forecast

📁 examples/global-temperature/

The baseline example. Loads 564 rows of NOAA global temperature anomaly data (2022–2024), runs a zero-shot 12-month forecast with TimesFM 1.0, and outputs a static visualization plus a 25-frame animated GIF showing how the forecast evolves as more historical context is added.

📊 Forecast Visualization

---

🎬 Forecast Evolution Animation (25 frames)

Each frame adds one month of context (12 → 36 months). Watch the forecast tighten as the model sees more of the warming trend.

---

Key metrics

	Value
Context window	36 months (2022-01 → 2024-12)
Forecast horizon	12 months
Final context value	+1.24 °C (Dec 2024)
Point forecast range	~1.1–1.3 °C
PI bands shown	80% and 60%

Run it

cd timesfm-forecasting/examples/global-temperature
python run_forecast.py       # → output/forecast_output.json
python visualize_forecast.py # → output/forecast_visualization.png
python generate_animation_data.py && python generate_gif.py # → output/forecast_animation.gif

[borealBytes]

🔍 Example 2 — Anomaly Detection (Two-Phase Method)

📁 examples/anomaly-detection/

TimesFM has no built-in anomaly detection, but its calibrated quantile intervals make it a natural fit. This example uses a two-phase approach combining classical detrending with TimesFM's prediction intervals.

📊 Anomaly Detection Output

---

How it works

Phase 1 — Context (historical 36 months, 2022–2024):

• Linear detrend via np.polyfit → compute residuals
• Z-score the residuals (σ ≈ 0.114 °C)
• Flag: WARNING if |z| ≥ 2.0, CRITICAL if |z| ≥ 3.0
• ✅ Sep 2023 correctly flagged CRITICAL (actual = +1.47 °C, z = +3.03) — the record-breaking heat spike

Phase 2 — Forecast (12 months):

• 4 synthetic anomalies injected into the forecast window
• Flagged using TimesFM 80%/90% quantile prediction intervals
• Points outside the 90% CI → CRITICAL; outside 80% CI → WARNING

Results

Window	Normal	Warning	Critical
Context (36 mo)	35	0	1 (Sep 2023)
Forecast (12 mo)	8	2	2

Run it

cd timesfm-forecasting/examples/anomaly-detection
python detect_anomalies.py
# → output/anomaly_detection.json
# → output/anomaly_detection.png

[borealBytes]

📈 Example 3 — Covariates / XReg Forecasting

📁 examples/covariates-forecasting/

Demonstrates the forecast_with_covariates() API introduced in TimesFM 2.5. Uses synthetic 3-store weekly retail data with price as a dynamic numerical covariate, day-of-week as a dynamic categorical covariate, and store type as a static categorical covariate.

📊 Covariate Decomposition (2×2 layout, shared x-axis)

---

Dataset

Store	Type	Base Price	Avg Weekly Sales
store_A	premium	$12.00	~1,060 units
store_B	standard	$10.00	~815 units
store_C	discount	$7.50	~550 units

Output CSV: 108 rows (3 stores × 36 weeks = 24 context + 12 horizon)

Covariate types used

Type	Field	Values
dynamic_numerical	price	per-store weekly prices (known future)
dynamic_categorical	day_of_week	0–6 (Mon–Sun)
static_categorical	store_type	premium / standard / discount

⚠️ Requires TimesFM 2.5 + pip install timesfm[xreg] — forecast_with_covariates() does not exist in TimesFM 1.0 or 2.0.

Run it

pip install timesfm[xreg]
cd timesfm-forecasting/examples/covariates-forecasting
python demo_covariates.py
# → output/sales_with_covariates.csv  (108 rows)
# → output/covariates_data.png
# → output/covariates_metadata.json

[borealBytes]

Why this PR exists — and why it matters

Saw Nic Borensztein's post a couple weeks back and it crystallized something I'd been thinking about:

"The CLI gives agents access. The skill gives them competence."

That's exactly right. Without a skill, agents act sloppily — wrong API calls, wrong quantile indices, OOM crashes on first model load. The documentation exists, but agents don't read it the way humans do. A SKILL.md is the bridge.

I'd just submitted a similar skill to K-Dense AI's scientific skills repo — currently the largest collection of research-focused agent skills I can find, covering 140+ scientific Python packages and databases. I was already building skills there (scientific writing standards, markdown/mermaid documentation pipelines), so TimesFM was a natural next addition. But a first-party skill belongs here, not just in a third-party library.

The man page analogy is real. Early Linux shipped full documentation with every tool — man grep gave you the exact docs for your exact version, offline, authoritative, no Googling. Fast internet killed that discipline. SKILL.md is how we get it back: documentation that ships with the code, versioned together, always in sync.

There's also a security angle nobody talks about: if you don't ship your own skill, someone else will. Third-party skills carry no license provenance, no safety guarantees, no official boundaries for what agents should and shouldn't do with your API. First-party skills let you own that contract.

This is me nudging things forward on free trials and leftover credits. Happy to do more — better skills, skill scaling patterns, security/deployment ideas — but I'm running on fumes. Open to a conversation, AI credits, or even just a PR merge or comment from the team. Either way, I hope this is useful. Take it and make it better.

— Clayton Young / @borealBytes / Superior Byte Works

[borealBytes]

Closing in favor of ##369