FPL Copilot

Fantasy Premier League data sync, analysis, and squad management.

FPL data: SQLite database at
```
~/.fplcopilot/fplcopilot.db
```
User squads: Markdown files in
```
~/.fplcopilot/squads/
```

When to Use

Activate this skill when the user mentions:

FPL, Fantasy Premier League, fantasy football (UK context)
Player stats, form, price, points, xG, xA, ICT, ownership
Transfer advice, who to buy/sell, budget options
Captain pick, vice-captain, chip timing
Fixture difficulty, FDR, schedule, easy/hard fixtures
Gameweek deadline, scores, standings, averages
Squad management, team composition, formation
Team analysis: momentum, xG differential, leaky defences, hot attacks
Rotation pairs, differential picks, value picks

Quick Start

1. Check Data Freshness

bash

sqlite3 ~/.fplcopilot/fplcopilot.db "SELECT * FROM sync_metadata;"

If the database doesn't exist or data is stale, sync first.

2. Sync Data

bash

SYNC="${CLAUDE_PLUGIN_ROOT}/skills/fpl-copilot/references/sync.sh"

# First time or daily refresh
$SYNC bootstrap              # Teams, gameweeks, ~600 players (~5s)
$SYNC fixtures               # All 380 fixtures (~2s)

# On demand — single player's match history
$SYNC player 328             # e.g., Salah's detailed GW-by-GW stats

# Batch — all players' histories (slow, ~60s, rate-limited)
$SYNC player-stats

# Everything at once
$SYNC all

# Bypass freshness checks
$SYNC bootstrap --force

3. Query and Analyze

bash

# All queries go through sqlite3
sqlite3 ~/.fplcopilot/fplcopilot.db "SELECT web_name, position, form, total_points, now_cost FROM players ORDER BY form DESC LIMIT 10;"

Read

references/analysis.md

for formulas and example SQL queries. Read

references/squad.md

for squad management, persistence format, and multi-squad support.

Output Format: HTML vs Markdown

Many FPL outputs are inherently spatial or color-coded — formation, FDR matrix, transfer comparison. For those, generate a self-contained HTML report instead of a markdown table. For quick lookups and one-shot answers, stay in markdown.

When to output HTML

Output type	Format	Template
Squad view (formation, bench, totals)	HTML	`templates/squad-view.html`
Fixture difficulty matrix (teams × next N GWs)	HTML	`templates/fixture-matrix.html`
Transfer comparison (out → in, deltas)	HTML	`templates/transfer-comparison.html`
Captain ranking with reasoning	HTML	`templates/captain-ranking.html`
Gameweek strategy report (squad + fixtures + recs)	HTML	`templates/gameweek-report.html`
Single-stat lookup ("Salah's form?")	markdown	—
Short reasoning ("Bench Haaland this week?")	markdown	—
Deadline, price changes, one-line answers	markdown	—
3-row SQL result	markdown	—

Heuristic: if the user will refer back to it, share it, or scan it visually → HTML. If they glance and move on → markdown.

Universal rules for HTML output

Single self-contained
.html
file. No build step. CSS in
```
<style>
```
, JS in
```
<script>
```
, SVG inlined.
Vanilla HTML/CSS/JS only. No Tailwind, no shadcn, no external CDN, no web fonts.

Mobile responsive. Include

<meta name="viewport" content="width=device-width, initial-scale=1">

. Layout survives a phone viewport.

Save to

~/.fplcopilot/reports/{YYYY-MM-DD}-{slug}.html

. Create the directory with

mkdir -p

if missing.

Tell the user the path after saving. On macOS, offer
```
open <path>
```
to view in their default browser.
Adapt the template, don't write from scratch. Read the matching file in
```
templates/
```
, replace the placeholder data with real values from SQL, save the result.

Before generating any HTML report, read
references/html-output.md
for color tokens, typography, the team-color table, the sortable-table snippet, and the list of anti-patterns to avoid.

Reference Docs

Read these BEFORE answering questions in their domain:

Doc	When to Read
`references/api.md`	Understanding FPL API endpoints and data structure
`references/analysis.md`	Computing metrics (VAPM, projected points, FDR, momentum, etc.)
`references/squad.md`	Squad persistence, management, multi-squad, scoring rules
`references/schema.sql`	Understanding database tables and columns
`references/html-output.md`	Styling rules, color tokens, team colors, anti-patterns for HTML reports

Squad Persistence

Squads are stored as markdown files in

~/.fplcopilot/squads/

— one file per squad. This enables multi-squad support (user's own team, friends' teams, draft plans).

Proactive persistence rules — the agent MUST follow these:

On squad identification: When the user shares their squad (screenshot, text, or any format), immediately save it to
```
~/.fplcopilot/squads/
```
. Ask for a name if unclear.
On squad changes: When the user makes a transfer, changes captain, uses a chip, or modifies their squad in any way, update the squad file immediately after confirming the change.
On conversation start: If the user asks about "my squad" or "my team", check
```
~/.fplcopilot/squads/
```
for existing squad files first. List available squads if multiple exist.
On analysis: After generating a strategy report or analysis, update the squad file's Notes section with key takeaways.
Multi-squad: Users may discuss multiple squads (their own, friends', draft plans). Each gets its own file. The user can specify which squad by name.
File naming: Use kebab-case slugs derived from the squad name (e.g.,
```
my-fpl-team.md
```
,
```
daves-team.md
```
,
```
wildcard-draft.md
```
).

Read

references/squad.md

for the full markdown format specification.

Agent Rules

Always check freshness before answering data questions. If
```
sync_metadata
```
shows stale data (bootstrap > 6h, fixtures on match day > 2h), run the sync script first.
Always check for saved squads when the user asks about "my squad/team". Read
```
~/.fplcopilot/squads/
```
before asking the user to re-share.

Never guess player IDs. Look up by name:

sql

-- Try exact web_name first, then partial, then full name
SELECT * FROM players WHERE web_name = 'Salah' COLLATE NOCASE;
SELECT * FROM players WHERE web_name LIKE '%salah%' COLLATE NOCASE;
SELECT * FROM players WHERE (first_name || ' ' || last_name) LIKE '%salah%' COLLATE NOCASE;

Price units:
```
now_cost
```
is in 0.1m units.
```
130
```
= £13.0m. Always display as
```
£X.Xm
```
.
Position codes: GKP, DEF, MID, FWD (mapped from API's 1, 2, 3, 4).
Status codes:
```
a
```
=available,
```
d
```
=doubtful,
```
i
```
=injured,
```
s
```
=suspended,
```
u
```
=unavailable.
FDR scale: 1 (very easy) to 5 (very hard).
Normalize by price when comparing players: value = points / (cost in millions).
Fetch player detail on demand: Only run
```
sync.sh player <id>
```
when the user asks about a specific player's match-by-match performance. Don't batch-fetch unless explicitly needed.
Proactively persist squads: Always save/update squad files after any squad-related interaction. Never rely on conversation context alone.
Generate HTML for spatial outputs: Any request that maps to a template in
```
templates/
```
— "plan gameweek" / "next gameweek team" →
```
gameweek-report.html
```
; "show/view my squad", formation, bench →
```
squad-view.html
```
; "compare transfer", out → in →
```
transfer-comparison.html
```
; "captain pick" with reasoning →
```
captain-ranking.html
```
; fixture run / FDR matrix →
```
fixture-matrix.html
```
— MUST produce the HTML file (saved to
```
~/.fplcopilot/reports/{YYYY-MM-DD}-{slug}.html
```
) and report the path with an
```
open <path>
```
hint on macOS. Markdown is only for one-line / single-stat lookups, short reasoning, deadlines, price changes, or ≤3-row SQL results.

fpl-copilot

NPX Install

Tags

SKILL.md Content

FPL Copilot

When to Use

Quick Start

1. Check Data Freshness

2. Sync Data

3. Query and Analyze

Output Format: HTML vs Markdown

When to output HTML

Universal rules for HTML output

Reference Docs

Squad Persistence

Agent Rules