/cbb-data

name: cbb-data
description: |
  College Basketball (CBB) data via ESPN public endpoints and the NCAA's official endpoints — scores, standings, rosters, schedules, game summaries, play-by-play, win probability, rankings, futures, team/player stats, and news for Division I men's basketball, plus official D2/D3 scoreboards, NCAA game detail, the March Madness bracket with live scores, and the schools index. Zero config, no API keys.

  Use when: user asks about college basketball scores, March Madness, the NCAA tournament bracket, standings, rankings, team rosters, schedules, play-by-play, betting futures, team/player statistics, CBB news, or D2/D3 games.
  Don't use when: user asks about NBA/WNBA (use nba-data/wnba-data), college football (use cfb-data), or non-sports topics.
license: MIT
metadata:
  author: machina-sports
  version: "0.1.0"

College Basketball Data (CBB)

Before writing queries, consult `references/api-reference.md` for endpoints, conference IDs, team IDs, and data shapes.

Setup

Before first use, check if the CLI is available:

which sports-skills || pip install sports-skills

If `pip install` fails with a Python version error, the package requires Python 3.10+. Find a compatible Python:

python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

No API keys required.

Quick Start

Prefer the CLI — it avoids Python import path issues:

sports-skills cbb get_scoreboard
sports-skills cbb get_rankings
sports-skills cbb get_standings --group=23

CRITICAL: Before Any Query

CRITICAL: Before calling any data endpoint, verify:

• Season year is derived from the system prompt's `currentDate` — never hardcoded.
• For standings, the `group` parameter is set to the correct conference ID (see `references/api-reference.md`).
• If only a team name is provided, use `get_teams` to resolve the team ID.

Choosing the Season

Derive the current year from the system prompt's date (e.g., `currentDate: 2026-02-28` → current year is 2026).

• **If the user specifies a season**, use it as-is.
• **If the user says "current", "this season", or doesn't specify**: The CBB season runs November–April. If the current month is November or December, use `season = current_year + 1`. If January–April, use `season = current_year`. If May–October (offseason), use `season = current_year` (most recently completed season).

Important: College vs. Pro Differences

• **Standings are per-conference** — use the `group` parameter to filter
• **Rankings replace leaders** — college uses AP Top 25 and Coaches Poll
• **Ranked teams** have a `rank` field (null = unranked) on scoreboard competitors
• **360+ D1 teams** — many games per day during the season (50+ during conference play)
• **March Madness** — NCAA Tournament runs in March/April with 68 teams

Commands

| Command | Description | |---|---| | `get_scoreboard` | Live/recent college basketball scores | | `get_standings` | Standings by conference (use `group` parameter) | | `get_teams` | All 360+ D1 men's basketball teams | | `get_team_roster` | Full roster for a team | | `get_team_schedule` | Schedule for a specific team | | `get_game_summary` | Detailed box score and player stats | | `get_rankings` | AP Top 25 and Coaches Poll rankings | | `get_news` | College basketball news | | `get_play_by_play` | Full play-by-play for a game | | `get_win_probability` | Win probability chart data | | `get_schedule` | Schedule for a date or season | | `get_futures` | Futures/odds markets (National Championship, etc.) | | `get_team_stats` | Team statistical profile | | `get_player_stats` | Player statistical profile | | `get_ncaa_scoreboard` | Official NCAA scoreboard — D1, D2, and D3 | | `get_ncaa_schedule` | Which dates have games (official index) | | `get_ncaa_game` | Official NCAA game information | | `get_ncaa_boxscore` | Official NCAA box score | | `get_ncaa_play_by_play` | Official play-by-play | | `get_ncaa_bracket` | March Madness bracket with live scores | | `get_ncaa_schools` | NCAA schools index (all divisions) |

See `references/api-reference.md` for full parameter lists and return shapes.

Official NCAA Backend

The `get_ncaa_*` commands read the NCAA's own endpoints (data.ncaa.com + sdataprod.ncaa.com) — coverage ESPN does not carry:

• **D2 and D3 scoreboards** via `division="d2"`/`"d3"` — ESPN's college

coverage is D1-centric.

• Both scoreboards now return **all of Division I by default** — the

ESPN-backed `get_scoreboard`/`get_schedule` previously inherited ESPN's Top-25-only un-grouped default (1 game on an ordinary Friday instead of ~24). Pass `group` explicitly for a narrower ESPN grouping.

• **The official March Madness bracket** with live scores: `get_ncaa_bracket`.
• **Official game detail**: `get_ncaa_game`, `get_ncaa_boxscore`,

`get_ncaa_play_by_play`.

• **The schools index** (~1,200 schools, all divisions): `get_ncaa_schools`.

NCAA game ids (from `get_ncaa_scoreboard`) and ESPN event ids share nothing — join on game date plus team names. Game-detail and bracket commands ride NCAA's GraphQL persisted queries, whose hashes rotate when ncaa.com redeploys; when that happens those commands say so explicitly while the scoreboard/schedule commands keep working.

Examples

Example 1: Current rankings User says: "What are the college basketball rankings?" Actions: 1. Call `get_rankings()` Result: AP Top 25 and Coaches Poll with rank, previous rank, record, and points

Example 2: Conference standings User says: "Show me SEC basketball standings" Actions: 1. Derive season year from `currentDate` 2. Call `get_standings(group=23, season=<derived_year>)` (group 23 = SEC) Result: SEC standings with W-L records per team

Example 3: Today's scores User says: "What are today's college basketball scores?" Actions: 1. Call `get_scoreboard()` Result: All live and recent CBB games