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

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 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. 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 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 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 produce a standalone HTML board with comments, an evaluation graph and cached engine lines. A later, optional chess-video skill 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 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 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 lists version 19, so the repository's fallback is pinned to an older release. Optional audio needs whisper.cpp and a model; its documentation 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 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.