sports-ds-bridge
Connect the optional sports_ds Python toolkit to the standalone sports analytics skills. Use when the user explicitly mentions sports_ds, wants its NFL/NBA/MLB public-data loaders or CLI, needs toolkit setup/troubleshooting, or wants to convert toolkit output into a skill's documented input artifact.
WalrusQuant · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add WalrusQuant/sports-analytic-skills --skill sports-ds-bridge技能说明
name: sports-ds-bridge description: > Connect the optional sports_ds Python toolkit to the standalone sports analytics skills. Use when the user explicitly mentions sports_ds, wants its NFL/NBA/MLB public-data loaders or CLI, needs toolkit setup/troubleshooting, or wants to convert toolkit output into a skill's documented input artifact. license: MIT metadata: version: "0.12.0"
Sports DS Bridge
Overview
sports_ds is an optional data and workflow accelerator that lives in the same
repository as this skill pack. It is not required by the other skills.
This bridge is the only skill allowed to talk about sports_ds setup, imports,
CLI commands, caches, and pipeline outputs. Its job is narrow:
- decide whether the toolkit is actually needed;
- set it up only with authorization;
- use the narrowest toolkit surface that satisfies the request;
- materialize a portable CSV / Parquet / JSON artifact;
- validate that artifact against the downstream skill's own contract;
- hand off to a standalone skill and stop.
The bridge is an integration boundary, not a second modeling stack. After the
handoff, generic skills must not call back into sports_ds.
Read references/toolkit-map.md for concrete imports and CLI routes. Read references/handoff-contracts.md before writing an artifact for another skill.
When to Use This Skill
Use this skill when:
- the user explicitly names
sports_ds,sports-ds, or this repository's toolkit; - the user wants the optional public-data loaders / normalized panels for NFL, NBA, or MLB;
- the user wants toolkit CLI reference pipelines or feature-registry output;
- the user needs setup, install, import, cache, or CLI troubleshooting for the toolkit;
- the user already has toolkit output and needs it translated into a portable artifact another skill can consume.
Do not use this skill when:
- the user already has usable CSV / Parquet / JSON and just wants EDA, features, models, validation, calibration, or reporting;
- a public loader skill (
nflreadpy,sportsdataverse-py,pybaseball,data-sources) is enough and the user did not ask for the toolkit; - you are tempted to make a generic skill "easier" by smuggling in a
sports_dsdependency; - the request is custom betting-market construction, pick selling, or claimed edge.
| Need | Prefer instead |
|---|---|
| Ordinary EDA on user data | eda-sports |
| Feature legality / leakage | feature-rules, leakage-audit |
| Baselines / predictive models | baseline-models, predictive-modeling |
| Public NFL load without toolkit | nflreadpy |
| Public MLB load without toolkit | pybaseball |
| Multi-sport source choice | data-sources / sportsdataverse-py |
| Environment only | environment-setup |
Installation
The toolkit is optional. Confirm it is missing before suggesting install, and get authorization before cloning or installing.
Check first
python -c "import sports_ds; print(sports_ds.__version__)"
sports-ds --help
If import works, do not reinstall. Record the version and continue.
Authorized install from the public repo
git clone https://github.com/WalrusQuant/sports-analytic-skills.git
cd sports-analytic-skills
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .
Optional multi-sport loaders (NBA/MLB via sportsdataverse / pybaseball):
python -m pip install -e ".[multi]"
Optional developer/test extras:
python -m pip install -e ".[dev]"
Compatibility notes:
- Python 3.10+ required.
- Base install covers NFL (
nflreadpy) and the scientific stack. - NBA/MLB team and player loaders need
.[multi]. - On macOS only, XGBoost pulled by sportsdataverse may need OpenMP:
brew install libomp. Not required for skill-only installs and usually unnecessary on Linux. - Keep installs inside a project venv. Do not modify system Python.
- Large public-data pulls and caches need explicit user authorization.
Decision workflow
Every bridge task follows this arc. Do not skip.
-
Name the downstream skill and its contract.
- What skill will consume the artifact?
- What grain, keys, and required fields does that skill document?
- If the contract is unknown, stop and open that skill first.
-
Decide whether
sports_dsis necessary.- User already has the table → skip the toolkit; hand the path to the skill.
- User wants public data only → prefer loader skills unless they asked for the toolkit.
- User asked for
sports_ds/ reference pipelines / normalized panels → continue.
-
Check importability before setup.
- Import +
sports-ds --helpfirst. - Install only with authorization when missing.
- Import +
-
Choose the narrowest surface.
- Loader/core API for data or one transform.
- CLI pipeline only when the user wants an end-to-end reference benchmark.
- Never default to the heaviest pipeline "to be helpful."
-
Materialize a portable artifact in the user's project.
- CSV / Parquet / JSON owned by the user.
- Stable path under their workspace (
data/,artifacts/, etc.). - No reliance on repo-relative paths or pipeline provenance.
-
Validate before handoff.
- Required columns present.
- Grain correct (team-game doubled? one row per decision? unique game ids?).
- Time fields usable for walk-forward.
- Missingness and row counts sane for the claimed window.
-
Hand off and stop.
- Tell the agent which standalone skill to run next.
- Do not keep modeling inside the bridge.
- Do not tell the next skill to import
sports_ds.
Choose the narrowest toolkit surface
| Need | Prefer | Avoid unless requested |
|---|---|---|
| NFL schedules / team-game panel | sports_ds.data.nfl | full win pipeline |
| NBA / MLB team-game pa |