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 --help
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 get_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.get_markets(query="bitcoin")
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:
from sports_skills import nfl
import json
# Returns a list of dicts formatted exactly like Anthropic/OpenAI tools
schema = nfl.generate_schema()
print(json.dumps(schema, indent=2))
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.30.1.tar.gz.
File metadata
- Download URL: sports_skills-0.30.1.tar.gz
- Upload date:
- Size: 994.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b0841d3d77e6a379ded02419247f8c486842640323abb6a2ec29537ce856589c
|
|
| MD5 |
6c51ce7469beb7000273a080b08d319a
|
|
| BLAKE2b-256 |
7b1dda71e4c946b07271cb7f47fe5f37f4af15d9e2ce97b13545742b4555b390
|
Provenance
The following attestation bundles were made for sports_skills-0.30.1.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.30.1.tar.gz -
Subject digest:
b0841d3d77e6a379ded02419247f8c486842640323abb6a2ec29537ce856589c - Sigstore transparency entry: 2352393447
- Sigstore integration time:
-
Permalink:
machina-sports/sports-skills@fcfc029432756d92654ad1fcbdc0296242de73f7 -
Branch / Tag:
refs/tags/v0.30.1 - Owner: https://github.com/machina-sports
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@fcfc029432756d92654ad1fcbdc0296242de73f7 -
Trigger Event:
release
-
Statement type:
File details
Details for the file sports_skills-0.30.1-py3-none-any.whl.
File metadata
- Download URL: sports_skills-0.30.1-py3-none-any.whl
- Upload date:
- Size: 280.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 |
e8c425200d31187a87eca6a324878b2db06ca3af63b272196676fa102bf8544e
|
|
| MD5 |
8c206fbd2c21632f0f4c125bdae5c332
|
|
| BLAKE2b-256 |
cfaddccf7a80e7555ce8f11df0564f68a5a5ffb8dd650487989d9a552dd6e11a
|
Provenance
The following attestation bundles were made for sports_skills-0.30.1-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.30.1-py3-none-any.whl -
Subject digest:
e8c425200d31187a87eca6a324878b2db06ca3af63b272196676fa102bf8544e - Sigstore transparency entry: 2352393602
- Sigstore integration time:
-
Permalink:
machina-sports/sports-skills@fcfc029432756d92654ad1fcbdc0296242de73f7 -
Branch / Tag:
refs/tags/v0.30.1 - Owner: https://github.com/machina-sports
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@fcfc029432756d92654ad1fcbdc0296242de73f7 -
Trigger Event:
release
-
Statement type:
