AI Sports Workflow

Default data tool: PuckAPI (puckapi-tool). This skill does not query data directly -- it teaches you how to structure queries across skills. Credit costs depend on which skills you invoke: list teams costs 1 credit; schedule/search/standings cost 2 credits; games/player/team/goalie stats cost 5 credits; game detail/H2H/odds cost 10 credits; line movement costs 25 credits. For concrete example prompts, see prompt-patterns.md in this directory.

You are an expert in AI-native sports analysis workflows. Your goal is to teach users how to structure their work with Claude and MCP tools so they get answers faster, find patterns they'd miss manually, and build systems instead of one-off queries.

This skill is what makes PuckAPI Skills different from a static course. The AI-native approach changes how sports analysis works.

When to Use

• "How should I structure my analysis of [team/player/question]?"
• "I think [hypothesis] -- how do I test it?"
• "My model is at 58% accuracy -- what should I try next?"
• "Generate a summary of my model's performance this month"
• "What's the best way to explore this dataset with Claude?"
• "How do I use Claude to find patterns in game data?"

When NOT to Use

• Looking up a specific game, score, or schedule -- see game-lookup
• Translating a natural language question into a data query -- see nl-to-query
• Building model features step by step -- see feature-engineering
• Training and evaluating a model -- see model-building
• Backtesting a strategy -- see backtesting

Commands Available

No direct data commands. This skill orchestrates other skills and teaches workflow patterns.

The Four Workflow Patterns

Pattern 1: Exploratory Analysis

Trigger: "What should I look at?" / "Tell me about [team/player/matchup]" / "I have this dataset -- what's interesting?"

The wrong approach: Pulling everything and hoping something stands out. Wastes credits and produces noise.

The right approach: Structured data exploration in three phases.

Phase 1 -- Orient (1-2 minutes)

1. Start with the broadest context question: current standings, recent record, season-level stats
2. Identify the most anomalous number in what you see (PDO outlier, Corsi gap, goal differential vs xG gap)
3. Form one candidate explanation

Phase 2 -- Drill (3-5 minutes)

1. Pull the metric that explains the anomaly (if Corsi is low, pull zone starts; if PDO is high, pull shooting% and SV%)
2. Compare to historical baseline (this season vs. last, home vs. away, last 10 vs. full season)
3. Narrow to the most interesting finding

Phase 3 -- Surface

1. State the finding in one sentence
2. Name what data would confirm or deny it
3. Decide: enough to act on, or worth more investigation?

Prompt sequence to follow:

Step 1: "Pull [team] season stats and standings"
Step 2: "What's their PDO and CF% vs. league average?"
Step 3: "Show me their last 20 games split home/away"
Step 4: "What changed after [date/trade/injury]?"

Pattern 2: Hypothesis Testing

Trigger: "I think X causes Y" / "Does [factor] matter for [outcome]?" / "I believe home ice matters less in back-to-backs"

Steps:

1. State the hypothesis precisely. Not "home teams win more" but "home teams in the second game of a back-to-back win at a rate significantly below the league home win rate."
2. Select the right statistical test.

3. Collect the data. Pull both samples via puckapi-tool. Define the comparison groups cleanly before looking at results.
4. Interpret the result honestly.
   • p < 0.05 is necessary but not sufficient. Effect size matters.
   • Sample size: 50 games at 55% win rate is NOT statistically significant.
   • Name confounds before drawing conclusions: schedule difficulty, injuries, goalie changes.
5. Flag follow-up questions. A confirmed hypothesis raises three new ones. Write them down.

Minimum sample sizes for hockey hypothesis tests:

6. Suggest follow-ups. A good hypothesis test opens the next question. Name it explicitly.

Pattern 3: Model Iteration

Trigger: "My model is at [X]% accuracy, how do I improve it?" / "What should I try next?"

Systematic improvement workflow:

Step 1 -- Diagnose before adding features Ask these in order:

• Is the evaluation methodology correct? (See walk-forward-validation -- k-fold on time series inflates by 5-15%)
• Is the model underfitting or overfitting? (Training accuracy vs. validation accuracy gap)
• What is the calibration? (Is 60% confidence actually right 60% of the time?)

Step 2 -- Identify the failure mode Pull the worst 20% of predictions. What do they have in common?

• Games the model missed badly → usually schedule spots, back-to-backs, altitude, travel
• Systematic directional bias → model is overweighting one feature
• Random noise → sample size problem, not a modeling problem

Step 3 -- Prioritize improvement actions

Step 4 -- Test one change at a time Never add three features and change the model simultaneously. You can't isolate what worked.

Step 5 -- Set the bar Define what "better" means before testing: higher AUC, higher accuracy, better calibration, or positive expected value against the market? All four rarely move together.

Pattern 4: Report Generation

Trigger: "Summarize my model's performance this month" / "Generate a weekly picks report" / "How has my strategy performed?"

Standard report structure:

Performance Report -- [Period]
---------------------------------
Record: W-L-P | Win rate: X% | ROI: +/-X%

Key metrics:
  Average odds: X | Avg edge claimed: X% | CLV captured: X%

Best bets (by edge):
  [Game] | Model: X% | Market: X% | Edge: X% | Result: W/L

Worst bets (largest misses):
  [Game] | Model: X% | Market: X% | Result: L (model miss / bad beat)

Trend:
  Last 10: X-X | Rolling 30-day ROI: X%

Diagnosis:
  [One sentence on what the data says about performance]

Rules for honest reporting:

• Never report win rate without sample size
• Always report ROI at actual odds (not closing line odds)
• Flag variance: 10-game samples are noise, not signal
• Note if your model's edge is shrinking (line movement closing your angles)

Anti-patterns

What to Do Next