Skip to main content

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-series for a task-neutral first look (sampling, periodicity, regime screen, next steps)
  • workflow run forecast-series for forecast plots, CSVs, and Markdown reports
  • workflow run forecast-panel for panel backtests, forecasts, model specs, and reports
  • workflow run activity-recognition for 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.json

On 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 periodic column in data/synthetic_signals.csv (time column t): 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 y of 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 ## Workflow section (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-agents

Inspect 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-agents

skills 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.md

Supported agents: claude, codex, gemini, windsurf, github.