♟️ Claude Code: Advanced Chess Post-Mortem Skills

This project introduces a suite of specialized skills for Claude Code, designed to transform raw chess game data into comprehensive, readable post-mortems. Instead of staring at cold engine numbers, you get plain-language critiques, Stockfish-verified annotations, and fully narrated game videos.

Note: You can find the original discussion and community insights over at Hacker News.

🎙️ The "Think-Aloud" Innovation

The most powerful feature of this tool is its ability to integrate your internal monologue. In a sample game (a $15+10$ rapid match on Lichess, Open Sicilian/Najdorf, ~1700 rating), the author recorded their thoughts in French using a simple voice recorder.

How it works:

Transcription: Claude utilizes whisper.cpp to transcribe the audio locally.
Temporal Alignment: By analyzing the clock timestamps within the PGN file, Claude matches specific spoken sentences to the exact move being contemplated.
Reasoning Refutation: Instead of guessing why you made a mistake, Claude can say: "At move eight, you wondered if the bishop belonged on c4 or e2," and then provide the engine-backed answer to that specific internal question.

Chess Analysis Concept (Conceptual representation of the analysis output)

🧠 Why Use This Over Raw Stockfish?

Standard engine analysis is often sterile and frustrating. It provides a numerical evaluation and a 12-move sequence that is practically impossible for a human to calculate.

Stockfish: -1.8 (Move 14. Be3 is a blunder, play 14. Nf3 instead) $\rightarrow$ Claude: "You played Be3 because you feared the pressure on d4, but Black can simply ignore this and push e5, gaining a decisive space advantage."

Is this for you?

Do you play slow or rapid games and want deep learning?
Are you comfortable running Claude Code locally?
Are you willing to record your thoughts or take notes during a game? (Optional, but highly recommended).

Performance Note: A complete pipeline (sweep $\rightarrow$ investigation $\rightarrow$ annotation $\rightarrow$ video) takes approximately one hour of processing. It is best suited for games where you spent significant time thinking.

🔄 The Analysis Workflow

🛠️ Skill Breakdown

Skill	Primary Function	Key Outputs
`chess-analysis`	Deep Stockfish sweep & "investigator" sub-agents.	Layered PGN, HTML analysis board, "Plan Pause" summaries.
`chess-video`	Generates a narrated game walkthrough.	MP4 video (arrows, eval bar, Piper TTS, subtitles), HTML viewer.
`chess-play`	Adversarial gameplay against Claude.	PGN-based play with PNG board rendering for vision.

🚀 Installation & Setup

1. Deploy the Skills

You can add the skills to a specific project or make them global:

# Clone the repository
git clone https://github.com/brumar/chess-postmortem-skills

# Install globally for all projects
cp -r chess-postmortem-skills/skills/* ~/.claude/skills/

2. Dependencies

Claude Code can likely handle this for you if you ask it to "install the dependencies for the chess skills," but the requirements are:

Python Environment: A .venv-chess containing:
- python-chess
- cairosvg (for analysis)
- pillow & piper-tts (for video)
Engine: Stockfish (via scripts/get_stockfish.sh or system PATH).
Media: ffmpeg and a Piper voice model.

3. File Structure

The system expects a specific directory layout at your project root: chess-games/ $\rightarrow$ games/, boards/, video/.

🎯 Personalization

To ensure the analysis is pitched at the correct difficulty, you should define your skill level. This is handled via the audience.level parameter in annotations.json.

Pro Tip: Add your rating to your CLAUDE.md file so Claude remembers it across sessions:

"My Lichess rating is 1700; please tailor all chess analysis to this level."