# HF Market Data — skills pack

Five Claude Code / Claude skills that turn <https://www.hfmarketdata.io> into a data-analysis workbench.
Each skill is a folder with a `SKILL.md` (when to use it, step-by-step, examples) and small Python scripts
(`requests` + `pandas`, `matplotlib` optional). No other dependency.

| Skill | Use it when you want to… |
|---|---|
| `hfmd-data-analysis` | pull bars for any symbol into pandas and get returns, volatility, drawdowns, seasonality, a chart |
| `hfmd-quick-backtest` | test a moving-average crossover (or any signal) with an honest walk-forward, costs, and a report |
| `hfmd-continuous-futures` | build or compare continuous futures series — roll rules, back-adjustment, vs the vendor series |
| `hfmd-fundamentals-screen` | screen US stocks on ratios, enrich with statements, keep point-in-time discipline |
| `hfmd-term-structure` | draw a futures curve, quantify contango/backwardation and roll yield, compare two dates |

## Install

```bash
# download
curl -LO https://www.hfmarketdata.io/downloads/hfmarketdata-skills.zip

# for every project (personal skills)
unzip -o hfmarketdata-skills.zip -d ~/.claude/skills/

# or for one project only (shared with the team through git)
unzip -o hfmarketdata-skills.zip -d .claude/skills/

pip install requests pandas matplotlib      # matplotlib only for the charts
export HFMD_API_KEY=hfmd_live_…             # optional: free API key = 120 req/min (keyless mode has low hourly limits)
# Everything is free. Higher limits are granted on request by e-mail to contact@spboucher.ai (also free) — see https://www.hfmarketdata.io/limits
```

Claude Code lists them under `/skills`; you can also just ask — "backtest a 20/100 MA crossover on SPY since 2015" triggers `hfmd-quick-backtest`.

## Layout

```
skills/
  _shared/hfmd.py                 single source of the API helper (copied into each skill by the build)
  hfmd-data-analysis/             SKILL.md · scripts/fetch_bars.py · scripts/analyze.py · scripts/hfmd.py
  hfmd-quick-backtest/            SKILL.md · scripts/ma_crossover.py · scripts/hfmd.py
  hfmd-continuous-futures/        SKILL.md · scripts/continuous_compare.py · scripts/stitch_local.py · scripts/hfmd.py
  hfmd-fundamentals-screen/       SKILL.md · scripts/screen.py · scripts/hfmd.py
  hfmd-term-structure/            SKILL.md · scripts/term_structure.py · scripts/hfmd.py
  scripts/build_skills.py         syncs _shared/hfmd.py → each skill, zips → web/public/downloads/hfmarketdata-skills.zip
```

## Build the zip

```bash
python3 skills/scripts/build_skills.py            # → hfmarketdata/web/public/downloads/hfmarketdata-skills.zip
python3 skills/scripts/build_skills.py --check    # fail if a copied hfmd.py drifted from _shared/
```

The zip is committed so the website can serve it without a build step.

## Conventions the scripts follow

- Never invent data: gaps stay `NaN`, and every script prints the row count and the date range it actually received.
- Intraday timestamps are naive US/Eastern (as delivered by the API); daily bars are dates.
- Respect the quota: keyless mode has low hourly limits (30 requests/hour) — scripts paginate by date only when needed and honour `Retry-After` on 429. A free API key lifts this to 120 req/min.
- Fundamentals are point-in-time: use `filed_at` (not `period_end`) to decide what was knowable on a given day.