技术学习文档写作 Skill
本 skill 指导如何写高质量、结构清晰、内容详细的技术学习文档（markdown 格式），适用于深度学习、机器学习、算法原理等技术主题。风格参考：激活函数文档、归一化方法文档。
核心目标：确保文档内容全面、及时反映技术最新发展，避免遗漏重要的新兴技术和实践。
核心写作流程
Step 1：信息收集
如果用户提供了参考文章 URL，先获取原文内容，然后：
- 1. 识别原文覆盖的知识点
- 获取当前系统时间,找出原文的错误、缺失、过时的内容
- 结合自身知识补充原文没有的重要内容，特别是最新的技术发展和实践
重要原则：不是"翻译"原文，而是以原文为基础，用自己的理解重写和扩充，确保内容的全面性和时效性。
特别注意：对于技术领域的文档，要重点关注近 3-5 年内的重要进展，如大模型中使用的 RMSNorm、SwiGLU 等新兴技术。
Step 1.5：穷举知识点 Checklist（⚠️ 强制步骤，不可跳过）
这是防止内容遗漏的核心机制。 过去的教训：直接进入写作模式会导致「写作驱动」而非「规划驱动」，靠「想到什么写什么」会遗漏非显眼但重要的技术点（如 MMR、RAG-Fusion、Semantic Cache 等）。
在动笔之前，必须先完成以下 3 个动作：
动作 1：按维度分类，穷举所有候选技术点
对文档主题，按照以下维度系统扫描，列出所有相关技术点：
CODEBLOCK0
动作 2：参照权威来源交叉验证，防止遗漏：
- - 主流框架文档的 API/模块目录（最完整的技术地图，如 LangChain Retrievers 文档）
- 最新 Survey 论文的技术分类表
- 相关 GitHub Awesome 列表
动作 3：将所有技术点组织为带复选框的 Checklist
CODEBLOCK1
完成 Checklist 后，对照着写文档，每完成一项打勾。 最终检查未打勾的项是否有意跳过还是遗漏。
Step 2：确定文档结构
每篇技术文档必须包含以下模块（按需取舍）：
通用结构（算法/框架类）：
CODEBLOCK2
命令行工具专属结构（⚠️ 如文档主题是 CLI 工具/命令行程序，必须额外包含参数完整索引章节）：
CODEBLOCK3
判断标准：文档主题涉及命令行工具（如 ruff、curl、git、uv、docker、kubectl 等）时，必须包含「参数完整索引」章节作为倒数第二章节。
工具/框架类专属结构（⚠️ 如文档主题是有配置项的工具/框架，必须包含环境变量章节）：
判断标准：文档主题涉及有环境变量支持的工具/框架（如 uv、docker、node、python、git 等）时，必须包含「环境变量」章节，完整列出所有支持的环境变量。
环境变量章节规范：
- - 位置：放在「安装与配置」章节内，或作为独立章节（配置后、实战案例前）
- 分组：按功能分组（如「路径/目录」「网络/代理」「认证」「行为控制」等）
- 格式：每组一张 3 列表格
变量名 | 说明 | 示例/默认值，重要变量标注加入版本 - 完整性：必须覆盖官方文档的全部环境变量，不可只列「常用」的几个
- 弃用标注：已弃用的变量须注明 ⚠️ 已弃用及替代变量
- 外部变量：除工具自身定义的变量外，还需列出工具读取的外部系统变量（如代理、TLS 证书等）
CODEBLOCK4 bash
示例注释
TOOL_VAR=value tool command
CODEBLOCK5
Step 3：写各方法详解
每个方法/概念的详解必须包含：
- - 论文出处：作者、机构、年份、论文名
- 提出动机：解决什么问题（why）
- 数学定义：完整公式（LaTeX 格式）
- 导数 / 梯度：反向传播必要信息
- 直觉解释：用类比或图示帮助理解（why it works）
- 优点表格：结构化列出
- 缺点表格：结构化列出，包含已知的反驳/修正
- 适用场景：具体的任务、架构、数据类型
- 代码示例：可运行的代码片段
Step 4：补充原文没有的视角
优先添加以下高价值内容：
- 1. 统一理论框架：如"所有归一化方法的本质区别是在哪个维度做统计"
- 历史演进脉络：用时间线梳理技术发展，突出技术迭代的逻辑
- 已被推翻的叙事：如"BN 有效不是因为解决了 ICS，而是平滑了损失曲面"
- 现代实践：最新的大模型 / SOTA 方法在用什么（如 RMSNorm、SwiGLU、LayerNorm 的变体等）
- 新兴技术覆盖：重点关注近 3-5 年内提出的重要技术，确保文档反映技术前沿
- 跨领域应用：不同领域（如 NLP、CV、生成模型）中归一化方法的选择差异
- 常见陷阱：实践中容易踩的坑（如 PyTorch BN 的 momentum 定义与数学相反）
- 决策树：帮助读者快速找到适合自己场景的方法
Step 5：写综合对比表
必须包含横向对比表，列出：
快速对比 |
| 关键特性（布尔值）| 一目了然 |
| 计算效率（星级）| 相对成本 |
| 主要应用场景 | 实用导向 |
Step 6：分步输出（⚠️ 强制步骤）
对于大型技术文档（预计超过 500 行 / 5 个以上章节），必须采用分步输出策略：
- 1. 建立 todo list，将文档拆分为 5~8 个 Part，每个 Part 对应 1~2 个章节
- 每次只输出一个 Part，完成后立即继续下一个 Part，无需等待用户催促
- 自动推进：每个 Part 完成后，标记 todo 为 completed，立即开始下一个
- 告知进度：在每个 Part 开头说明"当前是第 X/N 部分"
原因：一次性生成过长内容容易截断、遗漏章节、丢失上下文。分步输出确保每部分质量，也让用户实时看到进展。
- 5. 结构完整性校验（⚠️ 强制）：所有 Part 写完后，执行以下命令验证章节结构：
grep -n "^## " 文档文件名.md
确认输出中章节编号
从 1 开始连续递增，无跳号、无缺失。若发现如「第3章后直接是第8章」的跳号，必须立即补全缺失章节，再进行后续输出。
Step 7：完成后遗漏自检（⚠️ 强制步骤）
文档全部写完后，必须执行一次遗漏自检，步骤如下：
- 1. 列出文档现有的所有章节/技术点（
grep "^### \|^####" 扫描） - 重新过一遍 Step 1.5 的 Checklist，逐项确认是否已覆盖
- 重点核查容易遗漏的维度：
- 工程优化类（缓存、增量更新、可观测性）
- 多样性/效率类（与主流精度类方向不同）
- 新兴/小众但重要的技术（近 1~2 年新提出）
- 4. 若发现遗漏，立即补充到对应章节
教训：本规则来自实际 RAG 文档写作经验——初版遗漏了 MMR、RAG-Fusion、Semantic Cache、Multi-Vector Index、ColBERT、LLMLingua 等多项重要技术，均在事后检查中发现补充。
格式规范
数学公式
- - 所有公式使用 LaTeX 格式
- 行内公式： INLINECODE2
- 块级公式： INLINECODE3
- 必须给出导数/梯度公式（反向传播需要）
- 重要变量要注解其含义
CODEBLOCK7
代码示例
- - 使用 Python / PyTorch（深度学习场景）
- 代码要可运行，包含必要的 import
- 加中文注释
- 示例要体现实际使用场景，而非只是 API 调用
CODEBLOCK8
ASCII 图示
对于维度关系、架构结构，使用 ASCII 图增强可视化：
CODEBLOCK9
表格规范
优缺点用结构化表格，不用列表：
CODEBLOCK10
参数完整索引规范（CLI 工具文档专用）
当文档主题为命令行工具时，倒数第二章节必须是「参数完整索引」，按功能分组，每个分组一张 4 列表格。
列顺序： INLINECODE4
格式要求：
- - 无短参数的行，短参数列留空（不写
— 或 /） - 示例列必须是可直接运行的完整命令片段
- 同一子命令的参数按「修复/输出/规则选择/文件选择/其他」等功能子分组，用
#### 小标题分隔 - 子命令本身单独列一张「子命令一览」表，包含「子命令 / 说明 / 是否修改文件 / 示例」4 列
标准模板：
CODEBLOCK11
参考示例：见 zwy/stats/py_base/002_doc_ruff.md 第 9 章、zwy/stats/shell/004_doc_curl_wget_shell.md 第 10 章。
引用、警告块
用 blockquote 标注重要修正或补充：
CODEBLOCK12
质量检查清单
写完文档后，获取当前系统时间,仔细检查文档，简单梳理结构，看看是否有过时内容，遗漏内容和改进的地方,未解释的缩写或名词,并进行改进。
然后逐项确认：
【分步输出检查（Step 6 相关）】
- - [ ] 大型文档已建立 todo list 并分 Part 输出
- [ ] 每个 Part 完成后立即自动继续下一 Part，未等待用户催促
- [ ] 用
grep -n "^## " 扫描最终文件，验证章节编号从 1 开始连续递增，无跳号、无缺失
【完成后遗漏自检（Step 7 相关）】
- - [ ] 已用
grep 扫描当前文档所有章节，重新过 Checklist - [ ] 已重点核查「工程优化类」是否有遗漏
- [ ] 已重点核查「多样性/效率类」是否有遗漏
- [ ] 已重点核查「近 1~2 年新技术」是否有遗漏
【防遗漏检查（Step 1.5 相关）】
- - [ ] 写作前已完成维度化穷举 Checklist（Step 1.5）
- [ ] 已对照框架文档/Survey 论文的模块目录交叉验证
- [ ] Checklist 中所有条目均已有意决定（写入文档 or 明确标注跳过原因）
- [ ] 检查是否遗漏「工程优化类」技术（如缓存、增量更新等，常被算法类掩盖）
- [ ] 检查是否遗漏「多样性/效率类」技术（与主流精度类方向不同，易被忽视）
【内容质量检查】
- - [ ] 每个方法都有完整的数学公式（含导数）
- [ ] 每个方法都有代码示例（可运行）
- [ ] 包含综合对比表
- [ ] 包含选择指南/决策树
- [ ] 补充了原文缺失的重要方法（如 RMSNorm、SwiGLU 等现代方法）
- [ ] 重点覆盖了近 3-5 年内的重要技术进展
- [ ] 指出了原文的错误或过时信息
- [ ] 有直觉解释（不只是公式堆砌）
- [ ] 提到了实际使用中的陷阱
- [ ] 参考了最新的 SOTA 实践
- [ ] 考虑了跨领域应用的差异
【CLI 工具文档专项检查】
- - [ ] 文档主题是 CLI 工具时，已包含参数完整索引章节（倒数第二章）
- [ ] 参数索引表列顺序为「短参数 / 长参数 / 说明 / 示例」
- [ ] 无短参数的行，短参数列留空（不写
—） - [ ] 每行示例列为可直接运行的命令片段
- [ ] 参数按功能分组，用
#### 小标题分隔（修复/输出/规则选择/文件/其他） - [ ] 包含子命令一览表（含「是否修改文件」列）
【环境变量章节检查（有环境变量支持的工具/框架类文档专用）】
- - [ ] 已包含环境变量完整列表章节（不仅仅是「常用」几个）
- [ ] 环境变量按功能分组，每组一张 3 列表格
- [ ] 已弃用的变量已标注 ⚠️ 并注明替代变量
- [ ] 列出了工具读取的外部系统变量（代理、TLS 证书、认证 token 等）
- [ ] 包含使用示例小节（至少 5 个实用场景）
- [ ] 变量来源于官方文档，而非仅凭记忆列举（关键变量需标注加入版本）
参考示例
详见 references/ 目录：
- -
references/activation-functions-example.md — 激活函数文档节选示例 - INLINECODE16 — 归一化文档节选示例
技术学习文档写作 Skill
本 skill 指导如何写高质量、结构清晰、内容详细的技术学习文档（markdown 格式），适用于深度学习、机器学习、算法原理等技术主题。风格参考：激活函数文档、归一化方法文档。
核心目标：确保文档内容全面、及时反映技术最新发展，避免遗漏重要的新兴技术和实践。
核心写作流程
Step 1：信息收集
如果用户提供了参考文章 URL，先获取原文内容，然后：
- 1. 识别原文覆盖的知识点
- 获取当前系统时间，找出原文的错误、缺失、过时的内容
- 结合自身知识补充原文没有的重要内容，特别是最新的技术发展和实践
重要原则：不是翻译原文，而是以原文为基础，用自己的理解重写和扩充，确保内容的全面性和时效性。
特别注意：对于技术领域的文档，要重点关注近 3-5 年内的重要进展，如大模型中使用的 RMSNorm、SwiGLU 等新兴技术。
Step 1.5：穷举知识点 Checklist（⚠️ 强制步骤，不可跳过）
这是防止内容遗漏的核心机制。 过去的教训：直接进入写作模式会导致「写作驱动」而非「规划驱动」，靠「想到什么写什么」会遗漏非显眼但重要的技术点（如 MMR、RAG-Fusion、Semantic Cache 等）。
在动笔之前，必须先完成以下 3 个动作：
动作 1：按维度分类，穷举所有候选技术点
对文档主题，按照以下维度系统扫描，列出所有相关技术点：
维度扫描框架（根据主题调整）：
- - 算法/方法类：基础方法 + 变体 + 新兴方法
- 工程实现类：库/框架 + 工具 + 部署
- 评估/对比类：指标 + 基准测试 + 对比维度
- 优化/改进类：性能优化 + 成本优化 + 质量优化
- 生态/周边类：相关工具 + 集成方案
动作 2：参照权威来源交叉验证，防止遗漏：
- - 主流框架文档的 API/模块目录（最完整的技术地图，如 LangChain Retrievers 文档）
- 最新 Survey 论文的技术分类表
- 相关 GitHub Awesome 列表
动作 3：将所有技术点组织为带复选框的 Checklist
markdown
示例（RAG 主题）：
【分块策略】
□ 固定字符分块
□ 递归字符分块
□ Token 分块
□ 语义分块
□ 父文档检索
□ 命题分块 ← 容易遗漏（偏论文，不如框架API显眼）
【检索方式】
□ 纯向量检索
□ BM25 关键词检索
□ 混合检索 + RRF
□ MMR 多样性检索 ← 容易遗漏（解决多样性，方向与精度类不同）
□ Metadata Filtering ← 容易遗漏（工程技巧，不像算法显眼）
【查询增强】
□ Multi-Query
□ RAG-Fusion ← 容易遗漏（与 Multi-Query 相似，常被合并忽视）
□ HyDE
□ Step-Back Prompting
【工程优化】
□ Semantic Cache ← 容易遗漏（工程优化类，非核心算法）
□ 增量更新策略
完成 Checklist 后，对照着写文档，每完成一项打勾。 最终检查未打勾的项是否有意跳过还是遗漏。
Step 2：确定文档结构
每篇技术文档必须包含以下模块（按需取舍）：
通用结构（算法/框架类）：
- 1. 引言（为什么需要 XXX）
- 统一视角 / 核心框架（用一个视角统一理解所有方法）
- 各方法详解（每个方法独立一节）
- 方法对比表（综合横向比较）
- 选择指南 / 决策树（实用建议）
- 代码示例（PyTorch / Python）
- 参考资料
命令行工具专属结构（⚠️ 如文档主题是 CLI 工具/命令行程序，必须额外包含参数完整索引章节）：
- 1. 引言（工具简介、与其他工具对比、安装）
- 核心概念（命令/子命令体系、配置文件等）
- 各子命令详解（每个子命令独立一节，含常用选项示例）
- 配置详解（配置文件格式、优先级等）
- 工程集成（CI/CD、编辑器、预提交钩子等）
- 最佳实践与常见陷阱
N-1. 参数完整索引（⚠️ 必须包含，见下方格式规范）
N. 参考资料
判断标准：文档主题涉及命令行工具（如 ruff、curl、git、uv、docker、kubectl 等）时，必须包含「参数完整索引」章节作为倒数第二章节。
工具/框架类专属结构（⚠️ 如文档主题是有配置项的工具/框架，必须包含环境变量章节）：
判断标准：文档主题涉及有环境变量支持的工具/框架（如 uv、docker、node、python、git 等）时，必须包含「环境变量」章节，完整列出所有支持的环境变量。
环境变量章节规范：
- - 位置：放在「安装与配置」章节内，或作为独立章节（配置后、实战案例前）
- 分组：按功能分组（如「路径/目录」「网络/代理」「认证」「行为控制」等）
- 格式：每组一张 3 列表格 变量名 | 说明 | 示例/默认值，重要变量标注加入版本
- 完整性：必须覆盖官方文档的全部环境变量，不可只列「常用」的几个
- 弃用标注：已弃用的变量须注明 ⚠️ 已弃用及替代变量
- 外部变量：除工具自身定义的变量外，还需列出工具读取的外部系统变量（如代理、TLS 证书等）
markdown
X.X 环境变量（完整列表）
官方参考：https://docs.xxx.xxx/reference/environment/
X.X.1 <工具名> 自身定义的环境变量
📁 路径与目录
| 变量 | 说明 | 示例/默认值 |
|---|
| TOOLCACHEDIR | 缓存目录 | ~/.cache/tool |
🌐 网络与代理
| 变量 | 说明 | 示例/默认值 |
|---|
| TOOLHTTPTIMEOUT | HTTP 超时（秒） | 30 |
X.X.2 <工具名> 读取的外部变量
| 变量 | 说明 |
|---|
| HTTPPROXY | HTTP 代理 |
| HTTPSPROXY |
HTTPS 代理 |
X.X.3 使用示例
bash
示例注释
TOOL_VAR=value tool command
Step 3：写各方法详解
每个方法/概念的详解必须包含：
- - 论文出处：作者、机构、年份、论文名
- 提出动机：解决什么问题（why）
- 数学定义：完整公式（LaTeX 格式）
- 导数 / 梯度：反向传播必要信息
- 直觉解释：用类比或图示帮助理解（why it works）
- 优点表格：结构化列出
- 缺点表格：结构化列出，包含已知的反驳/修正
- 适用场景：具体的任务、架构、数据类型
- 代码示例：可运行的代码片段
Step 4：补充原文没有的视角
优先添加以下高价值内容：
- 1. 统一理论框架：如所有归一化方法的本质区别是在哪个维度做统计
- 历史演进脉络：用时间线梳理技术发展，突出技术迭代的逻辑
- 已被推翻的叙事：如BN 有效不是因为解决了 ICS，而是平滑了损失曲面
- 现代实践：最新的大模型 / SOTA 方法在用什么（如 RMSNorm、SwiGLU、LayerNorm 的变体等）
- 新兴技术覆盖：重点关注近 3-5 年内提出的重要技术，确保文档反映技术前沿
- 跨领域应用：不同领域（如 NLP、CV、生成模型）中归一化方法的选择差异
- 常见陷阱：实践中容易踩的坑（如 PyTorch BN 的 momentum 定义与数学相反）
- 决策树：帮助读者快速找到适合自己场景的方法
Step 5：写综合对比表
必须包含横向对比表，列出：
快速对比 |
| 关键特性（布尔值）| 一目了然 |
| 计算效率（星级）| 相对成本 |
| 主要应用场景 | 实用导向 |
Step 6：分步输出（⚠️ 强制步骤）
对于大型技术文档（预计超过 500 行 / 5 个以上章节
