/learn

name: nutmeg-learn
description: "Explain football analytics concepts and provider documentation: what a metric means (xG, PPDA, xT), learning paths and resources, and provider details such as qualifier IDs, coordinate systems, event types, schemas, ID schemes, coverage, or comparing providers."
argument-hint: "[concept, 'getting started', or provider query]"
allowed-tools: ["Read", "mcp__plugin_nutmeg_football-docs__search_docs", "mcp__football-docs__search_docs", "mcp__plugin_nutmeg_football-docs__list_providers", "mcp__football-docs__list_providers", "mcp__plugin_nutmeg_football-docs__compare_providers", "mcp__football-docs__compare_providers", "mcp__plugin_nutmeg_football-docs__resolve_entity", "mcp__football-docs__resolve_entity", "mcp__plugin_nutmeg_football-docs__get_provider_docs", "mcp__football-docs__get_provider_docs", "mcp__plugin_nutmeg_football-docs__resolve_provider_id", "mcp__football-docs__resolve_provider_id", "mcp__plugin_nutmeg_football-docs__get_metric", "mcp__football-docs__get_metric", "mcp__plugin_nutmeg_football-docs__list_metrics", "mcp__football-docs__list_metrics"]

Learn

Teach football analytics concepts, recommend resources, provide a learning path, and answer questions about data provider documentation — all adapted to the user's level.

Accuracy

Read and follow `${CLAUDE_PLUGIN_ROOT}/docs/accuracy-guardrail.md` before answering any question about provider-specific facts (IDs, endpoints, schemas, coordinates, rate limits). Always use `search_docs` — never guess from training data.

When the user asks what a metric means, read its football-docs metric card with `get_metric` (`list_metrics` shows the cards) and explain that variants exist, naming their IDs; use `search_docs` for metrics without a card.

First: check profile

Read `.nutmeg.user.md`. If it doesn't exist, continue with sensible defaults (Python and pandas, intermediate level) and suggest running `/nutmeg` setup at the end.

Glossary of core concepts

The glossary is in `${CLAUDE_PLUGIN_ROOT}/docs/glossary.md`: chance quality (xG, npxG, xGOT, xA, xT), possession and pressing (PPDA, high press, counterpressure, build-up, possession value), passing, shooting and defensive terms, and per 90. Read it when the user asks what a term means, and explain at their level. The research workspace page links the same entries. For a provider's own definition of a metric or event, use `search_docs`; the glossary gives the general meaning only.

When the user needs to explain a concept to someone else, or keeps coming back to it, offer once to write it up as an explainer page they can edit and share; follow `${CLAUDE_PLUGIN_ROOT}/docs/understanding.md` section 2.

Per-90 normalisation

Always normalise player stats per 90 minutes, not per match:

per_90 = (raw_stat / minutes_played) * 90

Why: a player with 2 goals in 180 minutes (per 90: 1.0) is performing the same as one with 1 goal in 90 minutes. Per-match stats penalise part-time players.

**Minimum sample:** about 900 minutes (10 full matches) is a common rule of thumb for per-90 stats. Noisy stats need far more: a finishing verdict needs several hundred shots.

Learning path

Stage 1: Getting started

1. **Read:** "The Numbers Game" by Chris Anderson and David Sally. Accessible introduction to football analytics. 2. **Watch:** Tifo Football YouTube channel for visual explainers of tactical and analytical concepts. 3. **Do:** Load StatsBomb open data and make a shot map. Just plot the x,y coordinates of shots, colour by goal/no goal. 4. **Understand:** What xG is and isn't. Read StatsBomb's public xG methodology.

Stage 2: Building skills

1. **Read:** "Soccermatics" by David Sumpter. Mathematical modelling applied to football. 2. **Learn:** How to make pass networks and xG timelines. 3. **Practice:** Analyse a full match. Write up what happened and what the data shows. 4. **Explore:** FBref (basic stats) and Understat (xG) for season-level numbers. Compare teams across multiple dimensions. 5. **Tool up:** Learn pandas/polars (Python), tidyverse (R), or D3.js (JavaScript) for data manipulation and visualisation.

Stage 3: Going deeper

1. **Read key papers:**

• Decroos et al. (2019) "Actions Speak Louder than Goals" (VAEP model)
• Fernandez & Bornn (2018) "Wide Open Spaces" (pitch control)
• Karun Singh (2018) "Introducing Expected Threat" (xT)
• Spearman (2018) "Beyond Expected Goals" (pitch control + off-ball)

2. **Build a model:** Train your own xG model. Compare with provider xG. 3. **Tracking data:** If you can access it, explore player positioning data. 4. **Community:** Join football analytics Twitter/X, and watch Opta Forum (formerly OptaPro Forum) or StatsBomb Conference talks (many are free online).

Stage 4: Professional level

1. **Statistical rigour:** Learn about confidence intervals, effect sizes, Bayesian methods. 2. **Causal inference:** Understanding what data can and can't tell you about cause and effect. 3. **Communication:** Presenting findings to non-technical audiences (coaches, scouts, journalists). 4. **Domain expertise:** The best analysts combine data skills with deep football knowledge. Watch matches, understand tactics.

Community resources

| Resource | What it is | |----------|-----------| | StatsBomb open data | Free event data, best starting point | | Friends of Tracking (YouTube) | University-level video lectures on football analytics | | McKay Johns (YouTube) | Python football analytics tutorials | | FBref | Free season stats. Basic stats only since January 2026, when its advanced (Opta) data was removed | | The Athletic | Journalism with analytics focus | | Opta Forum (formerly OptaPro Forum) | Annual analytics conference (talks online) | | StatsBomb Conference | Annual conference with published research | | r/socceranalytics | Reddit community | | Football Analytics Slack | Community workspace |

Common misconceptions

1. **"More possession = better."** P