acquire

Name: acquire
Author: withqwerty

1installs4forks

How to install acquire?

withqwerty/nutmeg/acquire

$npx -y skills add withqwerty/nutmeg --skill acquire

Installs into the current project.

Summary

Fetch, scrape, or download football data from any source. Also handles API key setup and credential management. Use when the user wants to get data from StatsBomb, Opta, FBref, Understat, SportMonks, Wyscout, Kaggle, or any football data source. Also use when they ask about API k

Files · 1

View on GitHub

SKILL.md

1	# Acquire
2
3	Help the user get football data from any source into their local environment. This includes setting up credentials for providers that require them.
4
5	## Accuracy
6
7	Read 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.
8
9	## First: check profile
10
11	Read `.nutmeg.user.md`. If it doesn't exist, tell the user to run `/nutmeg` first. Use their profile to determine preferred language and available providers.
12
13	## Credentials
14
15	If the user needs to set up API keys or asks "what can I access for free?", handle it here.
16
17	Key management rules:
18	- Keys go in `.env` (gitignored), environment variables, or `.nutmeg.credentials.local` (gitignored)
19	- Never commit keys to git. Verify `.gitignore` includes `.env` and `*.local`
20	- Test the key works with a minimal API call
21	- Never print or log API keys
22
23	Provider access reference:
24
25	\| Source \| Access \| Free? \| Env var \|
26	\|--------\|--------\|-------\|---------\|
27	\| StatsBomb open data \| GitHub / statsbombpy \| Yes \| — \|
28	\| FBref \| Web scraping (soccerdata) \| Yes \| — \|
29	\| Understat \| Web scraping (soccerdata) \| Yes \| — \|
30	\| ClubElo \| HTTP API \| Yes \| — \|
31	\| football-data.co.uk \| CSV download \| Yes \| — \|
32	\| Transfermarkt \| Web scraping \| Yes (fragile) \| — \|
33	\| SportMonks \| REST API \| Free tier \| `SPORTMONKS_API_TOKEN` \|
34	\| Football-data.org \| REST API \| Free tier \| `FOOTBALL_DATA_API_KEY` \|
35	\| FPL \| Unofficial API \| Yes \| — \|
36	\| Opta/Perform \| Feed \| No \| `OPTA_FEED_TOKEN` \|
37	\| StatsBomb API \| REST API \| No \| `STATSBOMB_API_KEY`, `STATSBOMB_API_PASSWORD` \|
38	\| Wyscout \| REST API \| No \| `WYSCOUT_API_KEY` \|
39	\| Kaggle \| Download \| Yes \| — \|
40	\| GitHub datasets \| Download \| Yes \| — \|
41
42	## Decision tree
43
44	When the user asks for data, determine the best source:
45
46	### 1. What data do they need?
47
48	\| Need \| Best free source \| Best paid source \|
49	\|------\|-----------------\|-----------------\|
50	\| Match events (pass-by-pass) \| StatsBomb open data \| Opta, StatsBomb API, Wyscout \|
51	\| Season stats (aggregates) \| FBref \| SportMonks \|
52	\| xG / shot data \| Understat, StatsBomb open \| Opta (matchexpectedgoals), StatsBomb API \|
53	\| Tracking data (player positions) \| None free \| Second Spectrum, SkillCorner, Tracab \|
54	\| Historical results \| football-data.co.uk \| SportMonks \|
55	\| Elo ratings \| ClubElo (free API) \| - \|
56	\| Player valuations \| Transfermarkt (scraping) \| - \|
57	\| Cross-provider entity IDs \| Reep Register (free CSV + API) \| - \|
58
59	### 2. Write acquisition code
60
61	Adapt to the user's language preference from `.nutmeg.user.md`.
62
63	Python patterns:
64
65	```python
66	# StatsBomb open data
67	from statsbombpy import sb
68	events = sb.events(match_id=3788741)
69
70	# FBref via soccerdata
71	import soccerdata as sd
72	fbref = sd.FBref('ENG-Premier League', '2024')
73	stats = fbref.read_team_season_stats()
74
75	# Understat via soccerdata
76	understat = sd.Understat('ENG-Premier League', '2024')
77	shots = understat.read_shot_events()
78	```
79
80	R patterns:
81
82	```r
83	# StatsBomb
84	library(StatsBombR)
85	events <- get.matchFree(Matches) %>% allclean()
86
87	# FBref
88	library(worldfootballR)
89	stats <- fb_season_team_stats("ENG", "M", 2024, "standard")
90	```
91
92	JavaScript/TypeScript:
93
94	```typescript
95	// StatsBomb open data (direct from GitHub)
96	const resp = await fetch('https://raw.githubusercontent.com/statsbomb/open-data/master/data/events/{match_id}.json');
97	const events = await resp.json();
98	```
99
100	### 3. Data validation
101
102	After acquiring data, always:
103	- Check row/event counts are sensible (PL match should have ~1500-2000 events)
104	- Verify key fields are present (coordinates, player IDs, timestamps)
105	- Check for missing data (some providers have gaps for certain competitions)
106	- Warn about coordinate system differences if combining sources
107
108	## Entity ID resolution
109
110	When joining data from different providers (e.g. FBref stats with Transfermarkt valuations), use the Reep Register to map entity IDs across providers.
111
112	Use the `resolve_entity` MCP tool (from football-docs) to look up any player, team, or coach:
113
114	```
115	resolve_entity(name: "Cole Palmer") # search by name
116	resolve_entity(provider: "transfermarkt", id: "568177") # resolve provider ID
117	resolve_entity(qid: "Q99760796") # Wikidata QID lookup
118	```
119
120	For entity-resolution tasks that go beyond a one-off lookup, read
121	`docs/entit

People who liked this also viewed

6 picks

Type

acquire

1installs4forks

View on GitHub

How to install acquire?

withqwerty/nutmeg/acquire

$npx -y skills add withqwerty/nutmeg --skill acquire

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Acquire
2
3	Help the user get football data from any source into their local environment. This includes setting up credentials for providers that require them.
4
5	## Accuracy
6
7	Read 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.
8
9	## First: check profile
10
11	Read `.nutmeg.user.md`. If it doesn't exist, tell the user to run `/nutmeg` first. Use their profile to determine preferred language and available providers.
12
13	## Credentials
14
15	If the user needs to set up API keys or asks "what can I access for free?", handle it here.
16
17	Key management rules:
18	- Keys go in `.env` (gitignored), environment variables, or `.nutmeg.credentials.local` (gitignored)
19	- Never commit keys to git. Verify `.gitignore` includes `.env` and `*.local`
20	- Test the key works with a minimal API call
21	- Never print or log API keys
22
23	Provider access reference:
24
25	\| Source \| Access \| Free? \| Env var \|
26	\|--------\|--------\|-------\|---------\|
27	\| StatsBomb open data \| GitHub / statsbombpy \| Yes \| — \|
28	\| FBref \| Web scraping (soccerdata) \| Yes \| — \|
29	\| Understat \| Web scraping (soccerdata) \| Yes \| — \|
30	\| ClubElo \| HTTP API \| Yes \| — \|
31	\| football-data.co.uk \| CSV download \| Yes \| — \|
32	\| Transfermarkt \| Web scraping \| Yes (fragile) \| — \|
33	\| SportMonks \| REST API \| Free tier \| `SPORTMONKS_API_TOKEN` \|
34	\| Football-data.org \| REST API \| Free tier \| `FOOTBALL_DATA_API_KEY` \|
35	\| FPL \| Unofficial API \| Yes \| — \|
36	\| Opta/Perform \| Feed \| No \| `OPTA_FEED_TOKEN` \|
37	\| StatsBomb API \| REST API \| No \| `STATSBOMB_API_KEY`, `STATSBOMB_API_PASSWORD` \|
38	\| Wyscout \| REST API \| No \| `WYSCOUT_API_KEY` \|
39	\| Kaggle \| Download \| Yes \| — \|
40	\| GitHub datasets \| Download \| Yes \| — \|
41
42	## Decision tree
43
44	When the user asks for data, determine the best source:
45
46	### 1. What data do they need?
47
48	\| Need \| Best free source \| Best paid source \|
49	\|------\|-----------------\|-----------------\|
50	\| Match events (pass-by-pass) \| StatsBomb open data \| Opta, StatsBomb API, Wyscout \|
51	\| Season stats (aggregates) \| FBref \| SportMonks \|
52	\| xG / shot data \| Understat, StatsBomb open \| Opta (matchexpectedgoals), StatsBomb API \|
53	\| Tracking data (player positions) \| None free \| Second Spectrum, SkillCorner, Tracab \|
54	\| Historical results \| football-data.co.uk \| SportMonks \|
55	\| Elo ratings \| ClubElo (free API) \| - \|
56	\| Player valuations \| Transfermarkt (scraping) \| - \|
57	\| Cross-provider entity IDs \| Reep Register (free CSV + API) \| - \|
58
59	### 2. Write acquisition code
60
61	Adapt to the user's language preference from `.nutmeg.user.md`.
62
63	Python patterns:
64
65	```python
66	# StatsBomb open data
67	from statsbombpy import sb
68	events = sb.events(match_id=3788741)
69
70	# FBref via soccerdata
71	import soccerdata as sd
72	fbref = sd.FBref('ENG-Premier League', '2024')
73	stats = fbref.read_team_season_stats()
74
75	# Understat via soccerdata
76	understat = sd.Understat('ENG-Premier League', '2024')
77	shots = understat.read_shot_events()
78	```
79
80	R patterns:
81
82	```r
83	# StatsBomb
84	library(StatsBombR)
85	events <- get.matchFree(Matches) %>% allclean()
86
87	# FBref
88	library(worldfootballR)
89	stats <- fb_season_team_stats("ENG", "M", 2024, "standard")
90	```
91
92	JavaScript/TypeScript:
93
94	```typescript
95	// StatsBomb open data (direct from GitHub)
96	const resp = await fetch('https://raw.githubusercontent.com/statsbomb/open-data/master/data/events/{match_id}.json');
97	const events = await resp.json();
98	```
99
100	### 3. Data validation
101
102	After acquiring data, always:
103	- Check row/event counts are sensible (PL match should have ~1500-2000 events)
104	- Verify key fields are present (coordinates, player IDs, timestamps)
105	- Check for missing data (some providers have gaps for certain competitions)
106	- Warn about coordinate system differences if combining sources
107
108	## Entity ID resolution
109
110	When joining data from different providers (e.g. FBref stats with Transfermarkt valuations), use the Reep Register to map entity IDs across providers.
111
112	Use the `resolve_entity` MCP tool (from football-docs) to look up any player, team, or coach:
113
114	```
115	resolve_entity(name: "Cole Palmer") # search by name
116	resolve_entity(provider: "transfermarkt", id: "568177") # resolve provider ID
117	resolve_entity(qid: "Q99760796") # Wikidata QID lookup
118	```
119
120	For entity-resolution tasks that go beyond a one-off lookup, read
121	`docs/entit

People who liked this also viewed

6 picks

Type