Guide · Agent skill
How to use the TimesFM forecasting agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The TimesFM forecasting skill teaches an AI agent to produce forecasts for ordered, time-based numbers, such as monthly sales or daily temperature readings, using Google's pretrained TimesFM model. You do not train a model on your data. This guide explains what the skill does, how to install it, how to ask for forecasts, and which safety and licence limits to know before you rely on the output.
TimesFM Time-Series ForecastingK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, upload it under Settings, Capabilities, Skills instead.
- 2Create the Python environment. Create a separate environment with uv and install the timesfm package with PyTorch, NumPy and pandas, using the quoted install command shown above.
- 3Run the system check. Run scripts/check_system.py before the first model download to confirm memory and disk space are adequate.
- 4Ask for a forecast. Describe your CSV, its date column, cadence and the horizon you need, in plain language.
- 5Check the results. Review the forecast file and the metadata sidecar, then evaluate accuracy and interval coverage on held-out past data before relying on the output.
What the skill makes the agent do
The skill performs zero-shot forecasting. The agent uses a pretrained TimesFM model to forecast a regular time series, so no task-specific training is needed. Along with point forecasts, it can produce quantile forecasts, which are ranges of likely values.
The skill also guides the agent through data preparation (checking that dates form a regular grid), optional covariates (XReg, extra variables known at the forecast origin), and held-out evaluation, where the model is tested on past data it did not see.
- Checks that dates are sorted, unique and form a complete regular grid
- Produces forecasts with 80% and 60% nominal bands and a median
- Evaluates accuracy across rolling origins against naive or seasonal-naive baselines
- Records the forecast origin, cadence, configuration and checkpoint revision in a metadata file
Install the skill (ZIP or Claude app upload)
Download the skill ZIP from this page. To add it to Claude Code, unzip it into your user skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it only for that project.
In the Claude apps, you can upload the skill instead. Open Settings, go to Capabilities, then choose Skills and add the ZIP.
- Personal use: ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills
Set up the Python environment
The skill runs Python scripts, so it needs Python 3.10 or newer, the timesfm package with PyTorch, and NumPy and pandas. Run the install in a separate environment. The skill's own install commands use uv and quote the extras, which matters in zsh.
The first run downloads the checkpoint from Hugging Face, so you need network access and some disk space for the cache. Optional covariate examples need JAX and scikit-learn; current JAX requires Python 3.12 or newer. Plotting example scripts need matplotlib.
- Required: Python 3.10+, timesfm with PyTorch, NumPy, pandas
- Optional: JAX and scikit-learn for XReg covariate examples
- Optional: matplotlib for example plots
- Hugging Face network access for the first checkpoint download
uv venv .venv-timesfm
uv pip install --python .venv-timesfm/bin/python "timesfm[torch]==3.0.2" numpy pandas
.venv-timesfm/bin/python scripts/check_system.pyTrigger the skill with natural requests
You do not need special syntax. Describe the data and what you want, and mention the file. Be specific about the date column, the frequency and the forecast horizon, because the skill needs them to validate the time grid.
Good requests name the cadence (for example monthly), the columns to forecast and how far ahead to look. If you do not give these, the agent should ask or state its assumptions.
- "Forecast the next 12 months of sales in monthly_sales.csv. Dates are in the date column and the data is monthly."
- "Give me a 24-step forecast with prediction intervals for the temperature column, and test it on the last 12 months first."
- "Compare the TimesFM forecast with a seasonal-naive baseline on this daily CSV."
Run a forecast from a CSV
The bundled CSV helper validates the file before loading it. It sorts dates, rejects duplicate headers and dates, and checks that the grid is complete. Missing values cause an error by default. The option --missing interpolate fills only internal gaps, never leading or trailing values. Use --value-cols to exclude numeric ID columns.
The horizon must be between 1 and 1,024 for this quantile-head workflow. Use --nonnegative only when the target is truly nonnegative.
- --date-col names the date column; without it, row order is treated as the regular grid
- --freq sets the cadence, for example MS for month starts
- --horizon sets the number of steps ahead
- --output writes the forecast file
python scripts/forecast_csv.py monthly_sales.csv --date-col date --freq MS --value-cols sales,revenue --horizon 12 --batch-size 1 --nonnegative --output forecasts.csvRead the output and intervals correctly
The output file contains forecast, median, lower_80, upper_80, lower_60 and upper_60 columns. These bands come from the 10th to 90th and 20th to 80th quantiles. Treat them as nominal intervals: they are not calibrated coverage until you test them on your own data.
A .metadata.json sidecar file records the origin, cadence, model revision and configuration, so you can reproduce the run.
- forecast and median: central estimates
- lower_80/upper_80: nominal 80% band
- lower_60/upper_60: nominal 60% band
- Check interval coverage and width by horizon during evaluation
Safety notes: scripts and network
The skill runs scripts and downloads model weights from Hugging Face, so review the scripts before running them and run them in a dedicated environment. The skill's own workflow runs a system check before loading weights, because its RAM and cache thresholds are heuristics and not a guarantee against running out of memory. Start with batch size 1.
Do not use the forecasts for causal questions, clinical or safety-critical decisions, or climate policy. The bundled temperature example is illustrative only and its data provenance is not verified.
- Run scripts/check_system.py before downloading weights
- Use a batch size of 1 at first and measure peak memory
- Do not treat the example temperature data as authoritative
- Use the non-commercial 3.0 checkpoint only for non-commercial, non-production work
What people use it for
- Producing a quick baseline forecast of monthly sales from a regular CSV
- Testing a forecasting pipeline with held-out evaluation and reproducibility metadata
- Comparing zero-shot forecasts against naive or seasonal-naive baselines for a research project
Frequently asked questions
How do I install the TimesFM forecasting skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings, Capabilities, Skills.
What do I need to run the TimesFM skill?
You need Python 3.10 or newer, the timesfm package with PyTorch, NumPy and pandas, and network access to download the checkpoint on first use. JAX and scikit-learn are optional, for covariate examples.
Is the TimesFM forecasting skill free to use?
The skill is MIT licensed. The default 2.5 checkpoint has Apache-2.0 weights, but the newer 3.0 checkpoint's downloaded weights are restricted to non-commercial, non-production use, so check those terms before any commercial work.
Can TimesFM be used for causal analysis or intervention effects?
No. The skill states that TimesFM is not a causal effect estimator, so its forecasts describe patterns, not cause and effect.
What if the CSV forecast fails validation?
The helper rejects unsorted or duplicate dates, incomplete grids and missing values by default. Fix the gaps or duplicates in your data, or use --missing interpolate only if you accept filling internal gaps.
How do I check whether the forecast is any good?
Use held-out evaluation across rolling origins and compare against a naive or seasonal-naive baseline. The skill also recommends checking interval coverage and width by horizon, since the quantile intervals are nominal until calibrated.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you need a fast, reproducible baseline forecast of a regular time series from a CSV, and you can validate it on your own held-out data. Pick something else for causal questions, clinical or safety-critical decisions, or commercial production use of the 3.0 checkpoint.
Download the skill