用途
Learning Material Writer 用于为不熟悉某个代码仓库的程序员创建或更新仓库学习材料，帮助其快速“上手”该仓库。材料输出为 docs/learning 目录下的可导航文档集。它只在用户明确要求学习材料时才使用，且默认覆盖整个仓库，同时尊重用户指定的重点、读者对象、排除项或术语。
本技能与“teach”共享教学优先级：先建立心智模型，先解释角色与边界再讲底层细节，只在确实能说明问题时使用小段代码，只在能减少解释篇幅时使用紧凑的 ASCII 图。区别在于输出形态：不是聊天中的单节课，而是 docs/learning 内的文档集。学习材料用于入门与熟悉，不得把自己呈现为仓库在实现真相、产品决策或开发政策上的权威来源。
主要能力
- 在 docs/learning 下创建或更新文件，形成层次清晰的学习文档集。
- 明确标注 docs/learning 属于入门阅读材料，不是实现行为、决策或项目政策的真相来源；在 docs/learning/INDEX.md 加入简短说明，提示读者在关心准确性或当前行为时参考更权威的来源。
- 若仓库已有合适的项目级文档表面（如 AGENTS.md、README.md、docs/INDEX.md 或其他文档索引），在需要时更新该表面，使 docs/learning 的角色同样清晰；优先在现有索引、文档角色或贡献章节加简短说明，而非新增一大段政策块；除非用户要求，否则不为此新建顶层文件。
- 向读者指向仓库中最佳的权威来源，如源代码、测试、架构文档、ADR、API 契约或产品需求。
- 构建教学地图：规划读者应先理解什么、其次什么、再次什么；按学习需要而非机械照搬源码树分组；倾向于少量强主题而非大量文档堆砌；让计划中的文件夹与文件名读起来像目录。
- 在 docs/learning 下创建清晰层级：以 docs/learning/INDEX.md 为根入口；使用无编号、描述性的目录与文件名；包含多个子页面的目录内加 INDEX.md；除非代码库确实需要，否则保持层级较浅；交叉链接父、子与相关页面。
- 按学习顺序讲解：先讲系统是什么、主要部分如何组合；再讲运行时流程、模块职责、边界与设计决策；仅当仓库复杂度足够时才深入子系统页面。沿用 teach 风格：先目的，再主流程，再关键机制，最后易混淆之处。
- 保持文档耐久可读：偏向职责、关系、不变量与取舍；避免逐文件目录（除非某“代码地图”页确需如此）；避免逐行走查；避免把大段源码复制进文档；若某理由为推断而非明示，标注为推断。
必需覆盖范围
文档集通常应覆盖以下方面，并按仓库实际情况调整：
- 系统整体目的与形态
- 代码库结构与主要目录
- 主要模块或子系统及其各自职责
- 模块之间如何交互
- 重要运行时或数据流
- 边界线：归属、API、持久化、外部集成、分层或其他接缝
- 有助于理解整体结构的关键设计决策、取舍与约束
- 新读者应尽早注意的易混淆或非显而易见之处
若某方面在仓库中并不真正存在，应省略而非强行套用模板。
拓扑规则
把文档当作一本短书，而非笔记堆砌。目录树应读起来像目录（TOC）。文件夹名应描述主题而非内部杂务。概述页放在细节页之上。仅当某主题有多个自然子页面时才拆分子目录。适合时优先使用如 system-overview、runtime-flows、module-boundaries、subsystems 或 design-decisions 等主题分组；若仓库暗示更清晰的名字，则不必强行采用这些确切名称。
好的模式示例：
docs/learning/ INDEX.md system-overview.md codebase-map.md runtime-flows/ INDEX.md request-lifecycle.md background-jobs.md subsystems/ INDEX.md auth.md billing.md design-decisions/ INDEX.md state-management.md
docs/learning/ INDEX.md product-and-architecture.md how-data-moves/ INDEX.md ingestion.md serving.md major-parts/ INDEX.md api-layer.md storage-layer.md
应避免的模式：每个源文件一页；仅镜像 src/ 而不解释这些部分为何重要的目录名；内容单薄的深层嵌套；没有索引页或阅读路径的孤立笔记堆。
写作规则
- 以快速理解为目标。
- 优先短章节、扁平项目符号与直接叙述。
- 先解释模块为何存在，再描述其如何运作。
- 说明谁拥有什么、决策发生在哪里。
- 用平实语言解释接口与接缝。
- 谨慎使用代码片段，仅当小例子能让边界或流程更易理解时使用。
- 仅当 ASCII 图能缩短解释时使用；不使用 Mermaid。
- 语气保持指导性、平和、就事论事。
- 不添加练习、测验或检查点。
- 不用通用入门建议填充页面。
页面设计
采用有助于扫读的页面形态。可按需调整章节名，但多数页面应快速回答以下部分问题：
- 这部分是做什么的
- 它位于系统的哪个位置
- 它与什么交互
- 它拥有什么
- 有哪些重要假设或不变量
- 有哪些值得了解的设计取舍或易混淆边界
好的页面开头：一段简短的定位段落；一组紧凑的职责或关系项目符号；若小图是最短的结构表达方式，则用一个小图。
根索引期望
docs/learning/INDEX.md 通常应包含：
- 该学习集用于什么
- 一句简短说明：这是入门材料，不是实现或决策的权威真相来源
- 推荐阅读路径
- 主要主题页面与目录的简短地图
- 每个链接页面的一句话描述
目录级 INDEX.md 页面应对其本地章节做同样的事。
编辑既有学习文档
若 docs/learning 已存在：
- 保留有用结构与术语，除非其妨碍清晰
- 必要时重构较弱的层级，使导航更清楚
- 合并冗余页面
- 补充缺失的索引页或交叉链接
- 在缺少或不明确时，添加或收紧“仅限入门/非真相来源”的说明
- 保持文件名稳定，除非重命名能实质提升目录效果
非目标
不要：
- 编写长篇教程或练习
- 镜像仓库中每个实现细节
- 把学习文档呈现为规范性项目政策或决策记录
- 在用户未要求时，在 docs/learning 之外创建架构文档
- 把它变成代码评审或重写计划
- 在代码不支持时推测意图
响应期望
执行工作时：
- 直接在 docs/learning 下创建或更新文件
- 当仓库级文档表面已存在时，必要时一并更新，使 docs/learning 的“仅限入门”角色明确
- 在编辑前或后简短说明所选层级
- 指出代码结构不够清晰、难以自信记录的重要空白
限制
关于收费、价格、平台支持或具体效果，资料中暂未提供。