ClawHub

Tech Doc Writer

Other

This skill should be used when the user wants to write detailed technical learning documentation, study notes, or knowledge summaries for deep learning, machine learning, or any technical topic. Use when user says "技术文档写作", "写一篇...文档", "整理...笔记", "写一篇关于...的学习资料", "结合文章写一份文档", or requests comprehensive technical documentation with formulas, code examples, and comparisons. Produces structured, detailed markdown documents with mathematical formulas, code examples, comparison tables, and decision guides following a consistent high-quality format.

Install

openclaw skills install tech-doc-writer

技术学习文档写作 Skill

本 skill 指导如何写高质量、结构清晰、内容详细的技术学习文档（markdown 格式），适用于深度学习、机器学习、算法原理等技术主题。风格参考：激活函数文档、归一化方法文档。

核心目标：确保文档内容全面、及时反映技术最新发展，避免遗漏重要的新兴技术和实践。

核心写作流程

Step 1：信息收集

如果用户提供了参考文章 URL，先获取原文内容，然后：

  1. 识别原文覆盖的知识点
  2. 获取当前系统时间,找出原文的错误、缺失、过时的内容
  3. 结合自身知识补充原文没有的重要内容，特别是最新的技术发展和实践

重要原则：不是"翻译"原文，而是以原文为基础，用自己的理解重写和扩充，确保内容的全面性和时效性。

特别注意：对于技术领域的文档，要重点关注近 3-5 年内的重要进展，如大模型中使用的 RMSNorm、SwiGLU 等新兴技术。

Step 1.5：穷举知识点 Checklist（⚠️ 强制步骤，不可跳过）

这是防止内容遗漏的核心机制。 过去的教训：直接进入写作模式会导致「写作驱动」而非「规划驱动」，靠「想到什么写什么」会遗漏非显眼但重要的技术点（如 MMR、RAG-Fusion、Semantic Cache 等）。

在动笔之前，必须先完成以下 3 个动作：

动作 1：按维度分类，穷举所有候选技术点

对文档主题，按照以下维度系统扫描，列出所有相关技术点：

维度扫描框架（根据主题调整）：

- 算法/方法类：基础方法 + 变体 + 新兴方法
- 工程实现类：库/框架 + 工具 + 部署
- 评估/对比类：指标 + 基准测试 + 对比维度
- 优化/改进类：性能优化 + 成本优化 + 质量优化
- 生态/周边类：相关工具 + 集成方案

动作 2：参照权威来源交叉验证，防止遗漏：

  • 主流框架文档的 API/模块目录（最完整的技术地图，如 LangChain Retrievers 文档）
  • 最新 Survey 论文的技术分类表
  • 相关 GitHub Awesome 列表

动作 3：将所有技术点组织为带复选框的 Checklist

示例（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）
2. 统一视角 / 核心框架（用一个视角统一理解所有方法）
3. 各方法详解（每个方法独立一节）
4. 方法对比表（综合横向比较）
5. 选择指南 / 决策树（实用建议）
6. 代码示例（PyTorch / Python）
7. 参考资料

命令行工具专属结构（⚠️ 如文档主题是 CLI 工具/命令行程序，必须额外包含参数完整索引章节）：

1. 引言（工具简介、与其他工具对比、安装）
2. 核心概念（命令/子命令体系、配置文件等）
3. 各子命令详解（每个子命令独立一节，含常用选项示例）
4. 配置详解（配置文件格式、优先级等）
5. 工程集成（CI/CD、编辑器、预提交钩子等）
6. 最佳实践与常见陷阱
N-1. 参数完整索引（⚠️ 必须包含，见下方格式规范）
N.   参考资料

判断标准：文档主题涉及命令行工具（如 ruff、curl、git、uv、docker、kubectl 等）时，必须包含「参数完整索引」章节作为倒数第二章节。

工具/框架类专属结构（⚠️ 如文档主题是有配置项的工具/框架，必须包含环境变量章节）：

判断标准：文档主题涉及有环境变量支持的工具/框架（如 uv、docker、node、python、git 等）时，必须包含「环境变量」章节，完整列出所有支持的环境变量。

环境变量章节规范：

  • 位置：放在「安装与配置」章节内，或作为独立章节（配置后、实战案例前）
  • 分组：按功能分组（如「路径/目录」「网络/代理」「认证」「行为控制」等）
  • 格式：每组一张 3 列表格 变量名 | 说明 | 示例/默认值，重要变量标注加入版本
  • 完整性：必须覆盖官方文档的全部环境变量，不可只列「常用」的几个
  • 弃用标注：已弃用的变量须注明 ⚠️ 已弃用及替代变量
  • 外部变量：除工具自身定义的变量外，还需列出工具读取的外部系统变量（如代理、TLS 证书等）
### X.X 环境变量（完整列表）

> 官方参考：https://docs.xxx.xxx/reference/environment/

#### X.X.1 <工具名> 自身定义的环境变量

**📁 路径与目录**

| 变量 | 说明 | 示例/默认值 |
|------|------|-----------|
| `TOOL_CACHE_DIR` | 缓存目录 | `~/.cache/tool` |

**🌐 网络与代理**

| 变量 | 说明 | 示例/默认值 |
|------|------|-----------|
| `TOOL_HTTP_TIMEOUT` | HTTP 超时（秒） | `30` |

#### X.X.2 <工具名> 读取的外部变量

| 变量 | 说明 |
|------|------|
| `HTTP_PROXY` | HTTP 代理 |
| `HTTPS_PROXY` | HTTPS 代理 |

#### X.X.3 使用示例

```bash
# 示例注释
TOOL_VAR=value tool command


### Step 3：写各方法详解

每个方法/概念的详解必须包含：

- **论文出处**：作者、机构、年份、论文名
- **提出动机**：解决什么问题（why）
- **数学定义**：完整公式（LaTeX 格式）
- **导数 / 梯度**：反向传播必要信息
- **直觉解释**：用类比或图示帮助理解（why it works）
- **优点表格**：结构化列出
- **缺点表格**：结构化列出，包含已知的反驳/修正
- **适用场景**：具体的任务、架构、数据类型
- **代码示例**：可运行的代码片段

### Step 4：补充原文没有的视角

优先添加以下高价值内容：

1. **统一理论框架**：如"所有归一化方法的本质区别是在哪个维度做统计"
2. **历史演进脉络**：用时间线梳理技术发展，突出技术迭代的逻辑
3. **已被推翻的叙事**：如"BN 有效不是因为解决了 ICS，而是平滑了损失曲面"
4. **现代实践**：最新的大模型 / SOTA 方法在用什么（如 RMSNorm、SwiGLU、LayerNorm 的变体等）
5. **新兴技术覆盖**：重点关注近 3-5 年内提出的重要技术，确保文档反映技术前沿
6. **跨领域应用**：不同领域（如 NLP、CV、生成模型）中归一化方法的选择差异
7. **常见陷阱**：实践中容易踩的坑（如 PyTorch BN 的 momentum 定义与数学相反）
8. **决策树**：帮助读者快速找到适合自己场景的方法

### Step 5：写综合对比表

必须包含横向对比表，列出：

| 字段 | 说明 |
|------|------|
| 方法名 + 提出年份 | 时间感 |
| 核心公式摘要 | 快速对比 |
| 关键特性（布尔值）| 一目了然 |
| 计算效率（星级）| 相对成本 |
| 主要应用场景 | 实用导向 |

### Step 6：分步输出（⚠️ 强制步骤）

对于**大型技术文档**（预计超过 500 行 / 5 个以上章节），必须采用分步输出策略：

1. **建立 todo list**，将文档拆分为 5~8 个 Part，每个 Part 对应 1~2 个章节
2. **每次只输出一个 Part**，完成后立即继续下一个 Part，无需等待用户催促
3. **自动推进**：每个 Part 完成后，标记 todo 为 completed，立即开始下一个
4. **告知进度**：在每个 Part 开头说明"当前是第 X/N 部分"

> **原因**：一次性生成过长内容容易截断、遗漏章节、丢失上下文。分步输出确保每部分质量，也让用户实时看到进展。

5. **结构完整性校验（⚠️ 强制）**：所有 Part 写完后，执行以下命令验证章节结构：
   ```bash
   grep -n "^## " 文档文件名.md

确认输出中章节编号从 1 开始连续递增，无跳号、无缺失。若发现如「第3章后直接是第8章」的跳号，必须立即补全缺失章节，再进行后续输出。

Step 7：完成后遗漏自检（⚠️ 强制步骤）

文档全部写完后，必须执行一次遗漏自检，步骤如下：

  1. 列出文档现有的所有章节/技术点（grep "^### \|^####" 扫描）
  2. 重新过一遍 Step 1.5 的 Checklist，逐项确认是否已覆盖
  3. 重点核查容易遗漏的维度：
    • 工程优化类（缓存、增量更新、可观测性）
    • 多样性/效率类（与主流精度类方向不同）
    • 新兴/小众但重要的技术（近 1~2 年新提出）
  4. 若发现遗漏，立即补充到对应章节

教训：本规则来自实际 RAG 文档写作经验——初版遗漏了 MMR、RAG-Fusion、Semantic Cache、Multi-Vector Index、ColBERT、LLMLingua 等多项重要技术，均在事后检查中发现补充。

格式规范

数学公式

  • 所有公式使用 LaTeX 格式
  • 行内公式：$f(x) = ...$
  • 块级公式：$$f(x) = ...$$
  • 必须给出导数/梯度公式（反向传播需要）
  • 重要变量要注解其含义
**数学定义：**

$$\sigma(x) = \frac{1}{1 + e^{-x}}$$

**导数：**

$$\sigma'(x) = \sigma(x)\big(1 - \sigma(x)\big)$$

代码示例

  • 使用 Python / PyTorch（深度学习场景）
  • 代码要可运行，包含必要的 import
  • 加中文注释
  • 示例要体现实际使用场景，而非只是 API 调用
# 示例：SwiGLU（LLaMA FFN 层）
class SwiGLU(nn.Module):
    """LLaMA / PaLM 使用的前馈层，用 SwiGLU 替代标准 FFN"""
    def __init__(self, in_dim, hidden_dim):
        super().__init__()
        self.w1 = nn.Linear(in_dim, hidden_dim, bias=False)
        self.w2 = nn.Linear(hidden_dim, in_dim, bias=False)
        self.w3 = nn.Linear(in_dim, hidden_dim, bias=False)

    def forward(self, x):
        # SiLU(xW1) ⊙ (xW3)，再经过 W2 投影
        return self.w2(F.silu(self.w1(x)) * self.w3(x))

ASCII 图示

对于维度关系、架构结构，使用 ASCII 图增强可视化：

        N (Batch)
        │
  ┌─────┼─────┐
  │ S1  │ S2  │
  └──┬──┘──┬──┘
     │  C  │
  ┌──┴──┐
  │ch1  │ch2│  H×W
  └─────┴───┘
  
BN: 在 N×H×W 上统计（跨样本）
LN: 在 C×H×W 上统计（跨通道）

表格规范

优缺点用结构化表格，不用列表：

| 优点 | 说明 |
|------|------|
| 加速训练 | 允许更大学习率，收敛快 |
| 正则化效果 | mini-batch 噪声类似 Dropout |

参数完整索引规范（CLI 工具文档专用）

当文档主题为命令行工具时，倒数第二章节必须是「参数完整索引」，按功能分组，每个分组一张 4 列表格。

列顺序：短参数 | 长参数 | 说明 | 示例

格式要求：

  • 无短参数的行，短参数列留空（不写 — 或 /）
  • 示例列必须是可直接运行的完整命令片段
  • 同一子命令的参数按「修复/输出/规则选择/文件选择/其他」等功能子分组，用 #### 小标题分隔
  • 子命令本身单独列一张「子命令一览」表，包含「子命令 / 说明 / 是否修改文件 / 示例」4 列

标准模板：

## N. 参数完整索引

> 按功能分类整理所有常用参数，便于快速查阅。

### N.1 子命令一览

| 子命令 | 说明 | 是否修改文件 | 示例 |
|--------|------|------------|------|
| `check` | 执行 lint 检查 | 否（`--fix` 时是） | `ruff check .` |
| `format` | 执行代码格式化 | 是（`--check` 时否） | `ruff format .` |

### N.2 全局选项

| 短参数 | 长参数 | 说明 | 示例 |
|--------|--------|------|------|
| `-v` | `--verbose` | 启用详细日志 | `-v` |
| | `--config <FILE>` | 指定配置文件 | `--config ruff.toml` |

### N.3 <子命令名> 选项

#### 修复相关

| 短参数 | 长参数 | 说明 | 示例 |
|--------|--------|------|------|
| | `--fix` | 应用安全修复 | `ruff check --fix .` |

参考示例：见 zwy/stats/py_base/002_doc_ruff.md 第 9 章、zwy/stats/shell/004_doc_curl_wget_shell.md 第 10 章。

引用、警告块

用 blockquote 标注重要修正或补充：

> **重要修正**：后续研究表明，BN 的有效性主要来自平滑损失曲面，
> 而非解决 ICS——这是对原始论文叙事的重要修正。

质量检查清单

写完文档后，获取当前系统时间,仔细检查文档，简单梳理结构，看看是否有过时内容，遗漏内容和改进的地方,未解释的缩写或名词,并进行改进。 然后逐项确认：

【分步输出检查（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 — 激活函数文档节选示例
  • references/normalization-example.md — 归一化文档节选示例