上周我把一个叫chess-analysis的 Claude Code 技能挂到了 Show HN 上。这个项目的起因很朴素：我下了十几年棋，最近一年养成一个习惯，每盘棋结束都把 PGN 棋谱丢进本地文件夹，再用 Stockfish 批量跑一遍引擎分析，把漏算的战术、压不住的胜势、时间恐慌里的离谱昏招都标记出来。问题是这套流程的输出永远是干巴巴的bestmove和centipawn数字，我看完还得自己对着棋谱翻译成“为什么这步不好”。折腾几次之后，我决定把整个分析流水线封装成一个 Claude Code 的 skill——一个能被 Claude Code CLI 直接加载的本地技能包。它自动读取 PGN 文件、调用开源国际象棋引擎做局面评估，再把原始数据变成有上下文、有注解、甚至能指出你棋风短板的复盘报告。
这文章不是给你展示什么惊天动地的黑科技，而是想借这个实际项目，把 Agent Skill 从“听说过”讲到“能复现”。我会拆解技能包的目录结构、SKILL.md的编写规范、python-chess 与 Stockfish 的协作方式，以及我在调试过程中踩过的五个低级坑。无论你是想给 Claude Code 写自定义技能，还是单纯想优化自己的棋谱复盘流程，这篇都值得读完再动手。
1. 这个技能解决什么问题：从“跑引擎”到“读复盘”
先说痛点。传统上我们做棋局复盘，要么靠人肉摆谱，要么靠 Stockfish 跑引擎。引擎能告诉你“这步棋导致胜率从 85% 掉到 40%”，但它不会告诉你“你在这个残局里犯了典型的中局思维错误”。专业棋手看得懂数值，业余爱好者看了只会一脸懵。我想要的是一个能衔接两者的工具：引擎负责计算，大模型负责把计算结论翻译成人类能理解的复盘语言。
chess-analysis这个技能在 Claude Code 里做三件事：
- 解析棋谱：从 PGN 文件里读出处着记录，包括开局名称、双方用时、ECO 编码、最终结果。
- 调用引擎分析：对选定的局面跑 Stockfish 深度分析，输出最佳着法、评估分值、主要变例（principal variation）。
- 生成复盘报告：让 Claude 基于引擎数据写一段教练风格的点评，指出关键转折点、漏算的战术、以及可能存在的思路问题。
这个设计解决了我的核心烦扰：以前跑完引擎还要自己对着 JSON 数据脑补，现在一句话就能获得带上下文的复盘。而且因为技能是本地执行的，PGN 文件不用上传到任何云端，全程在自己电脑上跑，隐私上也安心得多。
适合谁来参考？两类人。第一类是 Claude Code 的进阶用户，想弄明白自定义 skill 到底怎么写、怎么调试、怎么跟外部程序协作。第二类是有一定棋龄的业余棋手，平时用 Stockfish 分析但总觉得差点意思，想借助 LLM 获得更贴近人类的复盘视角。当然，如果你两个身份都占了，那这个项目真的是为你准备的。
2. 拆解 Agent Skill：Claude Code 技能的真实加载方式
在动手写代码之前，得先厘清一个概念：Claude Code 里的 skill 到底是什么？我用一句大白话解释——它是一个“按需加载的说明书+工具箱”组合，本质是一个目录，目录里有一个SKILL.md文件，外加任意数量的辅助脚本、模板、参考文档。当用户提问触发技能描述时，Claude Code 会把SKILL.md里的指令注入到上下文，并允许技能调用指定的工具或脚本。
它和常见的 CLI 脚本最大的区别在于：CLI 脚本是“你主动跑它”，skill 是“AI 判断该用它时自动调用”。这一点非常像函数按需加载，只不过加载的是一整套工作流。比如你直接运行python analyze_pgn.py，得到的是原始 JSON；而让 Claude Code 加载chess-analysis技能，它会把 JSON 翻译成一篇有教练口吻的分析报告，还能回答你跟着追问的“那下一步呢”。
这里必须提一下技能目录的加载规则。Claude Code 会扫描几个固定位置：
| 路径 | 作用域 | 说明 |
|---|---|---|
~/.claude/skills/ | 用户级 | 所有项目都能用，适合通用技能 |
.claude/skills/ | 项目级 | 只对当前项目生效，适合定制流程 |
.claude/skills/的子目录 | 项目级 | 可以按团队或模块拆分 |
把技能放在用户级目录是最省心的做法。我的chess-analysis就放在~/.claude/skills/chess-analysis/下，这样在任何目录打开 Claude Code 都能直接调用。
SKILL.md是整个技能包的入口。Claude Code 读取它来决定什么时候加载、加载后该干什么。文件头部有一段 YAML frontmatter，包含name、description、allowed-tools这些关键字段。description尤其重要，它是 AI 判断“这个问题是否该用这个技能”的匹配依据。写得太泛，任何棋类问题都会触发它；写得太窄，真正需要时又不会被调用。这是个需要在实践中反复调节的平衡点。
还有一点值得注意：Anthropic 官方文档里提到过一个disable-model-invocation选项，设为true后，技能不会因为描述匹配自动触发，只能由用户显式“召唤”。我一开始用默认的自动触发模式，结果在分析非棋谱文件时 Claude 也频繁想加载技能，浪费了不少 token。后来干脆把自动触发关掉，需要用的时候直接在提示词里写“用 chess-analysis 技能分析这个棋谱”，反而更清爽。如果你希望技能在特定场景下被动等待用户指令，这个开关值得优先配置。
3. 搭一个能跑的技能包：目录、SKILL.md 与标注规范
接下来进入实操。先看我最终版的技能目录结构，然后逐个文件解释为什么这么放。
~/.claude/skills/chess-analysis/ ├── SKILL.md ├── scripts/ │ ├── analyze_game.py │ ├── detect_tactics.py │ └── requirements.txt └── templates/ └── report_template.mdSKILL.md是入口文件，Claude Code 首先读它。scripts/存放实际干活的 Python 脚本，templates/放报告模板。目录结构的核心原则是：把需要动脑的逻辑写进脚本，把需要调校的措辞写进 SKILL.md 指令。这样你调整报告风格时不用碰代码，改代码时也不用担心破坏提示词。
下面是SKILL.md的简化版，标注了关键字段：
--- name: chess-analysis description: 分析国际象棋棋谱（.pgn 文件），调用 Stockfish 进行局面评估，输出结构化复盘报告。适用于用户提供 PGN 文件、棋谱路径，或要求解释某步棋好坏、查找漏算战术等场景。 allowed-tools: bash, Read, Write, Edit disable-model-invocation: true metadata: version: 0.1.0 --- <!-- 使用本技能时必须按以下步骤执行，不要跳过 --> 1. 如果用户只给了棋谱文本，先将其保存为临时 .pgn 文件。 2. 运行 `python scripts/analyze_game.py <pgn_path>` 获取 JSON 分析结果。 3. 如果 JSON 中包含 `tactics` 字段，继续运行 `python scripts/detect_tactics.py <pgn_path> --move <move_number>` 深入检测。 4. 把 JSON 数据映射到 templates/report_template.md，生成复盘报告。 5. 输出报告时保留引擎数值，但需用自然语言解释每个数值的业务含义。 ## 输出格式要求 - 开局阶段：简要说明开局名称与变例走向。 - 中局阶段：列出关键转折点，写明引擎评估变化。 - 残局阶段：指出决定性失误或精确胜法。 - 战术漏算：用“当时你走 X，错过了 Y”的句式描述。 ## Suggestions - 当用户说“这步棋好吗”“为什么走这里”时，优先分析当前局面。 - 当用户说“复盘整盘”时，按顺序输出全盘分析。 - 如果 Stockfish 未安装，提示用户安装，并提供 brew 安装命令。看到## Suggestions这一段了吗？这是 Claude Code 技能规范里很有特色的设计，它直接在技能文档里给 AI 提供行为建议，告诉模型用户用什么话术时会对应走哪条分支。以前写提示词是用自然语言埋在正文里，现在Suggestions变成了一个显式区块，让意图匹配更稳定。
但光有SKILL.md还不够。真正干活的还是scripts/analyze_game.py。这个脚本读取 PGN、调用引擎、输出 JSON。它必须写得让 AI 能轻松解析——因为 Claude Code 是通过 bash 工具运行脚本的，它只能通过标准输出拿到结果。如果脚本输出乱七八糟的调试信息，AI 就会误读。
我在脚本里特意定义一个 JSON 输出协议，结构固定成下面这样：
{ "pgn": "1. e4 e5 2. Nf3 Nc6 ...", "opening": "Italian Game", "declined_advantage": [ { "move_number": 17, "side": "white", "played": "Nxd4", "best": "Qb3", "eval_before": 0.8, "eval_after": -0.3, "message": "白方主动交换后，黑方获得反击机会" } ], "final_eval": { "white": 3.2, "black": -5.1, "result": "白胜" } }这个结构有四个要点：opening方便报告首段直接引用；declined_advantage是核心数据，记录每一步“评估下滑”的着法；final_eval用于结尾；整个输出只有 JSON，没有日志。Claude Code 拿到 JSON 后，按SKILL.md的指示生成报告——它不需要理解 JSON 后面有没有隐藏信息，因为它只需要按字段填模板。
4. 核心分析脚本：用 python-chess 串起 PGN 和 Stockfish
脚本技术栈选得相当轻：python-chess 负责解析棋谱，Stockfish 负责引擎计算，标准库subprocess负责中间通信。为什么不用 C-chess 引擎的 Python 封装？因为 python-chess 本身就带有engine模块，可以很方便地启动 UCI 引擎并控制搜索深度，没必要多引入一层依赖。
先看依赖安装，requirements.txt里只有两行：
python-chess==1.999Stockfish 不需要 pip 安装，它是个独立可执行文件，装好之后在SKILL.md里让用户通过包管理器装就行：
# macOS brew install stockfish # Ubuntu/Debian apt install stockfish这里我踩过一个坑：早期版本的脚本里我把 Stockfish 路径硬编码成/usr/local/bin/stockfish，结果别人的机器上引擎在别的位置，直接崩。后来改成先读环境变量，找不到就用shutil.which("stockfish")自动探测。
analyze_game.py的核心逻辑可以拆成四步：
- 载入对局：用
chess.pgn.read_game()解析 PGN 文件。 - 逐步评估：遍历棋谱里的每一步，每走一步就获取当前局面，然后调用引擎计算。
- 记录偏差：对比刚走出的实际着法和引擎推荐的最佳着法，计算评估分差。
- 输出 JSON：把关键数据整合成结构化文件。
逐步评估的代码大致长这样：
import chess import chess.pgn import chess.engine def analyze_game(pgn_path, engine_path, depth=18): game = read_pgn(pgn_path) board = game.board() engine = chess.engine.SimpleEngine.popen_uci(engine_path) declined = [] for move_number, node in enumerate(game.mainline(), start=1): played_move = node.move info = engine.analyse(board, chess.engine.Limit(depth=depth)) best_move = info.get("pv", [])[0] if "pv" in info else None best_score = info["score"].pov(chess.WHITE).score(mate_score=10000) board.push(played_move) # 走完实际着法后再评估一遍，看分数变化 info_after = engine.analyse(board, chess.engine.Limit(depth=depth)) score_after = info_after["score"].pov(chess.WHITE).score(mate_score=10000) if best_move and played_move != best_move and score_after < best_score - 50: declined.append({ "move_number": move_number, "side": "white" if board.turn == chess.BLACK else "black", "played": board.san(played_move), "best": board.san(best_move) if best_move else "unknown", "eval_before": best_score / 100, "eval_after": score_after / 100, "message": "实际着法比引擎最佳着法少收益约 {} 分".format((best_score - score_after) / 100) }) return {"opening": game.headers.get("Opening", ""), "declined_advantage": declined}这里面最容易出错的是side字段。我在代码里用board.turn判断是谁走完之后轮到谁走——因为board.push(played_move)之后，board.turn已经翻转了，所以要反过来判断实际走子方。这个问题调了我将近一个小时，排查的时候一直在想“为什么黑棋的失误全被标成白棋”。
还有score.pov(chess.WHITE)这个 API。一个新手常掉进的坑是直接用info["score"].white()之类的写法，但 python-chess 的Score对象区分相对分和绝对分，必须指定视角方向。这里的pov是 point of view 的缩写，指定从白方视角返回数值。如果你不指定，某些局面下黑方明明占优，数值却显示为负数，报告就全反了。
detect_tactics.py是我后加的增强功能。它用浅层搜索（depth=12）快速扫描整盘棋，判断是否存在可以一步吃子的战术组合。原理很简单：如果引擎在某个深度下给出的主变例里包含连续将军、强制吃后、双重攻击这类模式，就把对应步数标记为“战术机会”。这个脚本不用跑全深度，所以整体速度和analyze_game.py完全不在一个量级——全盘 40 步棋，深度 18 大约要 20 秒，而战术检测 3 秒内跑完。
5. 让 Claude Code 真正用起来：触发描述、调试命令与实战演示
技能包建好之后，最兴奋也最容易翻车的环节是“验证 AI 能不能按预期调用”。我最初把它放在~/.claude/skills/下，激动地写了条提示语：“分析这个棋谱”，结果 Claude 完全没搭理技能，反而自己生成了大段泛泛而谈的棋理分析，一个引擎数值都没有。原因就是description写得太像散文，AI 匹配度太低。
解决方式很直接：把description改成强触发型的话术，让它覆盖各种用户可能输入的自然语言表达。
description: 当用户提供国际象棋棋谱（.pgn 文件路径或文本）、要求分析对局、复盘失误、解释具体棋步优劣，或询问引擎评估结果时，必须调用本技能。改完之后，在项目目录里重新加载技能，再输入“帮我分析这盘棋”：
> 帮我分析这盘棋 > > 好的，我先找到棋谱文件路径，然后调用 chess-analysis 技能进行分析。 > [读取 ~/games/2024-09-15.pgn] > [运行 python scripts/analyze_game.py ...] > [运行 python scripts/detect_tactics.py ...] > > 这是一盘意大利开局（ECO C50）的对局，白方在第 14 步 Nxd4 出现重大评估下滑： > 引擎最佳着法为 Qb3，保持约 +0.8 分的优势。实际走 Nxd4 后，黑方通过 Bb4+ 获得反击， > 局势逆转至 -0.3。从这一手开始，白方整盘再也没有拿回主动权。看到没？Claude 会先读取文件、再调用脚本，最后把 JSON 数据组织成回话回复。整个流程有板有眼，而不是停留在“我看看棋谱然后凭感觉说两句”的状态。
调试阶段有几个命令/操作比较有用：
| 操作 | 用途 |
|---|---|
/skill斜杠命令 | 查看当前项目已加载哪些技能 |
claude --debug对话模式 | 打印上下文中注入的技能指令，确认 SKILL.md 是否真的被读取 |
ls ~/.claude/skills/ | 确认目录结构存在，且路径拼写无误 |
python scripts/analyze_game.py test.pgn | 脱离 Claude Code 直接测脚本，排查代码问题 |
--debug模式是我最推荐的排查手段。它会把“系统加载了哪些文件、注入了哪些指令”展示出来。如果技能没被加载，你一眼就能看到是不是路径不对；如果加载了但没触发，那就是description写得太菜。
还有一个非常关键的体验优化：如果技能脚本需要接收的参数很多，别指望用户每次手动输入完整路径。我在SKILL.md里明确写了“如果用户提供的 PGN 是文本而非路径，先用 Write 工具保存为临时文件，再传给脚本”。这样用户只需要粘贴 FEN 或 PGN 文本，Claude 自己会处理文件生命周期。
6. 踩坑实录：我修过的五个低级错误
这部分我觉得比前面的技术细节更值钱。每个坑都是真金白银换来的调试时间，分享出来能让你少走不少弯路。
坑一：description 写得太像博客文章导致触发失败。脚本写得再好，AI 不加载技能就等于白干。这不是脚本 bug，而是description匹配逻辑的问题。我的经验是：description里应该直接列出“用户说哪些话你可以用我”，而不是描述“我是做什么的”。把“分析国际象棋棋谱并调用 Stockfish 生成复盘”改成“当用户提供.pgn文件或要求复盘棋局时使用”，触发率肉眼可见地提升。
坑二：脚本用绝对路径/硬编码路径导致别人环境跑不了。我早期的SKILL.md里写的是python /Users/myname/.claude/skills/chess-analysis/scripts/analyze_game.py，在共享给朋友时直接运行失败。后来全部改成相对路径写法python scripts/analyze_game.py，并假设执行目录是技能目录本身。为了让这个假设成立，我在SKILL.md里加了一句“第一步先 cd 到技能目录”，这样无论用户在哪个项目路径下打开 Claude Code，脚本都能稳定执行。
坑三：yaml frontmatter 里的冒号没加引号导致解析失败。SKILL.md的 frontmatter 是 YAML 格式，如果你在 description 里写了英文冒号，比如“分析棋谱: 基于...”，YAML 解析器会把整行截断。不要问我是怎么发现的。在 openAI 的 Markdown 世界里这不是问题，但在 YAML 里，值里的冒号后面必须跟空格或加引号。我把所有 description 的值都套上了双引号，一劳永逸。
坑四：误把引擎分析当“标准答案”。Stockfish 分析结果不是上帝。深度不同的分析，对同一个局面可能给出完全不同的评级。我在SKILL.md里专门写了“分析输出必须标注搜索深度，如果深度小于 16，需要提示用户当前结果可信度有限”。这样报告末尾会自动加一句“该分析基于深度 18 的搜索，结论仅供参考”。这份“免责声明”不光在棋理上更严谨，也避免用户拿一个浅层搜索的结果去跟别人对喷。
坑五：没考虑 PGN 文件编码与乱码问题。很多棋谱是从网上复制的，可能带 BOM 头、Windows 换行符，甚至中文注释放的是 UTF-8 BOM。read_game()能解析大部分 PGN，但对乱码棋谱会出现诡异的报错。解决方式是在脚本开头做一次编码检测与清理：
raw_text = open(pgn_path, 'rb').read().decode('utf-8-sig') raw_text = raw_text.replace('\r\n', '\n')这步看起来不起眼，但能减少三分之一的无故报错。
7. 复盘效果对比与后续扩展方向
把技能挂到 Show HN 之后，不少网友按着 README 跑了一遍，反馈集中在两点：一是“AI 输出比裸引擎数据舒服多了”，二是“居然能从棋谱里读出棋风特征”。这个反馈跟我的感受高度一致。我自己的使用体验是：以前跑完 Stockfish 要花二十分钟整理复盘笔记，现在一条命令生成初稿，我只需要校对几个关键转折点。更重要的是，这个技能把分析从“数值驱动”提升到了“概念驱动”层面——它不再只说“e4 比 c4 好 0.5 分”，而是说“你在这个封闭局面里忽视了白格象的价值”。
再往后扩展的方向，我目前列了三件事：
- 接入 Lichess API：自动拉取最近对局，然后跑技能批量复盘，省去手动保存 PGN 的步骤。
- 开局树可视化：在 JSON 里补上开局变例路径，让 Claude 生成 ASCII 棋谱树或导出可分享链接。
- 多模型支持：把 Stockfish 换成
lc0或其他神经网络引擎，对比不同引擎对同一局面的判断分歧。
这些扩展其实都在“Skill + 外部程序”的框架里，不需要推翻现有设计，只要在SKILL.md里增加新的步骤指令，在scripts/下新增对应脚本即可。我个人对第三项最感兴趣，因为神经引擎和传统引擎的评估差异恰好能揭示一些“纯计算式盲区”。
最后再分享一个经验：这类个人复盘技能最容易翻车的不是技术，而是你对“分析深度”的预期管理。Stockfish 在深度 18 以上才有较高准确度，但那意味着更长的等待时间和更高的 CPU 占用。我建议技能默认跑深度 14~16，够用且速度快，只有用户明确要求“深度分析”时才上升到 20。这个平衡点在SKILL.md里写清楚，比你事后反复解释要省心得多。
