chess-postmortem-skills: AI-Powered Chess Game Analysis for Claude Code

Overview

chess-postmortem-skills is a set of specialized skills for Claude Code that transforms raw chess game data (PGN files) into comprehensive, human-readable post-mortems. Unlike traditional engine analysis that provides numerical evaluations and complex move variations, this tool uses an LLM to drive the Stockfish engine, translating technical data into plain-language explanations of mistakes and strategic plans.

Core Capabilities

The project is divided into three primary skills, each handling a different aspect of the game review process:

1. Chess Analysis (chess-analysis)

This skill performs a deep dive into the game's technical aspects. It executes a Stockfish sweep of every move and deploys parallel "investigator" subagents to interrogate the engine with naive questions (e.g., "Why not the move I played?" or "What if Black simply takes?").

Key outputs include:

• Annotated PGN: A layered PGN file with human-readable commentary.
• HTML Analysis Board: A standalone interactive viewer for the game.
• Plan Pause: A specific point in the game where the engine derives the strategic plans for both players.
• Think-Aloud Integration: If provided with an audio recording of the player's thoughts during the game, the skill uses whisper.cpp to transcribe the audio and align the text to specific moves using the PGN clock timestamps.

2. Chess Video (chess-video)

This skill generates a narrated video of the entire game. The video includes the board, arrows, an evaluation gauge, burned-in subtitles, and audio narration generated via Piper TTS. It is built from a storyboard generated during the analysis phase.

3. Chess Play (chess-play)

This skill allows a user to play a game against Claude. To maintain accuracy, the board is rendered to PNG for vision-based processing, and adversarial blunder-check subagents are used. Notably, this skill does not use an engine.

Technical Workflow and Requirements

User Workflow

1. Game Capture: Play a game (Rapid or Correspondence) and record a "think-aloud" audio file or write notes per move.
2. Initiation: Provide Claude Code with the game link/PGN and the recording.
3. Processing: The system runs a sweep, conducts investigations, and generates annotations (taking approximately one hour for a full run).
4. Review: The user reviews the annotated PGN and HTML board, then requests a narrated video.
5. Iterative Learning: The user can ask follow-up questions about specific positions, which Claude verifies with the engine before answering.

System Requirements

Claude Code can typically install these dependencies automatically upon request:

• Python Environment: A venv containing python-chess, cairosvg, pillow, and piper-tts.
• Stockfish: The official engine binary (installed via scripts/get_stockfish.sh).
• Video Tools: ffmpeg and a Piper voice model.
• Transcription: whisper.cpp (optional, for think-aloud recordings).

Design Philosophy: Engine-Driven LLM

The project addresses a common limitation of LLMs in chess: their tendency to hallucinate moves or misunderstand board states. To mitigate this, the tool does not rely on the LLM's internal chess knowledge. Instead, the LLM acts as an operator for Stockfish. Every claim made by the AI is checked against the engine, and a verifier pass re-reads the results to ensure accuracy.

Community Insights and Counterpoints

While the project has been praised for its concrete use of Claude Code skills, some users on Hacker News raised concerns regarding the efficacy of LLM-based chess coaching:

"The elo of opus 5 models is 1300 or so. I wouldn't take chess lessons from a 1300."

Other critics argued that the "tedious" work of manual analysis is where the actual learning happens, suggesting that automated summaries might be less effective for skill improvement. Conversely, proponents of the approach noted that integrating LLMs with Monte Carlo simulations or traditional solvers (as seen in other AI-driven game analysis tools) is a viable way to provide interpretability to complex data.

Installation

To install the skills, clone the repository and copy the skill folders into the Claude Code skills directory:

git clone https://github.com/brumar/chess-postmortem-skills
cp -r chess-postmortem-skills/skills/* ~/.claude/skills/