Skill: dongbinnie/fpl-assistant (version 1.0.0)

--- name: fpl-assistant description: Fantasy Premier League (FPL) assistant for squad management, transfer planning, captain selection, and chip strategy. Use when users ask about FPL lineup decisions, transfer suggestions, captain picks, gameweek analysis, FPL rules, or anything related to Fantasy Premier League. Triggers on "FPL", "fantasy premier league", "fantasy", "GW" (gameweek), "captain", "transfer", "chip", "wildcard", "free hit", "bench boost", "triple captain". --- # FPL Assistant ## Overview Assist with Fantasy Premier League decisions: squad analysis, transfers, captaincy, chip timing, and gameweek planning. Combine FPL API data with multi-dimensional analysis (not just FDR). ## Core Workflow ### 1. Gather Context Before making recommendations, collect: - User's current 15-player squad (with buy prices) - Remaining budget (ITB) - Available free transfers - Chips status (wildcard, free hit, bench boost, triple captain) - Current GW number ### 2. Fetch Live Data via FPL API Use `curl` against the public FPL API. No auth needed. ```bash # Bootstrap data (teams, players, events) curl -s 'https://fantasy.premierleague.com/api/bootstrap-static/' # GW fixtures with difficulty ratings curl -s 'https://fantasy.premierleague.com/api/fixtures/?event={gw}' # Player detail (history, fixtures) curl -s 'https://fantasy.premierleague.com/api/element-summary/{player_id}/' # Manager team curl -s 'https://fantasy.premierleague.com/api/entry/{manager_id}/event/{gw}/picks/' ``` See `references/api.md` for full API reference. ### 3. Multi-Dimensional Analysis **Do NOT rely solely on FDR (Fixture Difficulty Rating).** FDR is a season-long aggregate and misses short-term dynamics. Layer these factors: | Factor | What to Check | Source | |--------|--------------|--------| | Recent form | Last 4-6 GW results, player form rating | FPL API `form` field, recent results | | League position & motivation | Top 4/6 (European race), bottom 3 (relegation), mid-table dead rubber | League table | | Fixture congestion | Midweek European/FA Cup matches, travel load | Schedule check | | Head-to-head | Recent meetings between the two teams | Historical data | | Home/away split | Some teams significantly better at home | Season stats | | Injury/rotation risk | Flagged players, midweek match recovery | FPL API `status`, news | | Expected stats | xG, xA, shots, key passes vs actual returns | Advanced stats sites | ### 4. Transfer Strategy - **1 free transfer**: Use only if clear upgrade; otherwise roll it to next GW for 2 FTs - **2 free transfers**: Can address multiple weak spots or make a coordinated pair of moves - **-4 hit**: Only if expected point gain exceeds 4+ over multiple GWs - Prioritize: remove players with bad fixtures AND bad form > remove only bad fixtures - Consider value (selling price vs current price) when transferring out ### 5. Captain Selection Priority factors: 1. Fixture difficulty (FDR ≤ 2 strongly preferred) 2. Player form (recent goals/assists) 3. Home advantage 4. Set-piece duty (penalties, free kicks) 5. Expected minutes (rotation risk) 6. Ownership & rank protection vs differential ### 6. Chip Strategy - **Wildcard**: Best used before a fixture swing or when squad needs major overhaul - **Free Hit**: Ideal for blank/double gameweeks where normal squad is affected - **Bench Boost**: Save for double gameweeks when all 15 players play - **Triple Captain**: Use on a premium player with excellent fixture in a single or double GW ## Output Format Provide recommendations as: 1. **Analysis summary** (key factors for the GW) 2. **Starting XI** with formation 3. **Bench order** 4. **Captain / Vice-captain** 5. **Transfer suggestions** (with reasoning) 6. **Chip recommendation** (if applicable) ## Reference Files - `references/rules.md` — Full FPL scoring rules and squad constraints - `references/api.md` — FPL API endpoints and data structures - `references/strategy.md` — Advanced selection methodology

path: references/rules.md
content: # FPL Rules Reference

## Squad Structure

- **Budget**: £100.0m initial
- **Squad size**: 15 players
  - 2 Goalkeepers (GKP)
  - 5 Defenders (DEF)
  - 5 Midfielders (MID)
  - 3 Forwards (FWD)
- **Starting XI**: Pick 11 each GW, must include at least 1 GKP, 3 DEF, 2 MID, 1 FWD
- **Valid formations**: 4-4-2, 4-3-3, 3-4-3, 3-5-2, 4-5-1, 5-4-1, 5-3-2, 5-2-3
- **Club limit**: Maximum 3 players from any single club

## Scoring System

### Playing Time
- Appear (1-59 min): 1 pt
- Appear (60+ min): 2 pts
- Did not play: 0 pts

### Goals
- Goal by GKP: 6 pts
- Goal by DEF: 6 pts
- Goal by MID: 5 pts
- Goal by FWD: 4 pts

### Assists
- Any position: 3 pts

### Clean Sheets (played 60+ min)
- GKP: 4 pts
- DEF: 4 pts
- MID: 1 pt
- FWD: 0 pts

### Goals Conceded (per 2 goals, GKP/DEF only, played 60+ min)
- GKP: -1 pt
- DEF: -1 pt

### Cards
- Yellow card: -1 pt
- Red card: -3 pts (plus loss of any clean sheet bonus for that match)

### Other
- Own goal: -2 pts
- Penalty miss: -2 pts
- Penalty save (GKP): 5 pts
- Save per 3 shots (GKP): 1 pt
- Bonus points: 1-3 pts awarded to top performers in each match (via BPS)

## Transfers

- **Free transfers**: 1 per GW (can bank up to a maximum of 2, i.e., don't use 1 and have 2 next GW)
- **Extra transfers**: Each beyond free allocation costs -4 pts
- **Wildcard**: Unlimited free transfers for that GW (1 in GW1-19, 1 in GW20-38)
- **Deadline**: Usually 90 minutes before first kickoff of the GW

## Player Price Changes

- Prices fluctuate based on transfer activity (net in vs out)
- Selling price = purchase price + 50% of any profit (rounded down)
- Minimum selling price = purchase price (you never lose money on sale below buy price)
- Example: Bought at £7.0m, now £7.6m → profit £0.6m → 50% = £0.3m → sell at £7.3m

## Chips

| Chip | Effect | Available |
|------|--------|-----------|
| Wildcard | Unlimited free transfers for 1 GW | 1 per half-season (GW1-19, GW20-38) |
| Free Hit | Unlimited transfers for 1 GW, squad reverts next GW | 1 per season (GW2-38) |
| Bench Boost | All 15 players score points | 1 per season (GW1-19) |
| Triple Captain | Captain scores 3x instead of 2x | 1 per season (GW1-19) |

Note: Only 1 chip can be played per GW. Wildcard cannot be combined with any other chip.

## Captain & Vice-Captain

- Captain: Points doubled (2x)
- Vice-captain: Becomes captain if captain doesn't play at all (0 minutes)
- If both captain and vice-captain don't play, no captain bonus applies

## Substitutes (Auto-Sub)

- Bench players replace starting players who play 0 minutes
- Substitution order follows bench priority (1st, 2nd, 3rd sub)
- Formation constraints must still be maintained after substitution
- A sub only comes on if it doesn't break the minimum formation rules

## Bonus Points System (BPS)

Players earn BPS during matches based on actions. The top 3 BPS earners in each match get bonus FPL points:
- 1st: 3 pts
- 2nd: 2 pts
- 3rd: 1 pt
- Ties are resolved by splitting (e.g., two players tied 1st both get 2.5 → rounds to 3 and 2)

## Cup

- Qualification: Top ranked managers after GW16
- Format: Head-to-head knockout from GW17 onwards
- Tiebreaker: Overall GW score → overall rank


path: references/api.md
content: # FPL Public API Reference

Base URL: `https://fantasy.premierleague.com/api/`

No authentication required for public endpoints. Rate limit is generous but avoid excessive calls.

## Key Endpoints

### 1. Bootstrap Static (Master Data)

```
GET /bootstrap-static/
```

Returns ALL static data. Cache this — it's large (~2MB) but contains everything:

**Top-level keys:**
- `events` — Gameweeks (deadlines, status, chip plays)
- `teams` — 20 PL clubs (id, name, short_name, strength ratings)
- `element_types` — Position types (1=GKP, 2=DEF, 3=MID, 4=FWD)
- `elements` — All players (see below)
- `game_settings` — Scoring rules
- `chips` — Chip availability windows

**Key fields in `elements[]` (players):**
```
id                    — Player unique ID
web_name              — Short display name
element_type          — Position (1-4)
team                  — Team ID
now_cost              — Current price (×10, e.g. 75 = £7.5m)
selected_by_percent   — Ownership %
form                  — Average points last 30 days (string)
total_points          — Season total
event_points          — Last GW points
points_per_game       — Season average
minutes               — Total minutes played
goals_scored, assists — Season totals
clean_sheets          — Season total
yellow_cards, red_cards
bonus                 — Total bonus points
bps                   — Total BPS
influence, creativity, threat — ICT index values
transfers_in_event    — Transfers in this GW
transfers_out_event   — Transfers out this GW
status                — Availability: a=available, d=doubtful, i=injured, s=suspended, u=unavailable
news                  — Injury/availability news
chance_of_playing_this_round  — % or null
chance_of_playing_next_round  — % or null
```

### 2. Fixtures

```
GET /fixtures/
GET /fixtures/?event={gw}     — Specific gameweek
```

**Fields per fixture:**
```
event                    — GW number
kickoff_time             — ISO datetime
team_h, team_a           — Home/away team IDs
team_h_score, team_a_score
team_h_difficulty        — FDR for home team (1-5)
team_a_difficulty        — FDR for away team (1-5)
stats[]                  — Goals, assists, cards, bonus etc.
finished, started        — Match status
minutes                  — Minutes played
```

### 3. Element Summary (Player Detail)

```
GET /element-summary/{player_id}/
```

Returns:
- `history[]` — All past GW performances (opponent, points, minutes, goals, assists, etc.)
- `fixtures[]` — Upcoming fixtures (team, difficulty, home/away)

### 4. Manager / Entry Endpoints

```
GET /entry/{manager_id}/                — Manager profile
GET /entry/{manager_id}/event/{gw}/picks/  — Manager's team for a GW
GET /entry/{manager_id}/history/        — Season history
```

### 5. Live Data

```
GET /event/{gw}/live/                   — Live points for all players in a GW
```

Returns `elements[]` with `stats` for each player (points, minutes, goals, etc.)

### 6. Dream Team

```
GET /dream-team/{gw}/                   — Best XI for a GW
```

## Python Snippets

### Get all players as a usable dict

```python
import json, urllib.request

data = json.loads(urllib.request.urlopen(
    'https://fantasy.premierleague.com/api/bootstrap-static/'
).read())

teams = {t['id']: t for t in data['teams']}
positions = {t['id']: t['singular_name_short'] for t in data['element_types']}

players = []
for e in data['elements']:
    players.append({
        'id': e['id'],
        'name': e['web_name'],
        'team': teams[e['team']]['short_name'],
        'pos': positions[e['element_type']],
        'price': e['now_cost'] / 10,
        'form': float(e['form']),
        'pts': e['total_points'],
        'selected': float(e['selected_by_percent']),
        'goals': e['goals_scored'],
        'assists': e['assists'],
        'status': e['status'],
    })
```

### Get GW fixtures with team names

```python
fixtures = json.loads(urllib.request.urlopen(
    'https://fantasy.premierleague.com/api/fixtures/?event=32'
).read())

for f in fixtures:
    home = teams[f['team_h']]['short_name']
    away = teams[f['team_a']]['short_name']
    print(f"{home} vs {away} | FDR: {f['team_h_difficulty']}/{f['team_a_difficulty']}")
```

### Get player's recent GW history

```python
summary = json.loads(urllib.request.urlopen(
    f'https://fantasy.premierleague.com/api/element-summary/{player_id}/'
).read())

for h in summary['history'][-5:]:  # last 5 GWs
    print(f"GW{h['round']}: {h['total_points']}pts ({h['minutes']}min, {h['goals_scored']}G, {h['assists']}A)")
```

## Tips

- Call `/bootstrap-static/` once and cache; use `elements` array for all player queries
- Team IDs are stable within a season; map once from `teams[]`
- `now_cost` is in tenths — divide by 10 for display price
- `form` field is already a rolling average, useful for quick comparison
- `status` field: only `a` means fully fit; treat `d`/`i`/`s` with caution


path: references/strategy.md
content: # FPL Player Selection Strategy

## Analysis Framework

Do NOT rely on a single metric. Layer multiple factors for robust decisions.

### Factor 1: Fixture Context (Beyond FDR)

FDR is a season-long aggregate. Supplement with:

- **Recent form (last 5-6 GWs)**: Is the team on a hot streak or in freefall? A "FDR 2" fixture means nothing if the opponent just hit form.
- **Home/away split**: Some teams have dramatically different records. Check if the fixture is home or away for YOUR player.
- **Clean sheet trends**: DEF/GKP value depends heavily on the opponent's scoring form, not just the team's overall strength.
- **Expected goals (xG)**: Teams generating high xG but underperforming are due for regression (positive). Teams overperforming xG are likely to regress.

### Factor 2: Motivation & League Context

- **Title race / Top 4 / Top 6**: Teams fighting for European spots are more motivated and likely to field full-strength sides.
- **Relegation battle**: Bottom-3 teams fighting for survival can be dangerous opponents (no easy games) BUT also more likely to concede pushing forward.
- **Mid-table with nothing to play for**: Lower intensity, more rotation risk, less reliable output.
- **Dead rubber at season end**: High rotation risk for established teams.

### Factor 3: Fixture Congestion

- **Midweek European matches**: UCL/UEL midweek → likely rotation for weekend PL match. Check if the player's team played midweek.
- **FA Cup / League Cup**: Extra matches = fatigue + rotation risk.
- **Travel**: European away trips (Eastern Europe, long flights) increase fatigue more than home European matches.
- **Key rule**: Premium players (Haaland, Salah tier) rarely rotated. Mid-tier players (6-9m) are at highest rotation risk during congestion.

### Factor 4: Head-to-Head & Style Matchups

- Some teams consistently struggle against specific opponents regardless of overall strength
- Defensive teams vs attacking teams: matters for CS probability
- Set-piece reliant teams vs teams weak at defending set pieces

### Factor 5: Player-Specific Factors

- **Minutes security**: Will the player start AND play 60+? Check recent starts, manager comments, injury news.
- **Set-piece duty**: Penalty takers, corner takers, free-kick takers have higher ceilings.
- **Underlying stats vs returns**: A player creating lots of chances but not converting is "due." A player overperforming xG may regress.
- **Price trajectory**: Rising in price = high demand, likely good pick. Falling = consider if it's a short-term blip or a real decline.

## Positional Strategy

### Goalkeepers (GKP)

- Value position: don't overspend (4.5-5.5m range is optimal)
- Prioritize: CS potential > save points > bonus points
- Consider a rotating pair (two 4.5m keepers with alternating good fixtures)
- Set-and-forget premium (5.5m+) only if truly elite (e.g., Alisson, Raya)

### Defenders (DEF)

- Full-backs with attacking returns > center-backs (higher ceiling)
- Look for: nailed starters + set-piece involvement + CS potential
- 4.0-4.5m bench fodder is fine for 4th/5th defender
- Best value range: 4.5-5.5m

### Midfielders (MID)

- Widest price range, most points potential
- Premium (10m+): captain candidates, fixture-proof
- Mid-range (7-10m): best value zone, strong starters
- Budget (5-7m): enablers, look for form + fixture combo
- Penalty takers in MID are gold (goals = 5 pts each)

### Forwards (FWD)

- Fewer elite options vs MID, but premium FWDs are essential
- Haaland-tier: always own, captain in good fixtures
- Mid-range (7-9m): look for nailed starters with good fixtures
- Budget (5-7m): rotation risk, only if genuinely starting

## Transfer Decision Tree

```
Need a transfer?
├── Do I have an injured/suspended player? → YES → Transfer (mandatory)
├── Do I have a player with FDR 5 + bad form? → YES → Strong candidate
├── Can I roll the transfer (max 2 banked)? → YES → Consider rolling
│   ├── No clear upgrade available → Roll
│   └── Clear upgrade available → Make the move
└── Is it worth a -4 hit?
    ├── Expected gain over next 3+ GWs > 4 pts? → Maybe
    └── Only expecting gain this GW? → Probably not
```

## Captain Selection Matrix

| Factor | Weight |
|--------|--------|
| Fixture (FDR ≤ 2 preferred) | High |
| Form (recent returns) | High |
| Home/away | Medium |
| Set-piece duty (pens, FKs) | Medium |
| Minutes security | Medium |
| Ownership (protection vs differential) | Low-Medium |

**Default approach**: Captain the player with the best fixture AND form combination. When in doubt, captain the most-owned premium option (safety in numbers for rank protection).

## Chip Timing

### Wildcard
- Best windows: GW3-5 (early season adjustments), GW20-22 (second half setup)
- Use when: squad needs 5+ changes, or a major fixture swing is coming

### Free Hit
- Best for: Blank Gameweeks (BGW) where many teams don't play
- Strategy: Build a squad of 11 players who ALL play that week
- Don't waste on normal GWs

### Bench Boost
- Best for: Double Gameweeks (DGW) where teams play twice
- Prep: Ensure bench players have 2 fixtures that week
- Can combine with Wildcard the week BEFORE to set up

### Triple Captain
- Best for: DGW with premium captain having 2 good fixtures
- Alternative: Single GW with an elite fixture (FDR 1, home)
- Don't use on a single GW unless the fixture is truly exceptional

## Season Arc

- **GW1-8**: Be patient, don't kneejerk. Early form can be misleading.
- **GW9-19**: First Wildcard window. Solidify squad structure.
- **GW20-25**: Second half Wildcard. Plan for DGW/BGW.
- **GW26-30**: Chip planning begins. Save transfers for DGW setups.
- **GW31-38**: Execute chips. End-of-season rotation increases. Target teams still motivated.


path: README.md
content: # FPL Assistant Skill

A knowledge skill for AI agents assisting users with Fantasy Premier League (FPL) decisions. This skill enables agents to provide informed recommendations on transfers, captain picks, lineup selection, and chip strategy using live FPL data.

## When the Skill Is Triggered

This skill activates when users mention:

- **FPL terminology**: `FPL`, `fantasy premier league`, `fantasy`, `GW` (gameweek)
- **Decisions**: `captain`, `transfer`, `chip`, `wildcard`, `free hit`, `bench boost`, `triple captain`
- **Requests**: asking for lineup suggestions, transfer advice, gameweek analysis, FPL rules explanation

## How to Use in OpenClaw

### Installation

1. **Download the skill** — Clone or copy this repository into your OpenClaw workspace skills directory:
   ```
   workspace/skills/fpl-assistant/
   ```
2. **Install dependencies** — None required. This is a pure documentation skill with no code dependencies.
3. **Have OpenClaw read SKILL.md thoroughly** — Before using the skill, ask OpenClaw to read through `SKILL.md` completely so it fully understands the workflow, trigger phrases, reference file locations, and recommended output format.
4. **Activate the skill** — OpenClaw will automatically detect trigger phrases and load the skill when needed.

### Usage

When a user asks an FPL-related question, the agent automatically:

1. **Detects the trigger** and activates the skill
2. **Reads the skill definition** from SKILL.md
3. **Follows the 6-step workflow** — gathering context, fetching live FPL API data, applying multi-dimensional analysis (per strategy.md), and producing recommendations
4. **Returns structured output** in the format defined in SKILL.md

Reference documents are consulted as needed: `references/api.md` for API calls, `references/rules.md` for rules, `references/strategy.md` for analysis methodology.

## Skill Workflow

The skill defines a 6-step process for FPL assistance:

1. **Gather context** — Collect the user's squad state (manager ID, budget, current transfers, active chips, target GW)
2. **Fetch live data** — Call FPL API endpoints (bootstrap-static, fixtures, element-summary)
3. **Multi-dimensional analysis** — Layer FDR with form, motivation, fixture congestion, home/away, head-to-head matchups, xG regression
4. **Transfer strategy** — Evaluate free transfers, rolling FTs, -4 hit guidelines
5. **Captain selection** — Weight fixture difficulty, form, home/away, set-piece risk, minutes, ownership
6. **Chip strategy** — Advise on wildcard, free hit, bench boost, and triple captain timing windows

## Reference Files

| File | Purpose |
|------|---------|
| `SKILL.md` | Skill definition, trigger phrases, and core workflow |
| `references/rules.md` | FPL scoring rules, squad structure, transfer mechanics, chip effects |
| `references/api.md` | FPL API endpoints, data structures, Python code snippets |
| `references/strategy.md` | Advanced multi-factor analysis methodology, positional strategy, chip timing windows |

## Key Notes

- **FDR is insufficient alone** — Use the multi-factor approach in `references/strategy.md`. FDR (Fixture Difficulty Rating) is a starting point; form, motivation, fixture congestion, and head-to-head history must be layered in.
- **Cache bootstrap-static** — Call `/bootstrap-static/` once and cache it (~2MB); it contains all player/team/gameweek data.
- **Chip timing windows**:
  - Wildcard: GW3–5 or GW20–22
  - Free Hit: blank gameweeks (BGW)
  - Bench Boost: double gameweeks (DGW)
  - Triple Captain: DGW with premium players
- **Season arc**: GW1–8 patience, GW9–19 first wildcard, GW20–25 second wildcard, GW26–30 chip planning, GW31–38 execute.

## Example API Usage

```bash
# Fetch master data (cache this)
curl https://fantasy.premierleague.com/api/bootstrap-static/

# Get fixtures with FDR
curl https://fantasy.premierleague.com/api/fixtures/

# Get player history and upcoming fixtures
curl https://fantasy.premierleague.com/api/element-summary/{player_id}/

# Get a manager's squad for a gameweek
curl https://fantasy.premierleague.com/api/entry/{manager_id}/event/{gw}/picks/
```

## File Structure

```
fpl-assistant/
├── README.md           ← you are here
├── SKILL.md            ← skill definition and trigger config
└── references/
    ├── api.md          ← FPL API reference
    ├── rules.md        ← FPL rules and scoring
    └── strategy.md      ← advanced decision methodology
```

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)