{"id":"852d8444-e026-4ac4-bb84-371fd0ae7d5a","shortId":"RKvzte","kind":"skill","title":"nutmeg-learn","tagline":"Learn about football analytics concepts and explore provider documentation. Use when the user asks what a metric means (xG, PPDA, expected threat, xT), wants learning resources, papers, or courses, is new to football analytics, or wants a learning path. Also use when the user ask","description":"# Learn\n\nTeach football analytics concepts, recommend resources, provide a learning path, and answer questions about data provider documentation — all adapted to the user's level.\n\n## Accuracy\n\nRead and follow `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.\n\n## First: check profile\n\nRead `.nutmeg.user.md`. If it doesn't exist, tell the user to run `/nutmeg` first.\n\n## Glossary of core concepts\n\n### Chance quality metrics\n\n| Metric | What it means | Intuition |\n|--------|--------------|-----------|\n| xG (Expected Goals) | Probability a shot results in a goal (0-1) | \"How good was the chance?\" |\n| xGOT (xG on Target) | xG adjusted for shot placement in the goal | \"How good was the finish?\" |\n| xA (Expected Assists) | xG of the shot that resulted from a pass | \"How good was the chance created?\" |\n| xT (Expected Threat) | Value added by moving the ball to a more dangerous area | \"How much did this pass/carry increase goal threat?\" |\n| PSxG (Post-Shot xG) | Same as xGOT. StatsBomb terminology. |\n\n### Possession and pressing\n\n| Metric | What it means |\n|--------|--------------|\n| PPDA | Passes allowed per defensive action. Lower = more pressing |\n| High press | Defensive actions in the opponent's defensive third |\n| Counterpressure | Immediate defensive reaction after losing the ball |\n| Build-up | How a team progresses the ball from defence to attack |\n| Possession value | How much each action contributes to scoring probability |\n\n### Passing\n\n| Metric | What it means |\n|--------|--------------|\n| Progressive pass | Pass that moves the ball significantly toward the opponent's goal |\n| Key pass | Pass directly leading to a shot |\n| Assist | Pass directly leading to a goal |\n| Through ball | Pass played into space behind the defence |\n| Switch of play | Long pass crossing the centre of the pitch |\n| Pass completion % | Successful passes / total passes (misleading in isolation) |\n\n### Shooting\n\n| Metric | What it means |\n|--------|--------------|\n| Shots per 90 | Shot volume normalised by playing time |\n| Conversion rate | Goals / shots (noisy, small sample issues) |\n| Big chance | High-xG opportunity (typically xG > 0.3) |\n| Shot on target % | Shots on target / total shots |\n\n### Defensive\n\n| Metric | What it means |\n|--------|--------------|\n| Tackles won | Successful tackle attempts |\n| Interceptions | Reading and intercepting opponent passes |\n| Clearances | Defensive clearances (often under pressure) |\n| Blocks | Blocking shots or passes |\n| Aerial duels won | Headers contested and won |\n\n### Per-90 normalisation\n\nAlways normalise player stats per 90 minutes, not per match:\n```\nper_90 = (raw_stat / minutes_played) * 90\n```\n\nWhy: 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.\n\n**Minimum sample:** ~900 minutes (10 full matches) before per-90 stats are meaningful.\n\n## Learning path\n\n### Stage 1: Getting started\n\n1. **Read:** \"The Numbers Game\" by Chris Anderson and David Sally. Accessible introduction to football analytics.\n2. **Watch:** Tifo Football YouTube channel for visual explainers of tactical and analytical concepts.\n3. **Do:** Load StatsBomb open data and make a shot map. Just plot the x,y coordinates of shots, colour by goal/no goal.\n4. **Understand:** What xG is and isn't. Read StatsBomb's public xG methodology.\n\n### Stage 2: Building skills\n\n1. **Read:** \"Soccermatics\" by David Sumpter. Mathematical modelling applied to football.\n2. **Learn:** How to make pass networks and xG timelines.\n3. **Practice:** Analyse a full match. Write up what happened and what the data shows.\n4. **Explore:** FBref for season-level stats. Compare teams across multiple dimensions.\n5. **Tool up:** Learn pandas/polars (Python), tidyverse (R), or D3.js (JavaScript) for data manipulation and visualisation.\n\n### Stage 3: Going deeper\n\n1. **Read key papers:**\n   - Decroos et al. (2019) \"Actions Speak Louder than Goals\" (VAEP model)\n   - Fernandez & Bornn (2018) \"Wide Open Spaces\" (pitch control)\n   - Karun Singh (2018) \"Introducing Expected Threat\" (xT)\n   - Spearman (2018) \"Beyond Expected Goals\" (pitch control + off-ball)\n2. **Build a model:** Train your own xG model. Compare with provider xG.\n3. **Tracking data:** If you can access it, explore player positioning data.\n4. **Community:** Join football analytics Twitter/X, attend OptaPro Forum or StatsBomb Conference talks (many are free online).\n\n### Stage 4: Professional level\n\n1. **Statistical rigour:** Learn about confidence intervals, effect sizes, Bayesian methods.\n2. **Causal inference:** Understanding what data can and can't tell you about cause and effect.\n3. **Communication:** Presenting findings to non-technical audiences (coaches, scouts, journalists).\n4. **Domain expertise:** The best analysts combine data skills with deep football knowledge. Watch matches, understand tactics.\n\n## Community resources\n\n| Resource | What it is |\n|----------|-----------|\n| StatsBomb open data | Free event data, best starting point |\n| Friends of Tracking (YouTube) | University-level video lectures on football analytics |\n| McKay Johns (YouTube) | Python football analytics tutorials |\n| FBref | Free season stats, powered by StatsBomb data |\n| The Athletic | Journalism with analytics focus |\n| OptaPro Forum | Annual analytics conference (talks online) |\n| StatsBomb Conference | Annual conference with published research |\n| r/socceranalytics | Reddit community |\n| Football Analytics Slack | Community workspace |\n\n## Common misconceptions\n\n1. **\"More possession = better.\"** Possession without purpose is meaningless. Quality of chances matters more.\n2. **\"xG is a prediction.\"** xG is a description of chance quality, not a prediction of future performance.\n3. **\"This player has 0.8 xG per 90, so they'll score 30 goals.\"** Small samples, regression to the mean, context all matter.\n4. **\"Data analytics replaces scouting.\"** It complements it. Data finds candidates; humans evaluate fit, personality, potential.\n5. **\"All xG models are the same.\"** They vary significantly by input features, training data, and methodology.\n\n## Provider documentation\n\nWhen the user asks about provider-specific details — event types, qualifier IDs, coordinate systems, API schemas, field mappings — use the football-docs MCP tools.\n\n### Answering specific questions\n\nUse `search_docs` with the user's query. Add a `provider` filter if they're asking about a specific provider.\n\nExamples:\n- \"What qualifier ID is a headed goal in Opta?\" → `search_docs(query=\"headed goal qualifier\", provider=\"opta\")`\n- \"How does StatsBomb represent xG?\" → `search_docs(query=\"xG expected goals\", provider=\"statsbomb\")`\n- \"What free data sources have shot-level data?\" → `search_docs(query=\"shot data free\", provider=\"free-sources\")`\n\n### Comparing providers\n\nUse `compare_providers` when the user wants to understand differences.\n\nExamples:\n- \"How do Opta and StatsBomb represent passes differently?\" → `compare_providers(topic=\"pass event types\", providers=[\"opta\", \"statsbomb\"])`\n- \"Which providers have xG data?\" → `compare_providers(topic=\"xG expected goals\")`\n\n### Discovering what's available\n\nUse `list_providers` to show what documentation is indexed and its coverage.\n\n### Cross-referencing with kloppy\n\nWhen comparing providers, also search for kloppy's mapping documentation. kloppy defines how each provider's events map to a canonical model, which helps the user understand what maps cleanly between providers, what information is lost in translation, and what becomes a GenericEvent (unmapped).\n\n### Response format\n\n1. Give the direct answer first (the qualifier ID, the field name, etc.)\n2. Add context about how it works in practice\n3. If relevant, mention how other providers handle the same concept\n4. Adapt technical depth to the user's experience level","tags":["learn","nutmeg","withqwerty","agent-skills","claude-code","claude-code-plugin","football-analytics","football-data","mcp","opta","sports-analytics","statsbomb"],"capabilities":["skill","source-withqwerty","skill-learn","topic-agent-skills","topic-claude-code","topic-claude-code-plugin","topic-football-analytics","topic-football-data","topic-mcp","topic-opta","topic-sports-analytics","topic-statsbomb"],"categories":["nutmeg"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/withqwerty/nutmeg/learn","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add withqwerty/nutmeg","source_repo":"https://github.com/withqwerty/nutmeg","install_from":"skills.sh"}},"qualityScore":"0.458","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 17 github stars · SKILL.md body (8,020 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T01:02:06.455Z","embedding":null,"createdAt":"2026-04-18T23:06:51.571Z","updatedAt":"2026-04-23T01:02:06.455Z","lastSeenAt":"2026-04-23T01:02:06.455Z","tsv":"'-1':143 '-90':409,470 '/nutmeg':118 '0':142 '0.3':365 '0.8':870 '1':447,477,480,551,620,706,834,1131 '1.0':439 '10':465 '180':435 '2':432,496,548,562,660,717,848,1144 '2018':637,645,651 '2019':627 '3':510,572,617,673,733,866,1153 '30':878 '4':533,587,685,703,745,889,1164 '5':600,905 '90':342,416,422,427,438,450,873 '900':463 'access':491,679 'accuraci':74 'across':597 'action':228,235,268,628 'ad':188 'adapt':68,1165 'add':961,1145 'adjust':154 'aerial':401 'al':626 'allow':225 'also':43,1088 'alway':94,411 'analys':574 'analyst':750 'analyt':7,37,52,495,508,689,788,794,808,813,828,891 'anderson':487 'annual':812,819 'answer':61,80,950,1135 'api':939 'appli':559 'area':197 'ask':17,48,927,968 'assist':168,299 'athlet':805 'attack':262 'attempt':383 'attend':691 'audienc':741 'avail':1067 'ball':192,249,258,284,307,659 'bayesian':715 'becom':1125 'behind':312 'best':749,774 'better':837 'beyond':652 'big':357 'block':396,397 'bornn':636 'build':251,549,661 'build-up':250 'candid':899 'canon':1105 'caus':730 'causal':718 'centr':322 'chanc':124,148,182,358,845,858 'channel':501 'check':104 'chris':486 'clean':1114 'clearanc':390,392 'coach':742 'colour':529 'combin':751 'common':832 'communic':734 'communiti':686,762,826,830 'compar':595,669,1023,1026,1044,1058,1086 'complement':895 'complet':327 'concept':8,53,123,509,1163 'confer':696,814,818,820 'confid':711 'contest':405 'context':886,1146 'contribut':269 'control':642,656 'convers':349 'coordin':91,526,937 'core':122 'counterpressur':242 'cours':32 'coverag':1079 'creat':183 'cross':320,1081 'cross-referenc':1080 'd3.js':609 'danger':196 'data':64,102,515,585,612,675,684,722,752,770,773,803,890,897,919,1006,1012,1017,1057 'david':489,555 'decroo':624 'deep':755 'deeper':619 'defenc':260,314 'defens':227,234,240,244,374,391 'defin':1096 'depth':1167 'descript':856 'detail':932 'differ':1034,1043 'dimens':599 'direct':294,301,1134 'discov':1064 'doc':97,947,955,984,997,1014 'docs/accuracy-guardrail.md':78 'document':12,66,923,1074,1094 'doesn':110 'domain':746 'duel':402 'effect':713,732 'endpoint':89 'et':625 'etc':1143 'evalu':901 'event':772,933,1048,1101 'exampl':973,1035 'exist':112 'expect':24,133,167,185,647,653,1000,1062 'experi':1172 'expertis':747 'explain':504 'explor':10,588,681 'fact':87 'fbref':589,796 'featur':917 'fernandez':635 'field':941,1141 'filter':964 'find':736,898 'finish':165 'first':103,119,1136 'fit':902 'focus':809 'follow':77 'footbal':6,36,51,494,499,561,688,756,787,793,827,946 'football-doc':945 'format':1130 'forum':693,811 'free':700,771,797,1005,1018,1021 'free-sourc':1020 'friend':777 'full':466,576 'futur':864 'game':484 'genericev':1127 'get':478 'give':1132 'glossari':120 'go':618 'goal':134,141,160,204,290,305,351,433,448,532,632,654,879,980,987,1001,1063 'goal/no':531 'good':145,162,179 'guess':99 'handl':1160 'happen':581 'head':979,986 'header':404 'help':1108 'high':232,360 'high-xg':359 'human':900 'id':88,936,976,1139 'immedi':243 'increas':203 'index':1076 'infer':719 'inform':1118 'input':916 'intercept':384,387 'interv':712 'introduc':646 'introduct':492 'intuit':131 'isn':539 'isol':334 'issu':356 'javascript':610 'john':790 'join':687 'journal':806 'journalist':744 'karun':643 'key':291,622 'kloppi':1084,1091,1095 'knowledg':757 'lead':295,302 'learn':3,4,28,41,49,58,474,563,603,709 'lectur':785 'level':73,593,705,783,1011,1173 'limit':93 'list':1069 'll':876 'load':512 'long':318 'lose':247 'lost':1120 'louder':630 'lower':229 'make':517,566 'mani':698 'manipul':613 'map':520,942,1093,1102,1113 'match':420,454,467,577,759 'mathemat':557 'matter':846,888 'mckay':789 'mcp':948 'mean':21,130,222,277,339,378,885 'meaning':473 'meaningless':842 'mention':1156 'method':716 'methodolog':546,921 'metric':20,126,127,219,274,336,375 'minimum':461 'minut':417,425,436,451,464 'misconcept':833 'mislead':332 'model':558,634,663,668,908,1106 'move':190,282 'much':199,266 'multipl':598 'name':1142 'network':568 'never':98 'new':34 'noisi':353 'non':739 'non-techn':738 'normalis':345,410,412 'number':483 'nutmeg':2 'nutmeg-learn':1 'nutmeg.user.md':107 'off-bal':657 'often':393 'one':445 'onlin':701,816 'open':514,639,769 'oppon':238,288,388 'opportun':362 'opta':982,990,1038,1051 'optapro':692,810 'pandas/polars':604 'paper':30,623 'part':458 'part-tim':457 'pass':177,224,273,279,280,292,293,300,308,319,326,329,331,389,400,567,1042,1047 'pass/carry':202 'path':42,59,475 'penalis':456 'per':226,341,408,415,419,421,437,453,469,872 'per-match':452 'perform':441,865 'person':903 'pitch':325,641,655 'placement':157 'play':309,317,347,426 'player':413,430,460,682,868 'plot':522 'point':776 'posit':683 'possess':216,263,836,838 'post':208 'post-shot':207 'potenti':904 'power':800 'ppda':23,223 'practic':573,1152 'predict':852,862 'present':735 'press':218,231,233 'pressur':395 'probabl':135,272 'profession':704 'profil':105 'progress':256,278 'provid':11,56,65,85,671,922,930,963,972,989,1002,1019,1024,1027,1045,1050,1054,1059,1070,1087,1099,1116,1159 'provider-specif':84,929 'psxg':206 'public':544 'publish':822 'purpos':840 'python':605,792 'qualifi':935,975,988,1138 'qualiti':125,843,859 'queri':960,985,998,1015 'question':62,82,952 'r':607 'r/socceranalytics':824 'rate':92,350 'raw':423 're':967 'reaction':245 'read':75,106,385,481,541,552,621 'recommend':54 'reddit':825 'referenc':1082 'regress':882 'relev':1155 'replac':892 'repres':994,1041 'research':823 'resourc':29,55,763,764 'respons':1129 'result':138,174 'rigour':708 'run':117 'salli':490 'sampl':355,462,881 'schema':90,940 'score':271,877 'scout':743,893 'search':96,954,983,996,1013,1089 'season':592,798 'season-level':591 'shoot':335 'shot':137,156,172,209,298,340,343,352,366,369,373,398,519,528,1010,1016 'shot-level':1009 'show':586,1072 'signific':285,914 'singh':644 'size':714 'skill':550,753 'skill-learn' 'slack':829 'small':354,880 'soccermat':553 'sourc':1007,1022 'source-withqwerty' 'space':311,640 'speak':629 'spearman':650 'specif':86,931,951,971 'stage':476,547,616,702 'start':479,775 'stat':414,424,455,471,594,799 'statist':707 'statsbomb':214,513,542,695,768,802,817,993,1003,1040,1052 'success':328,381 'sumpter':556 'switch':315 'system':938 'tackl':379,382 'tactic':506,761 'talk':697,815 'target':152,368,371 'teach':50 'team':255,596 'technic':740,1166 'tell':113,727 'terminolog':215 'third':241 'threat':25,186,205,648 'tidyvers':606 'tifo':498 'time':348,459 'timelin':571 'tool':601,949 'topic':1046,1060 'topic-agent-skills' 'topic-claude-code' 'topic-claude-code-plugin' 'topic-football-analytics' 'topic-football-data' 'topic-mcp' 'topic-opta' 'topic-sports-analytics' 'topic-statsbomb' 'total':330,372 'toward':286 'track':674,779 'train':101,664,918 'translat':1122 'tutori':795 'twitter/x':690 'type':934,1049 'typic':363 'understand':534,720,760,1033,1111 'univers':782 'university-level':781 'unmap':1128 'use':13,44,95,943,953,1025,1068 'user':16,47,71,115,926,958,1030,1110,1170 'vaep':633 'valu':187,264 'vari':913 'video':784 'visual':503 'visualis':615 'volum':344 'want':27,39,1031 'watch':497,758 'wide':638 'without':839 'won':380,403,407 'work':1150 'workspac':831 'write':578 'x':524 'xa':166 'xg':22,132,150,153,169,210,361,364,536,545,570,667,672,849,853,871,907,995,999,1056,1061 'xgot':149,213 'xt':26,184,649 'y':525 'youtub':500,780,791","prices":[{"id":"4d385ecc-2f40-4415-98c8-a96cf5b31e91","listingId":"852d8444-e026-4ac4-bb84-371fd0ae7d5a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"withqwerty","category":"nutmeg","install_from":"skills.sh"},"createdAt":"2026-04-18T23:06:51.571Z"}],"sources":[{"listingId":"852d8444-e026-4ac4-bb84-371fd0ae7d5a","source":"github","sourceId":"withqwerty/nutmeg/learn","sourceUrl":"https://github.com/withqwerty/nutmeg/tree/main/skills/learn","isPrimary":false,"firstSeenAt":"2026-04-18T23:06:51.571Z","lastSeenAt":"2026-04-23T01:02:06.455Z"}],"details":{"listingId":"852d8444-e026-4ac4-bb84-371fd0ae7d5a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"withqwerty","slug":"learn","github":{"repo":"withqwerty/nutmeg","stars":17,"topics":["agent-skills","claude-code","claude-code-plugin","football-analytics","football-data","mcp","opta","sports-analytics","statsbomb","xg"],"license":null,"html_url":"https://github.com/withqwerty/nutmeg","pushed_at":"2026-04-16T02:33:15Z","description":"Football data analytics toolkit for Claude Code. Covers Opta, StatsBomb, Wyscout, SportMonks, and free sources.","skill_md_sha":"dd0e12ac6a213f3cf054131f956349ea29cffa8d","skill_md_path":"skills/learn/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/withqwerty/nutmeg/tree/main/skills/learn"},"layout":"multi","source":"github","category":"nutmeg","frontmatter":{"name":"nutmeg-learn","description":"Learn about football analytics concepts and explore provider documentation. Use when the user asks what a metric means (xG, PPDA, expected threat, xT), wants learning resources, papers, or courses, is new to football analytics, or wants a learning path. Also use when the user asks about data provider documentation — qualifier IDs, coordinate systems, event types, API schemas, field mappings — or wants to compare providers, look something up in the docs, or find out what data a provider offers."},"skills_sh_url":"https://skills.sh/withqwerty/nutmeg/learn"},"updatedAt":"2026-04-23T01:02:06.455Z"}}