Docs

Human-facing guide for Sports Analytic Skills — standalone agent skills for sports analytics and modeling. Agents still read each skill’s SKILL.md. This page is so you don’t have to dig through folders to get oriented.

No edge claimed. This pack is a free jumpstart for learning a rigorous workflow. Unexpected paper-trading results are normal. They usually mean your setup, market, or validation path needs scrutiny — not that the pack is a signal service.

What this is / isn’t

This is

Portable agent skills for sports analytics
Guidance for EDA, features, models, validation, calibration, reporting
A way to learn time-safety and honest evaluation
Optional helpers for public NFL / NBA / MLB data

This is not

A betting tip product or guaranteed-profit system
A finished market model with claimed edge
Custom build-on-request support for every sport/market
A hosted dashboard or pick seller

If you want NCAAF totals, WNBA player props, or any other market model: use the skills against your data and build it yourself. That is the point.

Getting started

1. Install the skills

# Interactive
npx skills add WalrusQuant/sports-analytic-skills

# One skill
npx skills add WalrusQuant/sports-analytic-skills --skill eda-sports -y

# Entire pack for every detected agent
npx skills add WalrusQuant/sports-analytic-skills --all

No repository clone and no sports_ds install are required for skill-only use.

2. Start from the task

Give the agent the question, the decision time for predictive work, and the path to your CSV / Parquet / JSON.

Use eda-sports on data/team_games.parquet. Confirm the grain, coverage,
missingness, target balance, and any leakage risks before modeling.

Use validation-design on data/features.parquet. The prediction is made at
kickoff; create season walk-forward folds and lock the primary metric.

3. Let the skill enforce contracts

Each skill documents required fields. If the artifact is missing columns, the agent should report that instead of silently inventing them.

4. Optional helpers

Some skills ship scripts. Resolve helper paths relative to the installed skill’s SKILL.md, not your current working directory:

python /scripts/.py --help

Example prompts

Use sports-modeling-doctrine. I want to predict NFL game winners at kickoff
using team-game data. Lock target, decision time, baseline, and success criteria.

Use feature-rules and leakage-audit on this feature table. Decision time is
tipoff. Flag every column that would not have been knowable then.

Use baseline-models, predictive-modeling, and validation-design to compare a
constant baseline with logistic regression under season walk-forward folds.

Use calibration-check on these predicted probabilities and outcomes.
Report Brier, log loss, and reliability by bin.

Skill index

Foundation and data

Skill	Purpose
sports-modeling-doctrine	Lock question, target, decision time, baseline, success criteria
environment-setup	Portable analysis environment for the user’s project
data-sources	Choose a public data source and grain
nflreadpy	Load NFL data from nflverse
sportsdataverse-py	Load supported multi-sport public data
pybaseball	Load Statcast / MLB season data
sports-ds-bridge	Optional bridge to the sports_ds toolkit

Exploration and features

Skill	Purpose
eda-sports	Coverage, grain, missingness, targets, red flags
sports-visualization	Honest charts with context and uncertainty
anti-slop-analytics	Remove chartjunk and unsupported claims
feature-rules	Decision-time-legal feature design
time-series-sports	Shifted rolling / EWMA form features
ratings-strength-models	As-of Elo and strength ratings

Modeling and validation

Skill	Purpose
baseline-models	Constant, home, simple statistical baselines
statistical-modeling	GLMs, diagnostics, effects, uncertainty
predictive-modeling	Predictive models under honest time splits
validation-design	Walk-forward folds and locked metrics
leakage-audit	Look-ahead, target, join, preprocessing leakage
calibration-check	Probability reliability / recalibration
simulation-sports	Season / matchup simulation from probabilities

Interpretation and reporting

Skill	Purpose
model-interpretation	Drivers, slices, largest misses
results-reporting	Reproducible results with baselines and limits
model-card	Durable model contract
experiment-log	Reproducible experiment history

Analysis path

question and decision time
  -> data acquisition
  -> EDA
  -> time-safe features / ratings
  -> baselines and candidate models
  -> time-ordered validation
  -> leakage and calibration checks
  -> interpretation, simulation, and reporting

Combine only the skills the task needs. Do not force a full pipeline when EDA is the whole job.

Optional sports_ds toolkit

The skills work without this repository’s Python package. Use sports-ds-bridge only if you want prebuilt public-data adapters, normalized panels, or reference CLI pipelines.

git clone https://github.com/WalrusQuant/sports-analytic-skills.git
cd sports-analytic-skills
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

# optional multi-sport loaders
pip install -e ".[multi]"

sports-ds --help
sports-ds feature-registry

On macOS only, XGBoost (pulled by sportsdataverse) may need OpenMP: brew install libomp. Not required for skill-only installs.

Deeper repo markdown

Still in the repository for contributors and deep dives: