{"slug": "show-hn-a-claude-code-skill-to-analyze-your-chess-games", "title": "Show HN: A Claude Code skill to analyze your chess games", "summary": "A developer published a Claude Code skill that turns a single chess game into a readable post-mortem, using Stockfish to verify every claim and whisper.cpp to transcribe a player's think-aloud recording. The tool, demonstrated on a 15+10 rapid game on lichess played around a 1700 rating, produces an annotated PGN, a standalone HTML analysis board, and a narrated video, with a full run taking roughly one hour of processing. The author recommends feeding it written notes or audio so the review critiques the player's actual reasoning rather than a guessed one, and notes a verifier pass re-reads each engine-checked claim to keep errors rare.", "body_md": "Claude Code skills that turn one of your chess games into a post-mortem you can actually read: plain-language explanations of your mistakes, checked against Stockfish, and a narrated video of the whole game.\n\n## out-010.mp4\n\n*6:49, English narration, subtitles.*\n\nThis is a real game of mine: a 15+10 rapid on lichess\n([5KmlrdyT](https://lichess.org/5KmlrdyT)), White, Open Sicilian against a\nNajdorf, around 1700. During the game I recorded myself thinking aloud, in\nFrench, with a plain voice recorder running next to the board. After the\ngame I gave Claude two things: the lichess link and the mp3.\n\nClaude transcribed the audio locally with whisper.cpp, then used the clock\ntimes in the PGN to match each sentence to the move I was deciding at that\nmoment. So when the video says \"at move eight you asked yourself whether\nthe bishop belongs on c4 or e2\", that is my own question, answered with\nthe engine. Everything the video shows (the transcript, the Stockfish\nsweep, the annotated PGN, the storyboard) is in `examples/game-010/`.\n\nA Stockfish analysis gives you numbers and lines. It is not fun to read,\nand often it does not tell you *why*: -1.8 after your move, and a 12-move\nvariation you would never find at the board.\n\nI realized Claude can drive Stockfish itself. It asks the engine the questions a human would ask (\"why not the move I played?\", \"what if Black simply takes?\"), keeps asking until the answer makes sense, and writes it down in human terms. And since it knows what I was thinking during the game, it can refute my actual reasoning instead of a guessed one. After the analysis I can keep asking my own questions about any position, and it checks them with the engine before answering.\n\nProbably yes if:\n\n- you play slow or rapid games and want to learn from them, not just see where the eval bar dropped;\n- you are fine running Claude Code on your machine;\n- you are willing to take notes or talk during the game (optional, but this is what makes the result interesting).\n\nProbably not if you want a quick check of a blitz game. Lichess or chess.com analysis does that in seconds.\n\n**It takes time.** A full run (sweep, investigations, annotations, video)\ntakes around one hour of processing. Use it on games where you took the\ntime to think, not on every game you play.\n\n**Give it your thoughts.** I strongly recommend passing your written notes\nor an audio recording covering the whole game. Without them you get a good\nengine explanation. With them you get a review of *your* reasoning:\nwhich fears were justified, which plans were sound, which questions you\nasked yourself and what the answer was.\n\n**Hallucinations.** The AI can still get something wrong. Every claim is\nchecked against Stockfish and a verifier pass re-reads the result, so in\nmy experience errors are rare. If something looks off, ask Claude to\ncheck that position with the engine.\n\n1. Play a game with some time to think (15+10 rapid, or correspondence).\n2. Record myself thinking aloud during the game (any phone or web voice recorder). For correspondence games, I write notes per move instead.\n3. After the game, open Claude Code and say something like: \"analyze this game: , here is my think-aloud recording: \".\n4. Wait about an hour. I get an annotated PGN and a standalone HTML analysis board.\n5. Ask for the video: \"make a video of this game\".\n6. Read, watch, then ask questions about the positions I still do not understand.\n\n| skill | what it does | \n|---|---|\n| `chess-analysis` | Stockfish sweep of every move, then parallel \"investigator\" subagents that interrogate the engine with naive questions until every mistake is explained. Output: a layered annotated PGN, a standalone HTML analysis board, and one \"plan pause\" per game where both sides' plans are derived from the engine. Handles the think-aloud recording: whisper.cpp transcription, alignment to moves via the PGN clocks. | \n| `chess-video` | A narrated video of the whole game (board, arrows, eval gauge, piper TTS, burned-in subtitles) built from a storyboard, plus an interactive HTML viewer. | \n| `chess-play` | Play a game against Claude over PGN files, with the board rendered to PNG for vision and adversarial blunder-check subagents. No engine. | \n\nThe skills are written for Claude to read, so the SKILL.md files double as\nthe documentation. Start with `skills/chess-analysis/SKILL.md`.\n\nCopy (or symlink) the skill folders into `.claude/skills/` of your project,\nor into `~/.claude/skills/` for all projects:\n\n```\ngit clone https://github.com/brumar/chess-postmortem-skills\ncp -r chess-postmortem-skills/skills/* ~/.claude/skills/\n```\n\nThen ask Claude something like \"analyze this game: \" or \"make a video of game 010\".\n\nYou do not need to set these up by hand. Claude Code can most likely install them for you: ask it to \"install the dependencies for the chess skills\" and it will read the list below and the SKILL.md files.\n\n- Python venv with `python-chess` ,`cairosvg` (analysis), plus`pillow` ,`piper-tts` for the video. The skills assume a`.venv-chess` at the repo\nroot and create it if missing.\n- Stockfish. `scripts/get_stockfish.sh` uses`$STOCKFISH` or the one on\nPATH, else downloads the official Linux binary.\n- For video: `ffmpeg` , and a piper voice (download command in`chess-video/SKILL.md` ).\n- Optional: [whisper.cpp](https://github.com/ggml-org/whisper.cpp) for\nthink-aloud transcription.\n\nGame files live in a `chess-games/` folder at the root of the project you\nrun Claude in (`games/`, `boards/`, `video/`).\n\nEvery comment is pitched at a reader level (`audience.level` in\n`annotations.json`). For your own games, tell Claude your level once and\nmake it stick, for example in your `CLAUDE.md`:\n\n```\nMy lichess handle is <handle>. Write chess analysis for a 1800 player.\n```\n\nWithout it, the skill uses the PGN's Elo for the reviewed side and asks when that is missing or provisional.\n\n| file | stage | \n|---|---|\n| `games/010-...pgn` | input, as exported from lichess | \n| `games/010-transcript-fr.md` | think-aloud transcript, whisper.cpp, clock-aligned per ply | \n| `games/010-...-sweep.json` | per-ply Stockfish evals (depth 22) | \n| `games/010-frag-*.json` | annotation fragments returned by each investigator / the plan pause / the brief-comment pass | \n| `games/010-analysis-*.json` | engine lines each investigator discovered ( `query.py --log` sidecars) | \n| `games/010-assemble.py` ,`010-annotations.json` | fragments merged into the build spec | \n| `games/010-...-annotated.pgn` | the deliverable of stage 2 | \n| `games/010-...-viewer.html` | standalone analysis board, open it in a browser | \n| `video/storyboard-010.json` | storyboard for stage 3 | \n| `video/out-010.mp4` ,`.srt` ,`.html` | the narrated video (6:49), subtitles, and annotation viewer | \n\nTo regenerate the video, download the piper voice into\n`examples/game-010/video/voices/` and run `make_video.py` on the storyboard.\n\nMIT, except the vendored `chess.js` (BSD 2-Clause) and the cburnett piece\nset (CC BY-SA / GFDL). See `LICENSE`.", "url": "https://wpnews.pro/news/show-hn-a-claude-code-skill-to-analyze-your-chess-games", "canonical_source": "https://github.com/brumar/chess-postmortem-skills", "published_at": "2026-09-26 15:34:53+00:00", "updated_at": "2026-09-26 16:01:07.059074+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Claude Code", "Stockfish", "lichess", "whisper.cpp", "piper TTS", "chess-analysis", "chess-video"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-a-claude-code-skill-to-analyze-your-chess-games", "markdown": "https://wpnews.pro/news/show-hn-a-claude-code-skill-to-analyze-your-chess-games.md", "text": "https://wpnews.pro/news/show-hn-a-claude-code-skill-to-analyze-your-chess-games.txt", "jsonld": "https://wpnews.pro/news/show-hn-a-claude-code-skill-to-analyze-your-chess-games.jsonld"}}