cfb-data

College Football Data (CFB)

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 cfb get_scoreboard
sports-skills cfb get_rankings
sports-skills cfb get_standings --group=8

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 CFB season runs August–January. If the current month is February–July (offseason), use season = current_year - 1. From August onward, use the current year.

Important: College vs. Pro Differences

• Standings are per-conference — use the group parameter to filter
• Rankings replace leaders — college uses AP Top 25, Coaches Poll, and CFP rankings
• Ranked teams have a rank field (null = unranked) on scoreboard competitors
• Week-based schedule — like NFL, college football uses week numbers

Commands

Command	Description
get_scoreboard	Live/recent college football scores
get_standings	Standings by conference (use group parameter)
get_teams	All 750+ FBS college football teams
get_team_roster	Full roster for a team
get_team_schedule	Schedule for a specific team
get_game_summary	Detailed box score and scoring plays
get_rankings	AP Top 25, Coaches Poll, CFP rankings
get_news	College football news
get_play_by_play	Full play-by-play for a game
get_win_probability	Win probability timeline for a completed game
get_schedule	Season schedule by week
get_injuries	Injury reports across all teams
get_futures	Futures/odds markets (National Championship, Heisman, etc.)
get_team_stats	Team statistical profile
get_player_stats	Player statistical profile
get_ncaa_scoreboard	Official NCAA scoreboard — FBS and FCS
get_ncaa_schedule	Which weeks 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 with drive context
get_ncaa_scoring_summary	Official scoring summary
get_ncaa_schools	NCAA schools index (all divisions)