book-to-skill：将游戏开发书籍蒸馏成AI Agent技能文件

每次看到 AI Agent 写游戏代码很容易遇到同一个问题通用模型的游戏开发知识太“泛”。让它写一个简单的平台跳跃 Demo 没问题一旦涉及具体引擎的项目结构、物理参数、节点组织、资源导入方式生成结果就经常是“看着像跑不起来”。不是模型能力不够而是它缺少一本书级的领域知识。这次我们来看的实践方向是 book-to-skill。核心思路很简单把一本书的内容蒸馏成一个可复用的 Skill 技能文件让 AI Agent 在游戏开发时调用这个 Skill。用这个方式Agent 不再靠模糊记忆写代码而是会按照书里的项目组织方式、脚本规范、资源管理习惯去生成内容。这篇文章会完整走一遍这个流程先解释 book-to-skill 的工作原理再讲怎么把一本游戏开发书籍蒸馏成 SKILL.md最后用 Godot 2D 平台跳跃游戏作为实战目标验证 Skill 在开发流程中的实际作用。如果你前段时间关注过 Claude Code、Codex 或 Cursor 里的 Skills 功能这类 Skill 文件本质上就是一个带 YAML 头的 Markdown 文件放在指定目录后Agent 可以根据用户请求自动加载。book-to-skill 要解决的问题就是如何从一本动辄几百页的技术书里提炼出 Agent 真正用得上的部分并组织成它容易遵循的指令结构。1. 核心能力速览能力项说明项目类型知识蒸馏 AI Agent 技能构建工作流输入内容技术书籍、官方文档、个人笔记等有结构化知识的内容输出产物SKILL.md 技能文件可被 Claude Code、Codex 等工具调用核心作用让 AI Agent 在游戏开发、代码生成等任务中遵循特定领域规则适用引擎Godot、Unity、微信小游戏等取决于蒸馏书籍和技能设计硬件门槛无特殊 GPU 要求普通笔记本即可完成蒸馏与开发显存占用不涉及本地大模型推理无需额外显存预算启动方式Skill 目录加载命令行或编辑器内触发是否支持 API取决于 Agent 工具CLI 模式下可脚本化批量调用是否支持批量任务可以Skill 文件可作为批处理指令被多次重复调用适合场景游戏开发、文档知识库、团队 AI 编程规范、课程内容复用从这些能力可以看出book-to-skill 并不是一个需要特定显卡或昂贵推理服务的项目它的价值在于把“知识资产”结构化让 AI 能被约束在某个专业范围内干活。这一点对游戏开发尤其重要因为游戏工程往往强依赖引擎版本、项目目录约定、场景组织方式等上下文信息。2. 适用场景与使用边界book-to-skill 最适合三类人。第一类是正在用 AI 辅助写游戏的人。你希望 AI 不只生成孤立脚本还能按照你的项目结构持续输出风格统一的代码比如统一用PlayerController命名角色控制脚本统一把场景资源放在res://scenes/目录统一使用某种输入映射方式。通过 Skill这些规则可以被固定下来。第二类是游戏开发学习者。我经常看到有人把一本引擎教程从头到尾读完但真正动手做项目时还是会卡在“书里明明写过但没记住”。如果把书蒸馏成 Skill开发时随时可以让 AI 按书里的思路给出建议等于给 Agent 装了一本浓缩版教材。第三类是团队维护者。一个团队如果依赖某个内部文档、编码规范或分支管理流程可以把这些内容转成团队级 Skill让所有成员的 AI 工具都遵循同一套规则。使用边界同样需要明确。book-to-skill 不适合当作“盗版书籍转换器”它蒸馏的是知识结构不是把整本书的原文复制粘贴成技能文件。生成 Skill 时应当使用自己拥有版权的内容、公开授权文档或者自行整理的笔记。很多技术书籍受版权保护未经授权抓取、传播或转售内容会带来法律风险。本文演示的方法只适合用你合法持有的材料做个人开发辅助。同时要意识到Skill 不是数据库。它不是把一本 500 页的书全部塞进去而是提炼出可执行规则和常用模式。把原文完整放进 SKILL.md 会导致上下文窗口被大量占用Agent 反而抓不住重点响应变慢输出质量下降。正确的做法是蒸馏出“怎么组织项目、怎么写脚本、怎么调参数、怎么排查错误”这类可操作指令。3. 环境准备与前置条件3.1 工具链选择在实际操作之前先确认你有哪些工具。book-to-skill 的蒸馏过程可以分成两个阶段知识提取阶段把书籍章节转换为结构化笔记这个阶段可以使用本地脚本、文本编辑器也可以让 AI 配合完成。技能封装阶段把结构化笔记写成一个 SKILL.md并放入 Agent 工具的 Skills 目录。你需要准备的工具包括工具用途备注支持 Skills 的 Agent执行 Skill 技能Claude Code、Codex、Cursor 等Python 环境文档解析、文本清洗可选用于转换 PDF/EPUBMarkdown 编辑器编写 SKILL.mdVS Code、Typora 均可游戏引擎验证 Skill 生成的工程本文以 Godot 4.x 为例源文档被蒸馏的书籍/教程/笔记必须是你合法持有版权的资料3.2 Skills 目录结构不同 Agent 工具对 Skills 目录的读取规则略有差异但通用的结构是每个 Skill 一个文件夹文件夹内必须有SKILL.md文件YAML 头里的name和description是 Agent 判断何时调用该 Skill 的主要依据。一个通用目录结构如下skills/ └── godot-2d-platformer-dev/ ├── SKILL.md ├── examples/ │ ├── platformer.gd │ └── enemy_spawner.gd └── references/ └── node_tree_cheatsheet.md把整个skills目录路径配置到你的 Agent 工具中即可。以 Claude Code 为例通常是把 Skills 放在~/.claude/skills/或项目级.claude/skills/目录下。3.3 源文档准备这里特别强调一下源文档的格式会影响蒸馏效率。PDF 需要先做文本提取EPUB 可以转换为 Markdown 或纯文本OCR 扫描版还需要额外的文字识别步骤。准备阶段先看你的书籍是什么格式然后决定是否需要写一个转换脚本。下面用一个简单的 Python 示例展示如何从 PDF 中抽取文本这个脚本只是一个基础模板需要按实际 PDF 库调整import sys from pathlib import Path try: import fitz # PyMuPDF except ImportError: print(请先安装 PyMuPDFpip install PyMuPDF) sys.exit(1) def extract_pdf_text(pdf_path: str, output_path: str) - None: pdf fitz.open(pdf_path) lines [] for page in pdf: text page.get_text() lines.append(f--- Page {page.number 1} ---) lines.append(text) Path(output_path).write_text(\n.join(lines), encodingutf-8) print(f已输出到 {output_path}) if __name__ __main__: extract_pdf_text(sys.argv[1], sys.argv[2])转换完成后先打开文本文件检查是否有乱码、分页符号残留、代码块错位等问题。这一步虽然不起眼但影响后续蒸馏质量。4. book-to-skill 蒸馏五步流程4.1 第一步拆解书籍目录建立知识地图不要直接让 AI 通读全书然后写 Skill那样既烧 Token 又容易遗漏重点。先把书籍目录拆开建立一张知识地图。以一本 Godot 2D 游戏开发书为例知识地图可以写成第一章 引擎安装与项目创建 第二章 场景与节点 第三章 脚本基础与 GDScript 第四章 物理与碰撞 第五章 摄像机与视口 第六章 UI 与 HUD 第七章 资源导入与项目管理 第八章 发布与调试这张地图的核心作用是在蒸馏时快速定位“哪些章节适合写成 Agent 可执行规则”而不是让 Agent 面面俱到。通常物理参数、节点组织、脚本骨架、项目目录约定是最有价值的部分。4.2 第二步设计 Skill 的 YAML 头SKILL.md 的 YAML 头决定了 Agent 在什么情况下调用这个技能。命名要具体描述要包含足够的触发词。如果描述太模糊Agent 可能该用的时候不用不该用的时候反复触发。--- name: godot-2d-platformer-dev description: 当用户需要开发 Godot 2D 平台跳跃游戏、编写 GDScript 脚本、组织角色场景、设置物理碰撞或调试平台跳跃机制时使用本技能。 ---这里的关键是“描述里写清楚技能边界”。我在实际项目中发现Agent 对description的依赖程度很高把能触发的场景写全比在后面正文中反复强调更有效。4.3 第三步选择性抽取而不是全文复制第三抽取哪些章节内容进 Skill要遵循“规则优先、代码优先、参数优先”的原则。从书里抽出来的内容适合成为 Skill项目目录结构约定节点组织方式物理参数推荐值常用脚本模板调试与发布流程常见坑点不适合直接进 Skill 的内容大段背景介绍和概念铺垫重复的截图说明与特定引擎版本绑定的临时命令冗长的示例玩法设计在抽取时可以保持一个临时笔记文件把每章最有操作性的段落摘出来。下面是一个笔记片段的示意第四章 物理与碰撞 - CharacterBody2D 主要用于玩家控制的角色不需要模拟完整刚体物理。 - 移动时设置 velocity 后调用 move_and_slide()。 - 跳跃高度与重力、初始 jump_velocity 的关系 h v^2 / (2g) - 常见参数move_speed300jump_velocity400gravity1200。 - 碰撞层建议分为 player、world、enemy 三层。这个阶段尽量避免让 AI 改写成“一般性建议”要保留书中的具体数值和命名习惯。Skill 的可执行性恰恰来自这些细节。4.4 第四步编写 SKILL.md 正文现在把临时笔记改写成 SKILL.md。正文部分要遵循一个原则Agent 读取后应当能直接执行不需要再向用户追问大量问题。SKILL.md 正文的结构建议# Godot 2D Platformer 开发技能 ## 项目结构 新项目建议按以下目录组织 text res:// ├── scenes/ ├── scripts/ ├── assets/ ├── ui/ └── autoload/角色控制脚本模板所有玩家控制脚本使用 CharacterBody2D基础模板如下extends CharacterBody2D export var move_speed : 300.0 export var jump_velocity : -400.0 var gravity : 1200.0 func _physics_process(delta: float) - void: if not is_on_floor(): velocity.y gravity * delta if Input.is_action_just_pressed(jump) and is_on_floor(): velocity.y jump_velocity var direction : Input.get_axis(move_left, move_right) velocity.x direction * move_speed move_and_slide()物理参数参考重力1200 到 1800根据手感调整。移动速度300 到 500。跳跃速度-400 到 -600。碰撞层约定层用途检测对象1玩家世界、敌人2世界玩家、敌人3敌人玩家、世界注意Skill 正文不是让 AI 背诵的教材而是让 AI 在生成代码时引用的操作手册。因此凡是能写成模板、参数表、规则列表的内容就不要写成散文。 ### 4.5 第五步本地校验 Skill 把 SKILL.md 放入 Skills 目录后不要急着开发游戏先做一次校验。你可以用一句很直接的测试请求验证 Skill 是否被正确加载 text 按照 godot-2d-platformer-dev 技能为一个角色创建移动与跳跃脚本。如果 Agent 输出脚本符合 Skill 里的参数约定说明加载成功。如果输出的是通用 GDScript没有使用你蒸馏出的move_speed300或gravity1200说明 Skill 没有被触发需要检查 YAML 中description的触发词是否覆盖了你的请求表达。5. 用 Skill 开发游戏实战5.1 实战目标现在进入核心环节用前面蒸馏出的 Godot 2D 平台跳跃 Skill从零生成一个小型平台跳跃游戏。目标工程包含以下要素一个可控角色支持左右移动和跳跃一个简单的平台关卡一个敌人碰到会返回起点基础 UI 显示得分这个目标不大但足以验证 Skill 是否能在多文件、多场景的项目中发挥作用。5.2 输入需求给 Agent创建项目目录后用一段自然语言向 Agent 描述需求。需要明确提到技能名或者让描述里包含能触发该技能的关键词。使用 godot-2d-platformer-dev 技能创建一个 Godot 4 项目 1. 项目根目录为 res://。 2. 按照技能中的目录结构组织 scenes、scripts、assets、ui。 3. 玩家使用 CharacterBody2D脚本参数使用技能中的推荐值。 4. 创建一个平台关卡包含地面、平台和一个敌人。 5. 添加一个得分 UI玩家跳跃到敌人头顶时加分。这里的重点是把“目录结构”“脚本参数”“节点类型”这些约束写清楚Agent 才能利用 Skill 中的规则。如果需求描述过于开放比如只说“做一个游戏”Agent 可能不会选择你的 2D 平台跳跃技能。5.3 Agent 利用 Skill 生成项目根据 Skill 中的约定Agent 通常会先生成项目骨架再逐个生成脚本文件。下面是一个符合 Skill 参数约定的角色脚本示例extends CharacterBody2D export var move_speed : 300.0 export var jump_velocity : -400.0 export var gravity : 1200.0 func _physics_process(delta: float) - void: if not is_on_floor(): velocity.y gravity * delta if Input.is_action_just_pressed(jump) and is_on_floor(): velocity.y jump_velocity var direction : Input.get_axis(move_left, move_right) velocity.x direction * move_speed move_and_slide()再生成敌人脚本时Agent 会继承节点类型约定使用 Area2D 或 CharacterBody2D 实现碰撞和判定extends Area2D export var patrol_speed : 80.0 var start_position: Vector2 var moving_right : true func _ready() - void: start_position global_position func _process(delta: float) - void: if moving_right: global_position.x patrol_speed * delta else: global_position.x - patrol_speed * delta if abs(global_position.x - start_position.x) 200: moving_right not moving_right这里你需要注意Skill 不一定直接提供敌人脚本模板但通过“碰撞层约定”和“玩家控制脚本模板”Agent 能推断出适合该项目的敌人实现风格。技能的价值是约束整体一致性而不是替代每一个具体脚本。5.4 检查生成结果与运行验证生成完所有文件后在 Godot 里打开项目检查三件事。第一场景节点结构是否合理。玩家是CharacterBody2D子节点是否包含CollisionShape2D和Sprite2D否则运行时会看到角色悬空或不显示。第二输入映射是否创建。如果项目里没有配置move_left、move_right、jump三个动作运行脚本会报错。可以手动在项目设置中添加上或者让 Agent 输出一份自动创建的说明。第三物理参数是否符合手感。Skill 中的参数是参考起点不一定每个项目都合适。如果角色跳跃太低就调大jump_velocity的绝对值如果下落太快适当降低gravity。这一步验证通过基本可以认定 Skill 已经发挥作用。你会发现 Agent 生成的代码在风格上明显更统一不再出现一个文件用snake_case、另一个文件用camelCase的现象。5.5 迭代改进 Skill开发过程中如果把某个参数调整到了一个更合适值或者总结了新的坑点随时把这些信息写回 SKILL.md。Skill 文件的价值会在多次迭代中体现出来。例如这次实战中如果发现move_and_slide()在斜坡上的表现需要单独说明就补充一个“斜坡处理”小节。## 斜坡处理 - 使用 CharacterBody2D 时velocity.x 在斜坡上会让角色卡顿。 - 可以设置 floor_max_angle 为 Math.deg_to_rad(46) 允许更陡的斜坡。 - 需要单独处理斜坡减速时使用 get_floor_normal() 计算摩擦力方向。这些内容来自实际开发经验比从书籍里抽出来的通用规则更有价值。蒸馏一本书是开始把实战经验反哺回 Skill 才是长期收益。6. 接口与批量任务展开6.1 CLI 调用 Skill大部分支持 Skills 的 Agent 工具都提供 CLI 模式适合脚本化调用。以 Claude Code 为例无头模式下可以使用类似下面的命令把任务一次性交给 Agentclaude -p 使用 godot-2d-platformer-dev 技能创建 enemies 目录并按技能中的碰撞层约定生成巡逻敌人脚本。 --allowedTools Bash,Edit,Write-p参数传入 prompt输出会直接打印到终端。这个模式很适合验证 Skill 是否生效也可以快速做批量生成。6.2 批量生成不同关卡如果你的 Skill 中包含“关卡生成规范”就可以用循环脚本批量创建多个关卡描述再交给 Agent 逐个生成。批量处理的核心是明确每个任务的差异点。可以准备一个简单的 JSON 配置描述每个关卡的关键参数[ { level: 1, theme: forest, platform_count: 8, enemy_count: 2, objective: collect 3 coins }, { level: 2, theme: cave, platform_count: 12, enemy_count: 4, objective: reach the exit portal } ]然后用一个简单的 Python 脚本循环调用 Agent CLI示例代码只展示调用思路实际要根据你使用的 Agent 命令调整import subprocess import json levels json.load(open(levels.json)) for item in levels: prompt ( f使用 godot-2d-platformer-dev 技能生成关卡 {item[level]} f主题为 {item[theme]}平台数量 {item[platform_count]} f敌人数量 {item[enemy_count]}目标是 {item[objective]}。 ) subprocess.run( [claude, -p, prompt], checkFalse, )批量任务有两个风险。第一是上下文窗口变大如果每个关卡生成的临时文件不进行清理后续任务可能受历史上下文影响。第二是输出不统一建议每个任务之间明确指定输出文件名和目录不要让 Agent 自行命名。更稳妥的做法是在 prompt 中强制要求输出路径。6.3 把 Skill 嵌入团队开发流程如果要把 Skill 用于团队协作建议放在项目级的.claude/skills/或等价目录下并纳入 Git 管理。这样团队成员克隆项目后AI 工具会自动拥有相同的技能规则。Skill 文件的变更也会进入代码评审流程可追溯、可回滚。这里有一个需要培养的习惯不要把个人习惯写进团队 Skill只放团队公认的规范。比如“敌人碰撞层固定用层 3”是团队规范可以写“双击敌人的 Sprite 会延迟 0.1 秒”是临时调试行为不要写。Skill 文件越干净Agent 遵循度越高。7. 资源占用与性能观察7.1 上下文窗口占用的估算book-to-skill 与传统 AI 模型部署不同它不占用显存但会占用 LLM 的上下文窗口。Skill 文件在 Agent 被触发时会作为指令注入到 prompt 中。如果 Skill 文件过长你会付出两个代价每次请求的输入 Token 数量增加API 费用上升。上下文剩余空间减少Agent 可能忽略用户需求中的详细信息。从实际经验看单个 Skill 文件建议控制在 3000 到 8000 字以内。如果一本书蒸馏后内容明显超过这个量建议拆成多个 Skill。例如把“物理与碰撞”单独成一个 Skill把“UI 与 HUD”单独成一个 Skill。这样 Agent 只加载当前任务需要的技能上下文压力更小。7.2 如何观察 Skills 是否生效在 CLI 模式下可以打开调试输出查看注入的 prompt 内容。如果发现 Skill 没有被注入检查文件名是否恰好为SKILL.mdYAML 头是否包含合法的name和description。另一个观察维度是响应质量。同一段需求启用 Skill 前后对比输出差异。如果差异不大说明 Skill 中的指令不够具体或者描述与用户需求不匹配。你可以尝试在 Skill 正文中增加更明确的“必须遵守”语句例如必须遵守 - 所有玩家脚本使用 CharacterBody2D不使用 RigidBody2D 控制玩家。 - 移动和跳跃必须使用 Input.get_axis 和 Input.is_action_just_pressed。 - 参数默认值为 move_speed300jump_velocity-400gravity1200。类似这种强制性语句比“建议使用”更容易被 Agent 采纳。7.3 降低上下文占用的方法如果 Skill 文件太长或者你希望减少每次请求的 Token 消耗可以采取以下方式把示例代码从 SKILL.md 移入examples/目录并在正文中引用文件名。把经常变化的内容例如发布平台清单单独写成references/release_cheatsheet.md。在 SKILL.md 中只保留决策规则和关键模板不保留长篇解释。这样能确保 Agent 只读取到精简指令需要更多细节时再顺着引用路径去查看文件。8. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 完全没提到 SkillYAML 头缺失或 description 触发词不够检查 SKILL.md 是否有正确的 YAML 头补充description加入用户常用的表达方式Skill 加载了但规则没被遵守Skill 正文过于模糊或与用户需求冲突检查正文是否包含明确的“必须遵守”清单增加强制性指令并把模板写成可直接粘贴的代码块Skill 文件太长Agent 响应慢上下文窗口被大量占用统计注入 Token 量拆分成多个 Skill精简正文GDScript 脚本报错Input.get_axis不存在没有创建输入动作查看项目设置中的 Input Map在项目设置中添加move_left、move_right、jump角色跳跃后卡在地面重力与跳跃速度参数不匹配测试参数组合增大jump_velocity绝对值或降低gravity敌人不移动敌人脚本没挂到场景节点检查场景树确认敌人节点类型和脚本挂载位置批量生成关卡时名字混乱prompt 未指定输出路径查看生成日志在 prompt 中强制指定输出文件名和目录API 费用上升明显Skill 文件过大或频繁触发查看 Token 统计拆分 Skill、减少示例数量、只保留必要规则以上排查思路同样适用于 Unity 或微信小游戏项目只要把 Skill 的引擎相关规则换成对应引擎即可。9. 最佳实践与合规建议9.1 先小后大第一次蒸馏一本书不要试图覆盖全部章节。选一个你最常用到的主题比如“角色控制与物理”先做一个小型 Skill验证流程能跑通再逐步扩展到 UI、资源管理、发布流程等主题。小 Skill 更容易维护触发也更精准。9.2 注意版权与授权book-to-skill 的知识蒸馏过程需要合法材料。使用开源文档、自行整理的笔记或已获授权的书籍内容时不存在版权问题。将受版权保护的书籍原文批量提取、传播或商用风险很高。建议的方式是从书中提炼“规则”和“参数”并将这些内容重新组织成自己的开发规范而不是保存原文章节。9.3 Skill 文件版本管理把 Skill 和你的游戏项目分开管理或者至少使用独立的 Git 仓库。游戏项目迭代频繁Skill 文件如果混在项目中被随意改动容易丢失或污染。为 Skill 单独建仓库可以给每个版本打 tag方便回溯。9.4 保留调试日志在批量任务和接口调用场景下给 Agent 命令加上日志输出把每次请求的 prompt 和响应文件保存下来。这样即使某个生成结果不理想你也能快速定位是“Skill 触发失败”还是“用户需求描述不清”。claude -p 使用 godot-2d-platformer-dev 技能生成敌人脚本 logs/generate_enemy.log 219.5 合规使用 AI 生成内容AI 生成游戏代码和资源后发布前仍要做人工审核。特别是涉及角色形象、音效素材、贴图资源时确认是否使用了有版权限制的素材。游戏发布时如果包含 AI 生成内容遵循目标平台的内容标识要求。10. 总结与后续方向book-to-skill 最值得尝试的点是它把“读书”转成了“给 AI 装备知识”的过程。你不需要读完一整本书才能做出一个像样的游戏但你需要从书里提炼出规则让 AI Agent 按规则工作。对游戏开发来说这个工作流最大的收益是代码风格统一、项目组织清晰、参数调整有据可依。最先应该验证的功能是“Skill 是否被正确触发”。不要直接开发完整游戏先做一个简单的角色控制脚本确认 Agent 输出的代码符合 Skill 中的参数约定即可。这个验证过程会暴露大多数配置问题。最容易踩的坑有三个一是直接把整本书塞进 Skill导致 Token 消耗过高二是description写得太泛Agent 不知道该在什么时候调用三是忘记更新 Skill导致生成结果与实际工程规范越走越远。如果你在这三个地方都做了控制整个工作流基本不会出大问题。后续可以继续扩展的方向包括把多个 Skill 组合成一个完整开发流程例如“游戏设计 Skill”负责生成策划文档“项目搭建 Skill”负责初始化工程“关卡生成 Skill”负责具体实现也可以把 Skill 接入自动化测试在每个脚本生成后自动运行 GDScript 内置检查减少手动作量。思路不限于游戏开发任何领域知识都可以用同样的方法蒸馏成可复用的 AI 技能。建议先挑一本你熟悉的技术书做一个 500 字起步的小 Skill跑通后再逐步扩大范围。