HTML Explainer 的核心目标是产出一个自包含的单一 HTML 文件，用来讲解某个真实系统是如何运作的，并且内容必须扎根于仓库里的真实代码。
用途
该技能适用于需要详细、可交互地解释代码的场景：把某个子系统或流程（例如一条端到端数据流）拆解并呈现给读者。输出是一个带内联 CSS、JavaScript 和 SVG 的 .html 文件，最终消费者是用户及其同事，直接在浏览器中打开，不需要服务器，也不需要构建步骤。
主要能力
页面必须在三个深度上都能工作。
- glance（概览）：可点击的整体地图加上一段落导语。
- scan（扫读）：章节摘要、表格和图示。
- descend（深入）：带代码的可展开面板。
技能明确规定：任何关键内容不得只存在于深入层，任何笨重内容不得放在深入层之上。
在内容可信度上有两条贯穿始终的规则：
- verbatim-or-absent——每段代码片段都从仓库逐字复制并标注其 path:line 范围，否则不得出现在页面上。绝不允许凭记忆重建代码；做删节时须把来源条标记为 (abridged) 并且只整行删除。如果某个论断无法追溯到文件，则只能以纯文字陈述或直接删除。
- drill-down contract——即上述三个深度的约定。
使用方式
工作流程分为五步。
- 范围界定（Scope）：确定主题（一个子系统/服务/流程，不相关主题拆成多个页面）、受众，以及页面必须回答的问题。受众需三选一：新人需要地图和通俗导语；实现者需要扩展点和约定；审查者需要边界、不变量和依赖方向。若该主题已有导览页，则复用其范围与证据。默认问题集为：架构与所用技术及各自在代码中的位置、端到端数据流（输入到输出）、授权/租户、日志/可观测性。默认输出路径为项目仓库中的 docs/<topic>-explainer.html。
- 证据收集（Evidence pass）：证据规则位于 shared/references/grounded-evidence.md，先阅读该文件，再按定义每个子系统构建一份证据档案，包含机制、2–5 段带精确 path:line 的逐字片段、注意事项，以及来自代码注释的经验故事。
- 组装（Assemble）：把技能目录下的 assets/template.html 复制到输出路径，替换其占位槽位。需先阅读 shared/references/html-page-conventions.md（关于自包含、三个深度、转义和验证），再阅读 references/page-anatomy.md（关于每个槽位、SVG 图示机制和片段转义规则）。排序要求：整体地图在最前，每个主要方框带 onclick="jump('sec-…')" 指向真实章节 id；章节按数据流编号排序；每个 .code 块都配有 .code-src 条，标注仓库相对路径与行号；片段文本中的 &、<、> 需要转义（例如 Promise<Foo> 必须写成 Promise<Foo>）。
- 验证（Verify）：运行确定性检查：
SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>"; python3 "$SKILL_DIR/scripts/validate_explainer.py" <output-file.html>
需修复问题直到退出码为 0。若浏览器可用，则渲染文件并确认整体地图能绘制、jump() 点击能打开对应章节。 5. 交付（Deliver）：把文件发送/渲染给用户，摘要以文件路径开头，并说明如何导航（点击地图、展开面板），每个章节用一行列出，并指出任何无法目视验证的部分。
适用场景
适用于对一个真实系统的子系统或流程做详细、可交互的代码讲解，面向三类受众（新人、实现者、审查者）。默认回答的问题覆盖架构与技术位置、端到端数据流、授权/租户、日志/可观测性。默认输出到仓库的 docs/<topic>-explainer.html。
限制与注意事项
- 代码片段无 path:line 标注，是改写的危险信号，需重读文件或删除（verbatim-or-absent）。
- 机密、真实主机名、受管控/已脱敏内容：适用共享证据契约第 6 节，命名机密及其解析位置，并沿用代码库自身的脱敏方式。
- 不要让页面用增加章节数代替增加深度：6–9 个编号章节是上限，超出则合并或拆分页面。
- 若既有目标文件未被选中替换，应使用新路径或询问要更新哪个产物，并保留无关内容。
- 官方未提供的收费、价格、平台等信息，本文未作说明。