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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sports_skills-0.31.0.tar.gz.
File metadata
- Download URL: sports_skills-0.31.0.tar.gz
- Upload date:
- Size: 1.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c4398dfd5047b41c546c1baac365c6e2f2af0658bac58fb5385c895c8d7602fe
|
|
| MD5 |
94a026f5d0c7bcc8120e3d5688bb7a79
|
|
| BLAKE2b-256 |
ec435cdc315d6ba9d0265c610021cb4f476e5cf83b2d3f2110df5a5faf32587a
|
Provenance
The following attestation bundles were made for sports_skills-0.31.0.tar.gz:
Publisher:
publish.yml on machina-sports/sports-skills
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sports_skills-0.31.0.tar.gz -
Subject digest:
c4398dfd5047b41c546c1baac365c6e2f2af0658bac58fb5385c895c8d7602fe - Sigstore transparency entry: 2414241427
- Sigstore integration time:
-
Permalink:
machina-sports/sports-skills@944c14e9895b7e541c4f80a536e0ec715db122fc -
Branch / Tag:
refs/tags/v0.31.0 - Owner: https://github.com/machina-sports
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@944c14e9895b7e541c4f80a536e0ec715db122fc -
Trigger Event:
release
-
Statement type:
File details
Details for the file sports_skills-0.31.0-py3-none-any.whl.
File metadata
- Download URL: sports_skills-0.31.0-py3-none-any.whl
- Upload date:
- Size: 332.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
10809011174c5e753658bf915996fd215f1e3c98d8f08b083e901ce4a0467c5c
|
|
| MD5 |
a6ecaf52b886fa6f5512f21783b6010a
|
|
| BLAKE2b-256 |
0506bb8c5f88aa6cae311edcf0d91c98776a7f0a92c2210b61938feb44a284c8
|
Provenance
The following attestation bundles were made for sports_skills-0.31.0-py3-none-any.whl:
Publisher:
publish.yml on machina-sports/sports-skills
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sports_skills-0.31.0-py3-none-any.whl -
Subject digest:
10809011174c5e753658bf915996fd215f1e3c98d8f08b083e901ce4a0467c5c - Sigstore transparency entry: 2414241558
- Sigstore integration time:
-
Permalink:
machina-sports/sports-skills@944c14e9895b7e541c4f80a536e0ec715db122fc -
Branch / Tag:
refs/tags/v0.31.0 - Owner: https://github.com/machina-sports
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@944c14e9895b7e541c4f80a536e0ec715db122fc -
Trigger Event:
release
-
Statement type:
