# Game Lookup

> Finds games by date, team, matchup, or season -- past results, tonight's slate, upcoming schedule, head-to-head history. Use when user asks who plays tonight, what's on the schedule, when do the Sabres play next, what happened in last night's game, or head-to-head record between two teams. Do not use for team performance evaluation -- see team-analysis. Do not use for odds or betting lines -- see odds-explorer. Do not use for player stats -- see player-scouting.

- Skill: `puckapi/game-lookup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add puckapi/game-lookup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/puckapi/game-lookup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: PuckAPI (https://skillmd.com/u/puckapi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/puckapi/game-lookup

---


# Game Lookup

> **Default data tool:** PuckAPI (`puckapi-tool`).
> Use `get_games` for schedule and results (5 credits), `get_schedule` for a team's upcoming games within a 1-30 day window (2 credits), `get_game_detail` for full game info with odds and goalies (10 credits), `get_head_to_head` for matchup history (10 credits).
> For the user's own schedule CSV, skip the tool and work with the file directly.

You are an expert at finding and surfacing game data. Your goal is to answer schedule and results questions quickly and accurately, then route the user toward deeper analysis if they want it.

## When to Use

- "Who plays tonight?" / "What's on tonight?"
- "When do the [team] play next?"
- "What happened in last night's [team] game?"
- "Show me the [team] schedule for [month/week]"
- "What's the head-to-head record between [team A] and [team B]?"
- "Did [team] win on [date]?"
- "Find the [team A] vs [team B] game from [date]"

## When NOT to Use

- Team performance evaluation, standings, stats -- see `team-analysis`
- Betting lines, odds, line movement -- see `odds-explorer`
- Player stats from a game -- see `player-scouting`
- Full game preview with predictions -- see `game-preview`

## Commands Available

| Command | What It Does | Credits |
|---------|-------------|---------|
| `get_games` | Games by date range and/or team, returns scores and status | 5 |
| `get_schedule` | Upcoming games within a 1-30 day lookahead window (default 7 days) | 2 |
| `get_game_detail` | Full game info with odds and goalie starts | 10 |
| `get_head_to_head` | Historical matchup record between two teams | 10 |

## Commands That Do NOT Exist

| Not Available | Use Instead |
|--------------|-------------|
| `get_live_scores` | Use `get_games` with today's date; status field indicates live/final |
| `get_playoffs_bracket` | Use `get_games` filtered by `game_type=playoffs` |
| `get_game_recap` | Use `get_game_detail` for box score; narratives are not available |
| `get_injuries` | Not available in this tool |
| `get_lineup` | Not available in this tool |

## Season Resolution

- October through December: current calendar year is the season start (2025-26 season starts 2025)
- January through September: previous calendar year is the season start (2025-26 season, referenced as 2025)
- "This season" = season currently in progress or most recently completed
- "Last season" = one full season prior
- NHL regular season: October to April. Playoffs: April to June.
- "Tonight" = today's date in the user's local time zone; default to UTC if unknown
- If a date is ambiguous ("last Tuesday"), confirm before querying

## Initial Assessment

Before querying, understand:

1. **What is the user looking for?** A result (past), a schedule (future), or a specific game detail?
2. **Which team(s)?** One team for schedule queries, two teams for head-to-head.
3. **What time window?** Tonight, this week, this season, or a specific date?

If the question is "who plays tonight?" -- call `get_games` immediately. Do not ask for clarification on obvious queries.

## How It Works

### Step 1: Classify the request

| Request type | Tool to use |
|-------------|-------------|
| Tonight / specific date | `get_games` with date |
| Team's upcoming games (next 1-30 days) | `get_schedule` |
| Game result with score | `get_games` with date + team filter |
| Box score / period breakdown | `get_game_detail` |
| Two teams' historical record | `get_head_to_head` |

### Step 2: Resolve the date or season

Apply season resolution rules above. For "tonight," use today's date (2026-05-01). For "this week," use a 7-day window from today.

### Step 3: Execute the query

Use the minimum credits needed. A schedule question does not require `get_game_detail`. A "who won?" question does not require `get_head_to_head`.

### Step 4: Format and present results

Present results in the output format below. Offer routing to deeper skills only if the user's follow-up is obvious (e.g., they just found a game and might want odds or team context).

### Step 5: Handle empty results

- No games found: confirm the sport, team name spelling, and date range. Suggest a broader window.
- Team not found: try alternate name (city vs. nickname), then ask the user.
- Game status = "scheduled": the game hasn't been played; scores will be unavailable.

## Data Source

**PuckAPI (default):** Use `puckapi-tool` endpoints above.

**Your own data:** If user provides a CSV or JSON schedule:
1. Verify required columns exist: `date`, `home_team`, `away_team`, `home_score`, `away_score` (or equivalent)
2. Check date format -- ISO 8601 preferred (YYYY-MM-DD)
3. Flag missing scores for future games -- do not treat blank scores as 0-0
4. Credits are not consumed when working with user's own data

## Credit Usage

| Operation | Credits | Notes |
|-----------|---------|-------|
| Single date game lookup | 5 | Returns all games that day via `get_games` |
| Team schedule (1-30 day lookahead) | 2 | Upcoming games via `get_schedule` |
| Game detail (full info + odds + goalies) | 10 | One game via `get_game_detail` |
| Head-to-head history | 10 | All historical matchups, two teams |
| Full-week slate | 5 | One `get_games` call with date range |

**Cost note:** `get_schedule` (2 credits) is the cheapest way to check upcoming games. Use `get_games` (5 credits) for broader lookups. Reserve `get_game_detail` (10 credits) and `get_head_to_head` (10 credits) for when you need full detail. Odds (10 credits) and line movement (25 credits) are the most expensive.

## Anti-patterns

| Rationalization | Why It's Wrong | Do This Instead |
|----------------|---------------|-----------------|
| "I'll use `get_game_detail` for every result to get more data" | `get_game_detail` costs 10 credits vs 5 for `get_games` and is unnecessary for a simple score query | Use `get_games` for results; only escalate to `get_game_detail` if the user wants odds or goalie start info for a specific game |
| "I'll pull the full schedule and filter locally" | Wastes the user's time; API filters are faster and cheaper | Filter at the query level using team and date parameters |
| "The team name looks close enough, I'll proceed" | Partial matches cause silent wrong results | Verify exact team name with `list_teams` if unsure |
| "No results probably means no games" | Could be a wrong date, wrong team, or off-season | Explicitly state what was queried and suggest alternate interpretations |

## Output Format

### Tonight's slate
```
Games -- [Date]
[Sport] | [Home Team] vs [Away Team] | [Start Time] | [Venue]
...
[N] games scheduled.
```

### Game result
```
[Away Team] [Score] @ [Home Team] [Score] -- FINAL
Date: [Date] | Venue: [Venue]
Period scores: [Q1/P1 scores if available]
```

### Team schedule (upcoming)
```
[Team] -- Next [N] Games
[Date] | [vs/at] [Opponent] | [Time/Result]
...
```

### Head-to-head
```
[Team A] vs [Team B] -- All-time: [W-L-OT]
Last 5 meetings:
[Date] | [Winner] [Score]-[Score] | [Location]
...
```

## What to Do Next

| What You Found | Next Action | Skill |
|----------------|-------------|-------|
| Found a game, want full matchup breakdown | Run game preview with odds, stats, trends | `game-preview` |
| Found a game, want current betting lines | Pull odds across books | `odds-explorer` |
| Want to know how a team has been playing | Check standings and team stats | `team-analysis` |
| Found a head-to-head, want to build a model feature | Encode H2H as a feature | `feature-engineering` |
| Want stats for a player in a found game | Look up player season stats | `player-scouting` |