Show HN：一套用于分析棋局的 Claude Code 技能
英文标题：🔶 Show HN: A Claude Code skill to analyze your chess games
开发者 brumar 发布了一套 Claude Code 技能，可将国际象棋对局生成包含 Stockfish 验证、自然语言复盘、标注 PGN、HTML 棋盘及旁白视频的赛后分析报告。该工具还能结合玩家在对局期间录制的思考音频，通过 whisper.cpp 转写并根据 PGN 时钟将内容对齐至具体着法，从而针对玩家真实的思路进行复盘。完整处理流程约需一小时，适合希望从慢棋或快棋中深入学习的玩家，而非需要快速检查闪电战的场景。项目以 MIT 许可开源，并提供 `chess-analysis`、`chess-video`、`chess-position` 和 `chess-play` 等技能。
96.2 KB
中文
面向 Claude Code 的国际象棋赛后复盘技能
这些 Claude Code 技能可以把你的一盘国际象棋对局转化为真正读得下去的赛后复盘：用通俗语言解释你的失误，通过 Stockfish 核验，并生成整盘对局的旁白视频。
编辑：该死，这篇帖子上了 Hacker News 首页。你可以去那里参与有见地的讨论：https://news.ycombinator.com/item?id=49857528
我本应该选一盘自己没有出现重大漏招的对局，哈哈。
out-010.mp4
如果上方播放器无法加载（它需要 GitHub 登录），请直接观看 mp4 文件（10 MB）。
时长 6:49，英文旁白，带字幕。
这是一盘我的真实对局：我在 lichess 上进行的一盘 15+10 快棋（5KmlrdyT），执白，以开放式西西里对阵纳道尔夫变例，等级分约为 1700。对局期间，我用放在棋盘旁的普通录音机录下了自己用法语进行的思考过程。对局结束后，我向 Claude 提供了两样东西：lichess 链接和 mp3 文件。
Claude 使用 whisper.cpp 在本地转写音频，随后利用 PGN 中的时钟时间，将每一句话匹配到我当时正在考虑的着法。因此，当视频说“在第八回合，你问自己象应该放在 c4 还是 e2”时，那确实是我自己提出的问题，并由引擎给出回答。视频展示的一切内容（转录文本、Stockfish 全局扫描、标注 PGN、分镜脚本）都位于 examples/game-010/ 中。
Stockfish 分析会给你数字和变化路线。但它读起来并不愉快，而且经常不会告诉你 为什么：例如你的着法之后评估变成 -1.8，再给出一条你在棋盘前根本不可能找到的 12 步变化。
我意识到，Claude 可以自己驱动 Stockfish。它会向引擎提出人类会问的问题（“为什么我下的这步不行？”、“如果黑方直接吃掉会怎样？”），不断追问，直到答案说得通，然后用人类能理解的方式记录下来。而且，由于它知道我在对局期间想了什么，它可以反驳我真实的推理，而不是猜测出来的推理。分析结束后，我还可以继续针对任何局面提出自己的问题，它会在回答前先用引擎验证。
如果你符合以下情况，这个工具大概适合你：
- 你下慢棋或快棋，并希望从中学习，而不只是看评估条在哪里下降；
- 你可以接受在自己的机器上运行 Claude Code；
- 你愿意在对局期间做笔记或口述思考（可选，但这正是让结果变得有趣的原因）。
如果你只是想快速检查一盘闪电战，它大概不适合你。Lichess 或 chess.com 的分析可以在几秒钟内完成这件事。
这需要时间。 完整运行一次（全局扫描、调查、标注、视频）大约需要一小时的处理时间。请将其用于那些你认真思考过的对局，而不是你下过的每一盘棋。
提供你的思考过程。 我强烈建议你提供覆盖整盘对局的文字笔记或录音。没有这些内容时，你仍会得到不错的引擎解释；有了它们，你得到的则是对 你自己的 推理过程的复盘：哪些担忧是合理的，哪些计划是可靠的，你向自己提出了哪些问题，以及对应的答案是什么。
幻觉。 AI 仍然可能出错。每一项论断都会通过 Stockfish 检查，验证环节还会重新阅读结果，因此根据我的经验，错误很少出现。如果某些内容看起来不对，请要求 Claude 用引擎检查该局面。
- 下完一盘有充足思考时间的对局（15+10 快棋或通信棋）。
- 在对局期间录下自己的思考过程（任意手机或网页录音工具均可）。对于通信棋，我会改为按每一着记录笔记。
- 对局结束后，打开 Claude Code，说类似这样的话：“analyze this game: , here is my think-aloud recording: ”。
- 等待约一小时。我会得到一份标注 PGN 和一个独立的 HTML 分析棋盘。
- 请求生成视频：“make a video of this game”。
- 阅读、观看，然后就仍然无法理解的局面继续提问。
| skill | 功能 |
|---|---|
chess-analysis |
对每一着进行 Stockfish 全局扫描，然后启动并行的“调查员”子 Agent，向引擎提出朴素问题，直到每一个失误都得到解释。输出包括：分层标注的 PGN、独立 HTML 分析棋盘，以及每盘棋一个“计划暂停点”，从引擎分析中推导双方计划。支持处理思考录音：使用 whisper.cpp 转写，并通过 PGN 时钟与着法对齐。 |
chess-video |
根据分镜脚本生成整盘对局的旁白视频（棋盘、箭头、评估仪表、piper TTS、内嵌字幕），并附带交互式 HTML 查看器。 |
chess-position |
研究单个局面（FEN 或截图）。会先询问你想进行位置性分析还是战术分析，然后以人类可理解的方式解释计划或战术，每项论断均由 Stockfish 验证。可选生成旁白视频。示例：examples/position-carlsbad/。 |
chess-play |
通过 PGN 文件与 Claude 对弈，棋盘会渲染为 PNG 供视觉识别，并使用对抗性漏招检查子 Agent。无需引擎。 |
这些技能是为 Claude 阅读而编写的，因此 SKILL.md 文件同时也是文档。请从 skills/chess-analysis/SKILL.md 开始。
将技能文件夹复制（或创建符号链接）到项目的 .claude/skills/ 中，或者复制到 ~/.claude/skills/ 以供所有项目使用：
git clone https://github.com/brumar/chess-postmortem-skills
cp -r chess-postmortem-skills/skills/* ~/.claude/skills/
然后向 Claude 提出类似“analyze this game: ”或“make a video of game 010”的请求。
你无需手动设置这些依赖。Claude Code 很可能可以替你完成安装：要求它“install the dependencies for the chess skills”，它会读取下方列表和 SKILL.md 文件。
- 使用 Python venv，并安装
python-chess、cairosvg（分析所需），以及用于视频的pillow、piper-tts。这些技能假定仓库根目录存在.venv-chess，若不存在则会创建它。 - Stockfish。
scripts/get_stockfish.sh会使用$STOCKFISH或 PATH 中的版本；若均不存在，则下载官方 Linux 二进制文件。 - 视频所需：
ffmpeg和一个 piper 语音模型（下载命令位于chess-video/SKILL.md）。 - 可选：whisper.cpp，用于思考过程录音转写。
对局文件位于运行 Claude 的项目根目录中的 chess-games/ 文件夹内（games/、boards/、video/）。
每条评论都会按读者水平调整（annotations.json 中的 audience.level）。对于你自己的对局，告诉 Claude 一次你的水平，并让它持续遵守，例如在 CLAUDE.md 中：
My lichess handle is <handle>. Write chess analysis for a 1800 player.
如果没有设置，技能会使用 PGN 中被复盘一方的 Elo；如果 Elo 缺失或属于临时等级分，则会询问你。
| file | 阶段 |
|---|---|
games/010-...pgn |
输入文件，从 lichess 导出 |
games/010-transcript-fr.md |
思考过程转录，使用 whisper.cpp 生成，并按每半回合依据时钟对齐 |
games/010-...-sweep.json |
每半回合的 Stockfish 评估（深度 22） |
games/010-frag-*.json |
每个调查员 / 计划暂停点 / 简要评论环节返回的标注片段 |
games/010-analysis-*.json |
每名调查员发现的引擎变化路线（query.py --log 附属文件） |
games/010-assemble.py、010-annotations.json |
合并为构建规范的片段 |
games/010-...-annotated.pgn |
第 2 阶段的交付结果 |
games/010-...-viewer.html |
独立分析棋盘，可在浏览器中打开 |
video/storyboard-010.json |
第 3 阶段的视频分镜脚本 |
video/out-010.mp4、.srt、.html |
带旁白的视频（6:49）、字幕和标注查看器 |
要重新生成视频，请将 piper 语音模型下载到 examples/game-010/video/voices/，并在分镜脚本上运行 make_video.py。
MIT 许可，但内置的 chess.js（BSD 2-Clause）以及 cburnett 棋子集（CC BY-SA / GFDL）除外。详见 LICENSE。
English / 原文
Chess post-mortem skills for Claude Code
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.
Edit: Damned this hit front page of HackerNews. You can go there for insightful conversations: https://news.ycombinator.com/item?id=49857528
I should have selected a game without a massive blunder on my side ahah.
out-010.mp4
If the player above does not load (it needs a GitHub login), watch the mp4 directly (10 MB).
6:49, English narration, subtitles.
This is a real game of mine: a 15+10 rapid on lichess (5KmlrdyT), White, Open Sicilian against a Najdorf, around 1700. During the game I recorded myself thinking aloud, in French, with a plain voice recorder running next to the board. After the game I gave Claude two things: the lichess link and the mp3.
Claude transcribed the audio locally with whisper.cpp, then used the clock times in the PGN to match each sentence to the move I was deciding at that moment. So when the video says "at move eight you asked yourself whether the bishop belongs on c4 or e2", that is my own question, answered with the engine. Everything the video shows (the transcript, the Stockfish sweep, the annotated PGN, the storyboard) is in examples/game-010/.
A Stockfish analysis gives you numbers and lines. It is not fun to read, and often it does not tell you why : -1.8 after your move, and a 12-move variation you would never find at the board.
I 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.
Probably yes if:
- you play slow or rapid games and want to learn from them, not just see where the eval bar dropped;
- you are fine running Claude Code on your machine;
- you are willing to take notes or talk during the game (optional, but this is what makes the result interesting).
Probably not if you want a quick check of a blitz game. Lichess or chess.com analysis does that in seconds.
It takes time. A full run (sweep, investigations, annotations, video) takes around one hour of processing. Use it on games where you took the time to think, not on every game you play.
Give it your thoughts. I strongly recommend passing your written notes or an audio recording covering the whole game. Without them you get a good engine explanation. With them you get a review of your reasoning: which fears were justified, which plans were sound, which questions you asked yourself and what the answer was.
Hallucinations. The AI can still get something wrong. Every claim is checked against Stockfish and a verifier pass re-reads the result, so in my experience errors are rare. If something looks off, ask Claude to check that position with the engine.
- Play a game with some time to think (15+10 rapid, or correspondence).
- Record myself thinking aloud during the game (any phone or web voice recorder). For correspondence games, I write notes per move instead.
- After the game, open Claude Code and say something like: "analyze this game: , here is my think-aloud recording: ".
- Wait about an hour. I get an annotated PGN and a standalone HTML analysis board.
- Ask for the video: "make a video of this game".
- Read, watch, then ask questions about the positions I still do not understand.
| skill | what it does |
|---|---|
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. |
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. |
chess-position |
Study of a single position (FEN or screenshot). Asks first whether you want a positional or a tactical analysis, then explains the plans or the tactics in human terms, every claim checked with Stockfish. Optional narrated video. Example: examples/position-carlsbad/. |
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. |
The skills are written for Claude to read, so the SKILL.md files double as the documentation. Start with skills/chess-analysis/SKILL.md.
Copy (or symlink) the skill folders into .claude/skills/ of your project, or into ~/.claude/skills/ for all projects:
git clone https://github.com/brumar/chess-postmortem-skills
cp -r chess-postmortem-skills/skills/* ~/.claude/skills/
Then ask Claude something like "analyze this game: " or "make a video of game 010".
You 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.
- Python venv with
python-chess,cairosvg(analysis), pluspillow,piper-ttsfor the video. The skills assume a.venv-chessat the repo root and create it if missing. - Stockfish.
scripts/get_stockfish.shuses$STOCKFISHor the one on PATH, else downloads the official Linux binary. - For video:
ffmpeg, and a piper voice (download command inchess-video/SKILL.md). - Optional: whisper.cpp for think-aloud transcription.
Game files live in a chess-games/ folder at the root of the project you run Claude in (games/, boards/, video/).
Every comment is pitched at a reader level (audience.level in annotations.json). For your own games, tell Claude your level once and make it stick, for example in your CLAUDE.md:
My lichess handle is <handle>. Write chess analysis for a 1800 player.
Without it, the skill uses the PGN's Elo for the reviewed side and asks when that is missing or provisional.
| file | stage |
|---|---|
games/010-...pgn |
input, as exported from lichess |
games/010-transcript-fr.md |
think-aloud transcript, whisper.cpp, clock-aligned per ply |
games/010-...-sweep.json |
per-ply Stockfish evals (depth 22) |
games/010-frag-*.json |
annotation fragments returned by each investigator / the plan pause / the brief-comment pass |
games/010-analysis-*.json |
engine lines each investigator discovered (query.py --log sidecars) |
games/010-assemble.py, 010-annotations.json |
fragments merged into the build spec |
games/010-...-annotated.pgn |
the deliverable of stage 2 |
games/010-...-viewer.html |
standalone analysis board, open it in a browser |
video/storyboard-010.json |
storyboard for stage 3 |
video/out-010.mp4, .srt, .html |
the narrated video (6:49), subtitles, and annotation viewer |
To regenerate the video, download the piper voice into examples/game-010/video/voices/ and run make_video.py on the storyboard.
MIT, except the vendored chess.js (BSD 2-Clause) and the cburnett piece set (CC BY-SA / GFDL). See LICENSE.