git:20261001.7be117a to git:20261009.a775151

# nutmeg

A Claude Code plugin for football data analytics. 11 skills (3 entry points + 8 sub-skills), 3 agents, powered by the football-docs MCP server.

## Architecture: progressive disclosure

Users interact through **three entry points**. Sub-skills are dispatched automatically or invoked directly by power users.

| Layer | Skills | How invoked |

|-------|--------|-------------|

| **Entry** | `/nutmeg` (router) | User describes any football analytics task — routes automatically |

| **Teaching** | `/nutmeg:learn` | Concepts, resources, provider docs, learning paths |

| **Research** | `/nutmeg:research` | Analysis to publish or decide on: question card, plan with reasons, claim ledger |

| **Sub-skills** | `acquire`, `wrangle`, `compute`, `analyse`, `brainstorm`, `store`, `review`, `heal` | Auto-dispatched by router, or directly by power users |

## Structure

```

skills/

nutmeg/ # Router — single entry point, handles init + dispatch

learn/ # Teaching + provider documentation (merged from old providers/)

research/ # Research projects: question, plan with reasons, claim ledger

acquire/ # Fetch data + credential management (merged from old credentials/)

analyse/ # Explore and interpret data

brainstorm/ # Visualisation ideation with research + style options

references/ # chart-canon.md (conventions), viz-styles.md (4 aesthetic styles)

compute/ # Derived metrics (xG, PPDA, xT, etc.)

heal/ # Fix broken scrapers

review/ # Dispatch data-reviewer + chart-reviewer agents

store/ # Storage format and publishing

wrangle/ # Transform, filter, reshape data

core/ # nutmeg command (stdlib Python >= 3.10): ledger, projects, redaction

nutmeg.py # Entry point: python3 "${CLAUDE_PLUGIN_ROOT}/core/nutmeg.py" <command>

nutmeg_core/ # Package; tests in core/tests (python3 -m pytest core/tests)

agents/ # Specialised sub-agents

data-reviewer.md # Reviews data code (coordinates, xG, filtering, sample sizes)

chart-reviewer.md # Reviews chart code (3 modes: code, visual, interactive)

pipeline-builder.md # Designs end-to-end data pipelines

docs/

accuracy-guardrail.md # Shared guardrail: always use search_docs, never guess from training

metric-misuse.md # Stat-misuse checks (Worville's ten commandments), used by analyse

entity-resolution-routing.md # Reep lookup, joins and routing

hooks/ # SessionStart hook: injects the core football-data and research-project rules every session

evals/ # claude plugin eval suite + football-docs replay mock (see README "Evals")

.mcp.json # Declares football-docs MCP server dependency

```

## Key conventions

- Every provider-touching skill includes the accuracy guardrail section

- Skills and agents reference plugin files as `${CLAUDE_PLUGIN_ROOT}/...` (a bare `docs/...` path resolves against the user's project, not the plugin)

- Plugin MCP tools are named `mcp__plugin_nutmeg_football-docs__<tool>`; frontmatter tool lists carry that name and the standalone `mcp__football-docs__<tool>`

- Skills and agents do not hard-code provider facts; they look them up with `search_docs` and name the source

- Run the eval suite before a release and compare with the previous version

- Skills use `search_docs` from the football-docs MCP server for all provider-specific facts

- Entity-resolution tasks route through `docs/entity-resolution-routing.md`:

provider facts in `football-docs`, public ID lookup through Reep Register,

reusable matching guidance in `reep-toolkit`, and private matching logic pack

material only when the user has access

- User profile lives at `.nutmeg.user.md` (created by `/nutmeg` on first run)

- Skills adapt to user's language (Python/R/JS), experience level, and available data sources

- Reference docs in skills/brainstorm/references/ are loaded on-demand, not all upfront

- The router mentions sub-skill names during dispatch so users learn the vocabulary naturally

## Related projects

**football-docs** (npm: `football-docs`, repo: `withqwerty/football-docs`)

- MCP server providing searchable documentation for football data providers

and identity surfaces

- Connected via `.mcp.json` — starts automatically when the plugin loads

- Skills query it via `mcp__football-docs__search_docs`, `list_providers`, `compare_providers`

**nutmeg-site** (local: `../nutmeg-site`)

- Marketing/landing page for the plugin, built with Astro 6 (static output)

- Components: Hero, SkillsGrid, ProvidersGrid, ExampleQueries, InstallRow, etc.

**plugins** (repo: `withqwerty/plugins`, local: `../plugins`)

- Plugin marketplace listing — nutmeg is registered here for discovery via `/plugin marketplace`