---
name: stockfish
description: Use this skill when the user asks to analyze a chess position, get the best move, evaluate a FEN string, check a chess move sequence, invokes /stockfish, asks "what should I play here?", "what's the best move?", or provides a FEN string and wants engine analysis. Use whenever there is a specific chess position to evaluate with an engine.
allowed-tools: Bash
---

# Stockfish Chess Analysis

Analyze chess positions using the local Stockfish engine via UCI. Works with FEN strings or UCI move sequences.

## Setup Check

Before first use, verify Stockfish is installed:

```bash
python3 ~/.claude/skills/stockfish/scripts/find_stockfish.py
```

If not found:
- macOS: `brew install stockfish`
- Linux: `sudo apt install stockfish` or `sudo dnf install stockfish`
- Override path: `export STOCKFISH_PATH=/path/to/stockfish`

## Invocation

Always run analysis from the skill's scripts directory using absolute path:

```bash
python3 ~/.claude/skills/stockfish/scripts/analyze.py [OPTIONS]
```

### From a Move Sequence

When the user provides moves in any order notation:

```bash
python3 ~/.claude/skills/stockfish/scripts/analyze.py \
  --mode multipv \
  --moves "e2e4 e7e5 g1f3 b8c6 f1b5" \
  --lines 3 \
  --depth 18
```

### From a FEN String

```bash
python3 ~/.claude/skills/stockfish/scripts/analyze.py \
  --mode multipv \
  --fen "r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3" \
  --lines 3 \
  --depth 18
```

### Best Move Only

```bash
python3 ~/.claude/skills/stockfish/scripts/analyze.py \
  --mode best-move \
  --fen "..." \
  --depth 20
```

### Deep Analysis

```bash
python3 ~/.claude/skills/stockfish/scripts/analyze.py \
  --mode multipv \
  --fen "..." \
  --lines 5 \
  --depth 25
```

### Time-Limited Analysis

```bash
python3 ~/.claude/skills/stockfish/scripts/analyze.py \
  --mode multipv \
  --fen "..." \
  --movetime 3000 \
  --lines 3
```

## Options Reference

| Option | Default | Description |
|---|---|---|
| `--mode` | `multipv` | `best-move`, `multipv`, or `evaluate` |
| `--fen` | — | FEN string (use instead of --moves) |
| `--moves` | `""` | UCI moves from startpos, space-separated |
| `--depth` | `18` | Search depth (12=fast, 18=good, 24+=deep) |
| `--movetime` | `0` | Search time in ms (overrides --depth if >0) |
| `--lines` | `3` | Top moves to show in multipv mode |

## Move Notation Translation

Users often give SAN notation. Translate to UCI long algebraic before passing to `--moves`:

| SAN | UCI | Notes |
|---|---|---|
| `e4` | `e2e4` | Include source rank for pawns |
| `Nf3` | `g1f3` | Include full source square |
| `O-O` | `e1g1` | White kingside castle |
| `O-O-O` | `e1c1` | White queenside castle |
| `o-o` | `e8g8` | Black kingside castle |
| `exd5` | `e4d5` | Include source file+rank for captures |
| `e8=Q` | `e7e8q` | Append promotion piece letter |

If the user provides a FEN, use `--fen` instead of translating moves.

## Interpreting Output

- **Score in pawns**: `+0.5` = slight White advantage, `+2.0` = significant, `+5.0` = decisive
- **Negative scores** favor Black
- **"Mate in N"**: Stockfish sees forced checkmate in N moves
- **Move notation**: source+destination (e.g., `e2e4`, `g1f3`, `e1g1` = kingside castle)

## Default Depths

| Use case | Depth | Typical time |
|---|---|---|
| Quick check | 12 | ~0.3s |
| Normal analysis | 18 | ~1–3s |
| Deep analysis | 24 | ~5–15s |
| Maximum | 30+ | 30s+ |

## Reference Files

- `references/uci-protocol.md` — Full UCI command/response reference for debugging
- `references/fen-notation.md` — FEN format, common positions, SAN→UCI translation guide