关于 doc-generator
doc-generator 是面向开发者和文档作者的写作技能，用于创建或修订技术文档。它强调先陈述主旨、依据具体内容支撑论点，并通过反冗余检查和质量门槛控制篇幅与表达。
主要功能
- 01按受众与主旨界定文档范围
- 02遵循风格配置起草内容
- 03检查冗余与 AI 文风特征
- 04按句子和文档层面执行质量门槛
- 05支持文档与注释修订
适用场景
- 01撰写 README、指南或 API 文档
- 02为不同读者层级准备内容
- 03精简现有文档并保留原意
- 04按规范改写代码注释
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/doc-generator确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
modules/generation-guidelines.mdquality-gates.mdremediation-workflow.md详细介绍
文档生成器
文档的成本，是读者投入时间的总和。要么证明这份成本值得，要么删减内容。
生成以具体论据为依据、开篇点明主旨且句句有价值的文档。“在当今快节奏的世界中”这类填充短语，以及没有证据支撑的“全面”“完整”等模糊描述，都是冗余内容。任何不能传达、举例说明、限定或重申文档唯一核心要点的句子，也同样多余。
此技能同时规范句子层面的简洁性（不使用拙劣词汇、避免过度使用 em dash 或谄媚式开场）和文档层面的精炼度（主旨优先、句句有分量，仅重申主旨）。完整评估标准见 Skill(scribe:slop-detector) 模块 document-economy.md。
不适用场景
- 将外部文件转换为 Markdown（使用
leyline:document-conversion及其project-import模块） - 扫描现有文稿中的 AI 写作痕迹（使用
scribe:slop-detector）
核心写作原则
使用主动语态，并体现作者视角。解释技术选择背后的理由（为什么选这个数据库，而不是那个），不要只给出中性的模板文字。谨慎使用项目符号，仅用于简短、并列的摘要。将多行项目符号长列表改写为散文，让推理过程得以保留。
词汇与风格
避免商业行话和语言习惯问题，例如镜像式句式或过度使用 em dash。文档字符串使用祈使语气（“Validate input”，而不是“Validates”）。不要把非生命体拟人化（例如“代码想要”“函数在表达”）。
| 不要使用 | 改用 |
|---|---|
| fallback | default、secondary |
| leverage | use |
| utilize | use |
| facilitate | help、enable |
| comprehensive | thorough、complete |
9. 避免拟人化表达
“Lives under”“speaks to”及类似说法只适用于有生命的事物。
10. 文档字符串使用祈使语气
使用“Validate”，不要使用“Validates”（遵循 PEP 257、pydocstyle、ruff）。
必需的 TodoWrite 项目
doc-generator:scope-defined- 已确定目标文件和类型doc-generator:style-loaded- 已应用风格配置文件（如有）doc-generator:content-drafted- 已创建初稿doc-generator:slop-scanned- 已检查 AI 写作痕迹doc-generator:quality-verified- 已通过原则检查清单doc-generator:user-approved- 已获得最终批准
模式：生成
用于编写新文档：
第 1 步：定义范围
## Generation Request
**Type**: [README/Guide/API docs/Tutorial]
**Audience tier**: [newcomer | practitioner | expert | persona: <one line>]
**Audience**: [developers/users/admins]
**Audience size**: [1 / small team / org / public]
**Read frequency**: [once / weekly / per-invocation]
**Thesis**: [one sentence the reader must walk away with]
**Length target**: [~X words or sections]
**Style profile**: [profile name or "default"]
主旨字段为必填项。如果无法用一句话说明核心要点，就说明范围尚未明确。受众规模和阅读频率决定读者时间预算（参见 scribe:slop-detector 模块 document-economy.md）：每天由 50 位用户加载的 skill，与 1:1 设计说明的时间预算截然不同。
受众层级也为必填项；如果请求中没有说明，请先询问，不要猜测。猜测读者特征会让文档看起来专业，却无法服务任何人。层级表、用于引导用户明确层级的苏格拉底式问题集，以及创意写作的例外情况，见 scribe:slop-detector 模块 audience-targeting.md。
层级决定初稿中保留哪些内容：
| 层级 | 保留 | 移至深入介绍 |
|---|---|---|
newcomer | 唯一一条端到端可行的路径 | 内部机制、历史、考虑过的替代方案 |
practitioner | 读者无法自行推导的仓库特定事实 | 通用领域知识 |
expert | 新颖论点及其数据 | 无。深入介绍适合这一层级 |
第 2 步：加载风格（如有）
如果存在风格配置文件：
cat .scribe/style-profile.yaml
应用语气、词汇和结构规范。
第 3 步：起草内容
开篇先讲核心论点。 第一段必须说明唯一的核心要点。如果读者读完开篇就停下，也应能带着这条信息离开。正文中呼应一次核心论点，结尾再呼应一次。删掉其他所有重复内容。
遵循上述 10 条核心原则。每个章节都应：
- 从关键信息开始（说明核心论点或其明确实例）
- 仅在有价值时补充背景信息（它是否能支撑、体现或限定核心论点？）
- 使用具体示例（一个是证明；两个是强调；三个就是凑数）
- 优先使用段落，而非项目符号
- 信息完整后就结束（不要用总结凑篇幅，也不要用“总而言之”重复陈述）
依据声明的层级，对每个章节进行删减测试：保留读者采取行动前需要的信息，链接他们之后需要的信息，提取只有更高层级读者需要的内容，删除所有层级读者都不需要的内容。最容易被跳过的判定结果就是“提取”。newcomer 无法使用的内容通常并非写得不好，而是在回答他们尚未提出的问题。技能相关内容移至 modules/<topic>.md，仓库文档相关内容移至 docs/deep-dive/<topic>.md，并从父级文档的开篇添加链接。绝不要为了符合某个层级而删除内容。
第 4 步：运行 Slop Detector
uv run --with pyyaml python scripts/slop_score.py --audit <files>
Skill(scribe:slop-detector)
该脚本会定位每项发现，并标出文件和行号，包括合并门禁不计分的低置信度类别和可选类别。技能文档会说明如何重写每项内容。继续之前先修复这些问题，并将 (low) 和 (medium) 命中项留给人工判断。
第 5 步：质量门禁
根据清单进行核验：
句子层面：
- 不含一级空话词
- 每 1000 个单词的破折号少于 3 个
- 项目符号占比低于 40%
- 所有论断都有具体内容支撑
- 没有公式化的开头或结尾
- 体现作者视角
- 不使用表情符号（除非明确要求）
文档层面（document-economy 模块）：
- 在开篇提出单一且清晰的核心论点（2/2）
- 超过 80% 的句子能够支撑、体现、限定或重复核心论点（2/2）
- 至少 3 次呼应核心论点；删除与核心论点无关的重复内容（2/2）
- 写作时间与（受众规模 × 阅读频率 × 单次阅读时间）大致成正比
受众（audience-targeting 模块）：
- 已声明层级；若请求未说明，则应先询问，而非猜测（2/2）
- 每个章节都服务于声明的层级
- 层级不符的内容已提取并添加链接，而非删除
- 每篇新深入指南都声明自己的层级
模式：修复
用于清理现有内容：
加载：@modules/remediation-workflow.md
第 1 步：分析当前状态
# Get slop score
Skill(scribe:slop-detector) --target file.md
第 2 步：逐节处理
对于较大的文件（超过 200 行），应逐步编辑：
## Section: [Name] (Lines X-Y)
**Current slop score**: X.X
**Issues found**: [list]
**Proposed changes**:
1. [Change 1]
2. [Change 2]
**Before**:
> [current text]
**After**:
> [proposed text]
Proceed? [Y/n/edit]
第 3 步：保留意图
绝不改变所说的内容，只改变表达方式。如果意思不明确，请提问。
第 4 步：重新验证
编辑后，再次运行 slop-detector，确认内容有所改善。
Docstring 专属规则
编辑代码注释时：
- 只修改 docstring/注释文本
- 绝不修改周围代码
- 使用祈使语气（“Validate input”，而不是“Validates input”）
- 简洁为佳——删掉赘语
- 保留 Args/Returns 结构（如果存在）
模块参考
- 内容创作模式见
modules/generation-guidelines.md - 验证标准见
modules/quality-gates.md
与其他技能集成
| 技能 | 使用时机 |
|---|---|
| slop-detector | 起草后、审批前 |
| style-learner | 生成前加载风格档案 |
| sanctum:doc-updates | 用于更广泛的文档维护 |
退出标准
- 已创建或修复内容
- Slop 评分 < 1.5（评级为干净）
- 请求中已声明受众层级，并在草稿中遵守
- 文档精简度评分 >= 7/8，受众契合度评分为 2/2
- 所有提取内容均已放入
modules/或docs/deep-dive/并从父文档的导言部分链接 - 已通过质量门槛检查清单
- 已获得用户批准
- 不含表情符号（除非另有说明）