sports-skills
A lightweight, zero-config Python SDK and CLI for live sports data and prediction markets.
Built natively for AI agents, but works perfectly as a standalone Python library for developers. Wraps publicly available sports data sources and APIs into unified, deterministic commands.
Zero API keys. Zero signup. Just works.
📦 Installation
Install as a global CLI tool (recommended for agents):
uv tool install sports-skills
# or
pip install sports-skills
Base install includes all sports modules.
Install as a Python library:
uv add sports-skills
# or
pip install sports-skills
Optional extras:
pip install "sports-skills[all]"
pip install "sports-skills[dev]"
⚡ What's Included
- Football (Soccer): ESPN, Understat, FPL, Transfermarkt, football-data.co.uk, ClubElo — 25 commands across 30 leagues
- US Sports: NFL, NBA, WNBA, NHL, MLB, College Football (CFB), College Basketball (CBB) — live scores, standings, depth charts, injuries, and leaders
- Analytics backends (same modules, second source): nflverse for NFL (EPA, weekly tables, 1999+), NBA Stats for NBA (shot charts, advanced ratings, 1946+), the official MLB Stats API (pitch-level velocity/spin/exit-velocity, 1901+), the official NHL API (coordinate play-by-play, 1917+), and the NCAA's own endpoints for college (FCS/D2/D3 scoreboards, March Madness bracket)
- Tennis: ATP and WTA tournament scores, rankings, calendars, and player profiles
- Golf: PGA, LPGA, and DP World tour scorecards and leaderboards
- College XC/TF: NCAA cross country and track & field — athlete profiles, personal records, meet results, and news via The Stride Report
- Volleyball: Nevobo — Dutch volleyball (Eredivisie, Topdivisie, Superdivisie) standings, schedules, results, clubs
- Racing: Formula 1 (via FastF1) — lap times, telemetry, and race results
- Esports: Dota 2 (OpenDota) and League of Legends esports (Leaguepedia) — pro matches, leagues, teams, and tournaments
- Prediction Markets: Polymarket & Kalshi live odds and order books, including esports implied-probability odds (CS2/LoL/Dota2)
- News: Multi-sport news aggregators
💻 CLI Usage
The package exposes a sports-skills binary.
List all supported sports:
sports-skills --help
List commands for a specific sport:
sports-skills nfl
Execute a command:
sports-skills nfl get_scoreboard --date 2026-02-24
sports-skills football get_current_season --competition_id premier-league
sports-skills polymarket search_markets --query "super bowl"
sports-skills news fetch_items --query "Lando Norris" --limit 5
sports-skills xctf get_news --limit 5
sports-skills xctf search_athlete --name "Jane Hedengren" --school "UT_college_f_BYU"
All CLI output is printed as strict JSON, making it perfect for AI agents (Claude, GPT, Gemini) to parse and reason over.
🐍 Python SDK Usage
You can use the exact same commands directly in your Python code:
from sports_skills import nfl, football, polymarket, xctf
# Get live NFL scores
scores = nfl.get_scoreboard(date="2026-02-24")
print(scores["data"]["events"])
# Get Premier League standings
table = football.get_season_standings(season_id="premier-league-2025")
print(table["data"]["standings"])
# Fetch live odds from Polymarket
markets = polymarket.search_markets(query="super bowl")
print(markets["data"]["markets"])
# Get latest NCAA XC/TF news from The Stride Report
news = xctf.get_news(limit=5)
print(news["data"]["articles"])
# Look up an athlete's PRs
profile = xctf.get_athlete_profile(athlete_id="9230145", school="BYU", name="Jane_Hedengren")
print(profile["data"]["prs"])
🏗️ AI Agent Integration
sports-skills is built on the Anthropic Level-3 Agent capability spec. Every command is deterministic and automatically generates its own JSON Schema.
To extract the OpenAI/Anthropic compatible tool schema for any module:
sports-skills nfl schema
Prints {sport, version, tools} — tools is one Anthropic/OpenAI-shaped tool definition per command.
Machina Sports Schema (canonical output)
Football event commands can emit the Machina Sports Schema envelope instead of the native payload: one provider's observation of one event, serialized as JSON-LD against the IPTC Sport Schema 1.1 profile, with a provider-id crosswalk, a capability report, and a provenance block naming the pinned upstream commit.
# One event → one envelope, printed directly
sports-skills football get_event_summary --event_id=740000 \
--format=machina-canonical --observed-at=2026-03-01T22:05:00+00:00
# A day's fixtures → {provider, format, events}, every event a full envelope
sports-skills football get_daily_schedule --date=2026-03-01 \
--canonical --observed-at=2026-03-01T22:05:00+00:00
--canonical is an alias for --format=machina-canonical. It is supported on football get_event_summary and football get_daily_schedule (also reachable as scores); every other command refuses the flag by name rather than wrapping data the schema does not describe.
--observed-at is required and must carry a UTC offset. It is never read from the clock: it is the one input that makes the document reproducible, and the reference fixtures this output is tested byte-for-byte against depend on it being stated rather than guessed.
Rights: prototype only. Every envelope carries rights: {"data_class": "open-public", "prototype_only": true, "commercial_use": false}. Gate a consumer against them with --consumer-tier:
sports-skills football get_event_summary --event_id=740000 --canonical \
--observed-at=2026-03-01T22:05:00+00:00 --consumer-tier=production
# → refused: rights-prototype-only, exit status 1
prototype (the default) is served. production refuses every envelope this package can produce, with one actionable finding and a nonzero exit status — including a query that returns nothing, which is refused before the provider is called, because the licence answer is the adapter's and not the result set's. For licensed data cleared for commercial use, see machina.gg.
The default output of every command is unchanged: no module on the native path imports the canonical package, and the CLI reaches it only when you ask for it by name.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for sports-skills 0.34.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| sports_skills-0.34.0.tar.gz | 478.0 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sports_skills-0.34.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.1 MB
Release files / sports_skills-0.34.0.tar.gz
| Download URL | sports_skills-0.34.0.tar.gz |
|---|---|
| Size | 478.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
48cc68cddccdc344a0db3ee006d86eb5939f397fbe922bf246bb99cef28119f6
|
|
BLAKE2b-256 checksum How to use checksums |
ca16fca556fa1420ebfe50a7e1393eb345f65c9df5f2fc89f7590ea434ec70de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / sports_skills-0.34.0-py3-none-any.whl
| Download URL | sports_skills-0.34.0-py3-none-any.whl |
|---|---|
| Size | 611.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
364a9ef6e851d7c418a0905cef1ec699e9baa4e88eee4cbd23385a4376f76cb6
|
|
BLAKE2b-256 checksum How to use checksums |
5fe6f4dadbb0922a3c6343c0e387007b5b93656d417e03f6a02ceef37e431bd8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logSecurity for sports-skills 0.34.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for sports_skills-0.34.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
