How to use the TimesFM Time Series Forecasting agent skill

What is an agent skill and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file and optional scripts and examples. When the folder is installed, an AI agent can read the instructions and follow them for matching tasks. This skill is licensed under Apache-2.0.

For time series work, the skill tells the agent to first run a preflight system checker that estimates whether your machine has enough memory, then load the TimesFM model and return point forecasts with quantile prediction intervals. The model works zero-shot, meaning it forecasts a series it has not been trained on without any training step from you.

• Point forecast: a median prediction for each future step.
• Quantile prediction intervals: for example the 10th to 90th percentile bands.
• Covariate forecasting (XReg): uses extra input variables such as price, promotions or holidays.
• Examples in the folder: anomaly detection, covariate forecasting, LoRA fine-tuning and a global temperature forecast.

Install the timesfm-forecasting skill

Download the skill ZIP from this page and unzip it into one of these locations. Use ~/.claude/skills/ to make the skill available to you across projects, or a project's .claude/skills/ folder to limit it to one project.

Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Check your machine before the first run

The SKILL.md says the preflight checker must be run before the model is loaded for the first time. It checks available RAM, GPU availability, disk space, the Python version and whether timesfm and torch are already installed. From the skill folder, run the checker with the command below.

To estimate memory for a specific dataset, the skill documents extra flags. The memory formula in the skill is RAM ≈ 0.8 GB (model) + 0.5 GB (overhead) + (0.2 MB × num_series × context_length / 1000).

• RAM under 4 GB produces a warning; under 2 GB the check blocks loading.
• Disk needs at least 2 GB free for the model download.
• The checker may block loading if the machine is short on memory or disk.

Install the TimesFM package and PyTorch

The skill lists the install commands below. Use the torch variant for PyTorch or the flax variant for JAX/Flax. For PyTorch, pick the wheel index that matches your hardware. Apple Silicon uses MPS, which the skill says is built into PyTorch.

Requirements: Python 3.10 or newer, PyTorch 2.0 or newer or JAX/Flax, and internet access to download the model weights (about 800 MB) from HuggingFace on first use.

• Optional covariates: pip install timesfm[xreg] (needs scikit-learn and JAX per the skill)
• Optional fine-tuning: transformers, accelerate, peft, pandas, pyarrow

Ask for a forecast in natural language

You do not need to type commands. Describe your series and the horizon you want, and attach or point to the CSV or data. The skill is meant for any univariate time series, so give the agent the values in time order and say how far ahead you want to predict.

The skill says not to use it for classification, clustering, tabular data that is not temporal, or cases where classical statistical coefficients must be interpreted. Ask for those tasks with the appropriate tools instead.

• "Forecast the next 24 hours of this sensor CSV and give me 10th to 90th percentile bands."
• "Forecast weekly sales for each store for the next 12 weeks using the attached file."
• "Flag readings in this temperature series that fall outside the 90% prediction interval."
• "Forecast demand with price and holiday as extra variables."

Understand the output and the minimal code

The skill's minimal example loads the TimesFM 2.5 200M PyTorch checkpoint, compiles it with a ForecastConfig, and calls forecast. The point output has shape (1, 24) for a 24-step horizon and the quantile output has shape (1, 24, 10), giving the 10th to 90th percentile bands.

For anomaly detection, the skill treats values outside the q10 to q90 band as statistically unusual. The skill's own table labels values inside the 80% interval as normal.

Safety notes: scripts and network access

This skill runs scripts and uses the network. The checker and examples are Python files in the skill folder, and model weights are downloaded from HuggingFace on first use and cached in ~/.cache/huggingface/. Read the scripts before running them, especially if you install a skill from an unfamiliar source.

Forecasts are statistical estimates. The skill's examples are illustrative and not validated for safety-critical or medical decisions, so do not base those decisions on the output alone.

• Model weights are not stored in the repository.
• Review scripts/check_system.py and the example scripts before running them.

Tips for better results

Use TimesFM 2.5 unless you have a specific reason to use an older checkpoint. The skill says it is smaller, faster and supports up to 16,384 context points, compared with 2,048 for the archived versions.

Use the dataset preflight estimate before large batches. If the estimate is too large, the skill suggests reducing context_length or processing series in chunks.

• Start with one series to confirm the setup works.
• Reduce context_length or batch size if memory is tight.
• Use the examples folder as a template for anomaly detection, covariates or fine-tuning.