# A Claude Code chess skill pairs Stockfish analysis with a player's notes

> A public Claude Code skill set combines Stockfish evaluations, player notes and model-written explanations in a reviewable chess post-mortem. We trace its documented workflow and limits.

By BIG CHANGE Editorial

Published: 2026-09-26T20:57:48.171Z
Updated: 2026-09-26T20:57:48.171Z
Canonical: https://bigchange.ai/blog/claude-code-chess-stockfish-postmortem-skill

![A chess player studies a midgame position on a wooden chessboard beside an analog chess clock in a quiet club room.](https://bigchange.ai/api/media/file/chess-postmortem-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE.

A public set of Claude Code skills turns a chess game into an annotated PGN and an HTML analysis board. The author also provides a route to a narrated video. Stockfish evaluates positions; Claude Code asks follow-up questions and writes explanations for the player. The [repository](https://github.com/brumar/chess-postmortem-skills) supplies one worked game and the scripts behind that process. BIG CHANGE inspected the documentation and code at commit `46919038`, dated September 26, 2026; we did not run the workflow or assess the chess advice ourselves.

## The big change

- **What changed:** This small public project documents a workflow that connects an engine's position checks to explanations aimed at a chess player's own game and, when supplied, their recorded reasoning.
- **Why it matters:** A player can inspect the PGN, engine sweep, saved query lines and annotations separately. That makes a generated explanation easier to question at the position it describes. Whether it helps a player improve is unmeasured here.
- **What to watch:** The model still chooses questions, interprets engine lines and writes the lesson. The prompt-based verifier checks that work, but its presence does not establish accuracy. A reader deciding whether to use the output for study should review the cited positions and lines.

## From a game record to candidate mistakes

The input is a PGN game, either supplied directly or obtained from a game link. The `chess-analysis` skill first sets the reader's level so its comments can target that player. Written notes can be added. For a recorded think-aloud, the documented path uses local whisper.cpp transcription and aligns speech to moves using clock comments in the PGN. That alignment depends on usable clock data and on matching spoken references to moves; it is not a way to recover a player's thoughts from a PGN alone.

The first mechanical pass is visible in [`sweep.py`](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/skills/chess-analysis/scripts/sweep.py). It asks Stockfish to evaluate the position before and after each played move, records candidate moves and scores, and flags a move when the measured loss reaches the script's default 30 centipawns. The documented default search depth is 22. These evaluations locate positions for closer inspection; their numbers do not themselves explain a mistake.

The skill then directs a Claude Code investigator to examine each flagged position. Its [`query.py`](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/skills/chess-analysis/scripts/query.py) can ask Stockfish about alternative moves, including a search restricted to a proposed move, and save the resulting lines in JSON. Separate instructions tell the investigator to inspect board images and explain why a move or alternative works. The player notes may inform an explanation only where the note belongs to that move. This is the point where engine output becomes model-written chess prose, with judgment and possible error entering the result.

## What the checks and outputs establish

The repository's `chess-analysis` skill calls for a separate verifier agent to review the finished annotations with the sweep and player notes. Its checklist covers flagged mistakes, legal variations, evaluation claims and statements about what the player thought; evaluation claims should match the sweep or saved engine queries. The [`build_annotated.py` script](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/skills/chess-analysis/scripts/build_annotated.py) also reparses the PGN and reports parsing errors. Those are distinct checks: parsing establishes that the moves can be read, while the verifier is another model-directed review of the explanations. Neither establishes that every interpretation is correct. The author says errors have been rare in personal use, but provides no independent error study.

The saved annotated PGN and [`build_viewer.py`](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/skills/chess-analysis/scripts/build_viewer.py) produce a standalone HTML board with comments, an evaluation graph and cached engine lines. A later, optional [`chess-video` skill](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/skills/chess-video/SKILL.md) starts from the annotated PGN and sweep. It asks Claude Code to write a storyboard, then its scripts render the board, synthesize narration and create an MP4 with subtitles. The repository includes one example from the author's own rapid game, including the transcript, sweep, annotations and a 6 minute 49 second video. That example shows the intended artifacts, not a measured result across players or games.

## Prerequisites, time and limits

The [README](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/README.md) says to copy the skill folders into Claude Code's personal or project skills directory, then provide a game link or PGN. [Claude Code's own documentation](https://code.claude.com/docs/en/skills) confirms those skill locations. Analysis needs Python with `python-chess` and `cairosvg`, plus a Stockfish executable. The repository's fetch script uses an existing executable when available or downloads a Linux x86-64 Stockfish 17.1 build. [Stockfish's current download page](https://stockfishchess.org/download/) lists version 19, so the repository's fallback is pinned to an older release. Optional audio needs whisper.cpp and a model; its [documentation](https://github.com/ggml-org/whisper.cpp) describes converting audio to 16-bit WAV for `whisper-cli`. The video stage also needs Pillow, Piper text to speech or espeak, and FFmpeg. These paths and dependencies are documented; this article is not an installation test or a compatibility guarantee for a particular machine.

The author estimates about one hour of processing for the complete review and video. The repository gives no bill for that run. [Anthropic's current plan table](https://claude.com/pricing) lists Claude Code under Pro rather than Free; Pro is $20 a month when billed monthly, with usage limits. Local compute time, any subscription or API usage, and the optional transcription and video setup make the cost depend on the reader's environment. The example's time and the author's view of its accuracy should be read as a single user's account.

## Sources

- [brumar/chess-postmortem-skills, README at commit 46919038](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/README.md) — Author's account of the game, inputs, example outputs, installation, prerequisites and approximately one-hour processing time. Its personal error assessment and timing are not independent measurements.
- [Chess analysis skill and verifier checklist](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/skills/chess-analysis/SKILL.md) — Describes PGN and optional notes/audio input, Stockfish sweep, investigator queries, annotation build, model-directed verifier and HTML output. The verifier checklist is in the linked references/style.md; written instructions do not prove every review is correct.
- [Chess analysis scripts: sweep, query, annotation build and viewer](https://github.com/brumar/chess-postmortem-skills/tree/46919038bd849995522d9414b4781d3442940a3d/skills/chess-analysis/scripts) — Code establishes default depth and loss threshold, restricted Stockfish queries with saved lines, PGN reparse, and HTML bundling. Source inspection alone is not an execution test or quality assessment.
- [Chess video skill and rendering script](https://github.com/brumar/chess-postmortem-skills/blob/46919038bd849995522d9414b4781d3442940a3d/skills/chess-video/SKILL.md) — Documents the optional storyboard, narration, MP4, subtitles and HTML stage, with separate video prerequisites. No video was generated by BIG CHANGE.
- [Claude Code documentation: skills](https://code.claude.com/docs/en/skills) — Confirms personal and project skill directory locations. It does not validate this third-party project's cross-version compatibility.
- [Stockfish official downloads](https://stockfishchess.org/download/) — Lists Stockfish 19 and platform downloads. The inspected project's fallback download script is pinned to Linux x86-64 Stockfish 17.1.
- [whisper.cpp official repository](https://github.com/ggml-org/whisper.cpp) — Documents whisper-cli and input conversion to 16-bit WAV. Transcription and audio-to-move alignment are optional parts of this project and were not tested here.
- [Anthropic Claude pricing](https://claude.com/pricing) — The individual plan table lists Claude Code on Pro, not Free, and Pro at $20 monthly or $17 per month equivalent with annual billing. Usage limits and price changes apply; the chess project provides no per-run cost.