Using and Customizing Skills
Skills are reusable workflow definitions that tell an AI agent how to use ts-agents workflows and tools for a specific task. Each skill is a Markdown file (SKILL.md) with YAML frontmatter describing the workflow, required tools, and step-by-step instructions.
The 10 canonical skills
| Skill | Description |
|---|---|
| diagnostics | First look at any series: sampling and gaps, descriptive stats, significance-tested periodicity, autocorrelation, a regime screen, and next steps |
| anomaly-detection | Unusual subsequences and outliers with matrix-profile discords (judged by robust_z), peaks, and decomposition residuals |
| segmentation | Change-points and regimes: mean/variance shifts (segment_changepoint) and shape changes (segment_fluss) |
| spectral-analysis | Power spectral density, dominant frequencies, spectral slopes, significance-tested periodicity, and coherence |
| decomposition | Trend/seasonal/residual decomposition via STL, MSTL, or Holt-Winters |
| activity-recognition | Labeled-stream activity recognition: window-size selection on training data and a held-out (optionally leave-subject-out) score |
| classification | Supervised time-series classification with KNN/DTW, ROCKET, or HIVE-COTE |
| forecasting | Forecast future values, choose baselines, compare methods (ARIMA, ETS, Theta, optional zero-shot foundation models) |
| panel-forecasting | Compare a seasonal baseline, global LightGBM/histogram GBM, NHITS and Darts zero-shot foundation models on long-format panels with rolling validation |
| report-generation | Convert workflow manifests, plots, JSON, CSV, and Markdown artifacts into stakeholder-facing Markdown, Quarto, HTML, or PDF reports |
All skills live in skills/<name>/SKILL.md. Agent export copies the complete skill directory, including supporting files such as forecasting/SKILL-pro.md. The byte-identical mirror in ts_agents/resources/skills/ supplies installed wheels and must be updated separately when canonical files change. Exports update current source files and preserve destination-only content, including local additions. After removing or renaming a source file, remove its obsolete export yourself or use a fresh destination for an exact snapshot. --symlink links each current file individually; re-export when adding files.
Invoking a skill
Skills work with any agent that reads project-level instruction files. Point the agent at the skill and provide context:
Claude Code
Run the activity-recognition skill on data/demo_labeled_stream.csv
Codex / other agents
Use the forecasting skill to inspect method availability and run
`workflow run forecast-series` on a single-series CSV with horizon 12
The agent reads the SKILL.md, discovers the required tools, and executes the workflow.
Customizing skill outputs
Workflow-first outputs vs low-level tool outputs
Prefer first-class workflows when the goal is an artifact bundle:
workflow run inspect-seriesfor a task-neutral first look (sampling, periodicity, regime screen, next steps)workflow run forecast-seriesfor forecast plots, CSVs, and Markdown reportsworkflow run forecast-panelfor panel backtests, forecasts, model specs, and reportsworkflow run activity-recognitionfor window-size and evaluation artifacts
Use tool run when you need one targeted analysis function and its saved JSON payload. Tools take data directly: --input loads the tool’s series parameter from a CSV, TSV, parquet, JSON, or JSONL file. Use --input-json or --param for inline values and for tools without a series parameter.
Loading data into tools
--value-col selects the series column. With --time-col, rows are ordered by time and sampling is checked; gaps or irregular steps are reported in input.warnings. A regular numeric time column also sets sample_rate for tools that accept one (input.series.sample_rate_source: time_column). Datetime axes keep results in samples. Every tool response has quality_status ok, or review when the result or the input carries warnings. Invalid, too-short, non-finite, or multichannel input to a univariate tool fails with ok: false.
A source checkout includes data/synthetic_signals.csv, a 50 Hz table with known answers (see data/README.md), so the results of these commands can be checked:
# Significance-tested period: about 0.5 s on the 2 Hz column
ts-agents tool run detect_periodicity \
--input data/synthetic_signals.csv --time-col t --value-col periodic \
--json --save outputs/periodicity.json
# Mean shift near sample 1000 and variance change near sample 2000
ts-agents tool run segment_changepoint \
--input data/synthetic_signals.csv --value-col regime \
--json --save outputs/changepoints.json
# Flatlined oscillation at samples 1500-1529: top discord with a large robust_z
ts-agents tool run find_discords \
--input data/synthetic_signals.csv --value-col anomaly --param m=100 \
--json --save outputs/discords.json
# Your own file
ts-agents tool run stl_decompose --input data.csv --value-col y \
--param period=12 --json --save outputs/stl.jsonOn 3000 samples, segment_changepoint resolves change-points to a coarse jump grid and returns quality_status: review with a warning; pass --param jump=1 for full resolution.
Tools return data, not plots. Workflows write plots, CSVs, and Markdown reports under --output-dir (or an auto-generated run directory) and list them in run_manifest.json. --extract-images applies only to saved legacy outputs that still contain embedded [IMAGE_DATA:...] tokens.
PDF reports via a mixed workflow/tool skill
A skill can combine workflows (for plots) with targeted tools (for structured results), compose a Quarto document, and render it to PDF. Here is a complete SKILL.md example; ts-agents skills validate accepts it:
---
name: comprehensive-report
description: Diagnostic, spectral, decomposition, pattern, and forecast analysis of one series rendered as a PDF report
metadata:
domain: time-series
tasks: [report, pdf, comprehensive]
ts_agents:
preferred_workflow: inspect-series
preferred_tools: [describe_series, compute_psd, stl_decompose, find_discords, segment_changepoint]
artifact_checklist: [summary.json, autocorrelation.png, forecast_comparison.png, report.pdf]
---
# Comprehensive report
## When to use
Use when the user wants one PDF that covers diagnostics, spectral content,
decomposition, anomalies, change-points, and a forecast comparison for a
single series in a CSV, parquet, or JSON file.
## Workflow
Inputs: `$DATA` (file), `$TIME` (time column), `$COL` (value column), and
`$OUT` (output directory). Save every response as JSON and check its `ok` and
`quality_status` fields before using it.
### 1. Diagnose with the workflow
```bash
ts-agents workflow run inspect-series --input $DATA --time-col $TIME --value-col $COL --output-dir $OUT/inspect --json --save $OUT/inspect.json
```
Read `result.data.periodicity` in `inspect.json`. When `detected` is true, set
`$P` to `dominant_period` rounded to whole samples. When it is false, do not
invent a period: skip STL and choose the discord length `m` from the domain.
### 2. Targeted tools (structured data, no plots)
```bash
ts-agents tool run describe_series --input $DATA --value-col $COL --json --save $OUT/describe.json
ts-agents tool run compute_psd --input $DATA --time-col $TIME --value-col $COL --json --save $OUT/psd.json
ts-agents tool run stl_decompose --input $DATA --value-col $COL --param period=$P --json --save $OUT/stl.json
ts-agents tool run find_discords --input $DATA --value-col $COL --param m=$P --json --save $OUT/discords.json
ts-agents tool run segment_changepoint --input $DATA --value-col $COL --json --save $OUT/changepoints.json
```
### 3. Forecast comparison with the workflow
```bash
ts-agents workflow run forecast-series --input $DATA --time-col $TIME --value-col $COL --horizon $P --season-length $P --methods seasonal_naive,theta,arima --output-dir $OUT/forecast --json --save $OUT/forecast.json
```
### 4. Compose the Quarto document
Create `$OUT/report.qmd`. Embed the workflow plots
(`inspect/autocorrelation.png`, `forecast/forecast_comparison.png`). Tools
return arrays rather than images: plot `stl.json` (`result.trend`,
`result.seasonal`, `result.residual`) and `psd.json` (`result.frequencies`,
`result.psd`) in a code cell, and tabulate the discords (`index`, `robust_z`)
and change-points (`changepoints`, `segment_stats`).
### 5. Render to PDF
```bash
cd $OUT && quarto render report.qmd --to pdf
```
## Guardrails
- If a tool returns `ok: false`, record the error and continue with the rest.
- Copy `result.warnings` and `input.warnings` from any response with
`quality_status: review` into the report instead of dropping them.
- Judge discords by `robust_z`; top-k discords exist even in pure noise.Example prompts
These prompts ask an agent to run the comprehensive workflow:
Run a full analysis of the
periodiccolumn in data/synthetic_signals.csv (time columnt): diagnostics, PSD, STL decomposition, discords, change-points, and a Theta + ARIMA forecast comparison over one period. Render a PDF report.
I need a comprehensive PDF report for every value column in data.csv (time column
ds). For each column: run inspect-series, compute the PSD, decompose with STL when a period is detected, and compare forecasts 20 steps ahead with ETS and Theta. Compile everything into a single Quarto PDF.
Requesting deeper analysis
Chain skills in a single prompt:
Run diagnostics on column
yof data.csv to check for a significant period, then decompose with STL if one is detected, then forecast 30 steps ahead using ARIMA and Theta. Compare the forecasts.
This produces diagnostics artifacts, decomposition plots, and a forecast comparison — all in one session.
Modifying skill behavior
Edit skills/<name>/SKILL.md directly:
- Add a step — append to the
## Workflowsection (e.g., “7. Compare STL and Holt-Winters residuals”) - Change defaults — edit parameter values in the workflow steps
- Add guardrails — insert validation steps (e.g., “If the series has fewer than 100 points, warn the user and stop”)
After editing, copy the changed files to the same packaged-mirror paths, run the existing integrity check, and re-export when agent directories need it:
# Source checkout: mirror integrity and command discovery
uv run --no-sync python -m pytest -q tests/cli/test_skills.py
ts-agents skills validate
ts-agents skills export --all-agentsInspect per-agent outcomes: a failed destination makes the export fail rather than silently leaving a partial installation. See skills/README.md for the canonical authoring procedure.
Creating a new skill
skills/
my-skill/
SKILL.md # required — workflow definition
SKILL.md structure:
---
name: my-custom-skill
description: One-line description of what the skill does and when to use it
compatibility: "ts-agents CLI (`ts-agents`)"
metadata:
domain: time-series
tasks: [keyword1, keyword2]
ts_agents:
tool_category: statistics
preferred_workflow: inspect-series
preferred_tools: [describe_series, compute_autocorrelation]
---
# My custom skill
## When to use
What problem this skill solves.
## Workflow
1. Run `ts-agents tool run describe_series --input data.csv --value-col y --json`.
2. Run `ts-agents tool run compute_autocorrelation --input data.csv --value-col y --json`.
3. Summarize results, including any `quality_status: review` warnings.
## Guardrails
- Validation rules, limits, warnings.Validate and export:
ts-agents skills validate
ts-agents skills export --all-agentsskills validate rejects tool and workflow names (in preferred_tools, avoid_tools, preferred_workflow, or ts-agents tool|workflow run ... commands in the body) that the installed CLI does not provide.
Export and sync commands
# List registered skills
ts-agents skills list
# Validate frontmatter
ts-agents skills validate
# Export to all agent directories (copy)
ts-agents skills export --all-agents
# Export with symlinks (local dev, Unix only)
ts-agents skills export --all-agents --symlink
# Export to a single agent
ts-agents skills export --agent claude
# Generate an aggregate summary
ts-agents skills export --out skills/SKILLS.mdSupported agents: claude, codex, gemini, windsurf, github.