文档编写技能Skill：让 AI 写文档时解释「为什么」，而不是复述「是什么」
- 一句话定位：这是一个专注于「代码内文档」的 AI 技能，覆盖文件夹 README、JSDoc 注释与代码注释三类产物，核心要求是解释设计意图与推理，而不是把代码翻译成自然语言。
- 三条硬规则：文档解释「为什么」而非「什么」；README 讲清文件夹为何存在；注释只在代码不够清晰时才写。
- 反模式清单：拒绝
ls式文件罗列、拒绝「auth.ts - 身份验证」这类同义反复、拒绝注释掉的死代码。 - 可落地：技能内置了「好例子 / 坏例子」对照，直接可作为团队评审文档质量的检查表。
- 协作属性：该技能声明遵循
writing-voice技能的语气规范，可与写作风格类技能组合使用，保持全项目文档口吻统一。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：文档编写技能Skill 技能英文名：documentation 技能ID：11880
它要解决的问题非常具体：AI 写文档最大的毛病不是「写不出来」，而是「写得太像目录」。让它给一个文件夹生成 README，它往往输出一长串文件名加一句同义解释——「to-arktype.ts - 转换为 ArkType」「index.ts - 导出」。这种文档读者扫一眼代码就能得到，等于零信息增量。同样，AI 写的 JSDoc 常常是「返回所有表格助手作为数组」这种把函数签名翻译一遍的废话，既没说清什么时候该用它，也没给可运行的示例。
这个技能把「文档的价值在于解释推理」这条原则固化成了技能指令，让 AI 在生成文档时主动回答：这个文件夹为什么存在？这些模块之间的思维模型是什么？这段代码为什么要用这个绕法？读者从代码里读不出来的东西，才是文档该写的东西。
关于「一键安装」，需要说明的是：技能详情中并未给出具体的安装命令、市场入口地址或版本信息，因此以下为通用流程，具体命令与入口以官方说明为准：
- 确认安装前提：你使用的 AI 编程助手/客户端需支持技能（Skill）机制，并已开启技能加载能力；由于本技能声明遵循
writing-voice的语气规范，建议同时确认该写作语气类技能可用，否则文档语气部分可能退化。 - 检索技能：在技能市场或技能列表中，用中文名「文档编写技能」、英文名
documentation或技能ID11880进行检索。 - 添加并启用：将该技能添加到当前工作区或项目级配置中；若客户端支持项目级技能目录，优先选择项目级，便于团队共享同一套文档规范。
- 验证是否生效：随便挑一个业务文件夹，向助手发出请求——「为这个文件夹写一份 README」。如果输出仍然是一串文件名清单，说明技能未生效；如果输出开始解释该文件夹的职责、模块之间的关系（甚至给出 ASCII 结构图）、以及新增文件时应遵循的约定，说明技能已正确加载。
2. 该技能的主要功能和特点
- 覆盖三类文档产物：代码内文档、文件夹 README、代码注释。它不是只写一种文体，而是把「解释型写作」贯穿到三个层级。
- 以「为什么」为第一原则：技能明确要求「用户可以阅读代码以了解其作用，他们需要你解释推理」。这条原则直接决定了输出的信息密度。
- 文件夹 README 的正面清单：允许并鼓励使用 ASCII 艺术图表达复杂关系、概述关键导出与入口点、为文件名补充上下文、说明与其他文件夹的关系。
- 文件夹 README 的负面清单：禁止只重复
ls的详尽文件列表、禁止复述文件名的同义描述、禁止在文档里写「代码本身表达得更好」的实现细节。 - JSDoc 的写法规范：要求包含带真实用法的
@example代码块、说明「何时使用」而不只是「做什么」、记录不明显的行文与边缘情况；并区分文档粒度——公共 API 获得详细文档，内部辅助函数可以简短。 - 代码注释的克制原则：代码清晰就不写注释；只在「为什么不显而易见」时写；对变通写法（workaround）要注释并链接到对应 issue 或文档；注释掉的代码一律删除，交给版本控制。
- 自带正反例对照：技能内容里每个模块都配有「好例子 / 坏例子」，这让它不仅能生成文档，也能当作评审标准使用。
- 与写作语气技能联动：声明遵循
writing-voice的语气，这使得它在多人协作仓库里不会产生「每个文件一种文风」的割裂感。
和普通「让大模型写个 README」相比，它强在约束：普通对话式生成没有反模式清单，模型倾向于凑字数、堆清单；而本技能内置了明确的禁止项与判断标准，输出更接近一位资深工程师写的文档，而不是一份自动生成的目录说明。
3. 如何使用该技能？
以下为通用使用步骤，调用入口与具体交互方式以你所用客户端的官方说明为准。
第 1 步：明确你要的文档层级 先判断当前需求属于哪一类：文件夹 README（解释模块职责）、JSDoc（解释公共 API 的调用时机）、还是行内注释（解释非常规实现）。技能对三者的要求不同，说明层级能让输出更精准。
第 2 步：提供足够的上下文 把目标文件夹的文件列表、关键入口文件内容、以及模块间的调用关系一并提供给助手。仅给一个文件名列表，模型很难写出「为什么」，只能退回清单式输出。建议附上一句话业务背景，例如「这个目录负责把字段模式编译成不同目标格式」。
第 3 步：发出结构化指令 可参考这样的输入示例：
使用「文档编写」技能，为
converters/文件夹写一份 README。说明这个文件夹为什么存在、各个转换器之间的关系，以及新增一个转换器时需要遵守什么约定。不要罗列文件清单。
第 4 步：检查输出是否满足三条判据 ① 是否出现了关系图或关系描述（而非文件列表）；② 是否解释了这个模块存在的理由；③ 是否给出了「什么时候该在这里加文件」的约定。三条中缺两条，基本可以判定是退化输出，需要补充上下文重试。
第 5 步：JSDoc 场景下指定示例需求
写公共 API 文档时，明确要求「包含 @example 块，示例要是能直接跑的真实用法，并说明何时该用这个方法、何时不该用」。输出后重点核对示例中的参数名、返回值结构是否与真实代码一致——这是最容易被模型写错的部分。
第 6 步：代码注释场景下要求「只注释为什么」
对一段复杂逻辑，可以这样提问：「解释这段排序为什么不能依赖 clientID，把结论写成一行代码注释」。技能会输出类似「Y.Doc 的 clientID 是随机 32 位整数，不能依赖顺序，因此改用条目自身时间戳做确定性排序」这样的注释，而不是「对条目进行排序」。
第 7 步：人工复核并纳入仓库 文档生成后务必人工过一遍事实准确性，再提交。建议把生成的「好例子」沉淀为团队模板，后续同类文件夹直接复用结构。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 文档编写技能Skill（documentation） | 带写作规范的 AI 文档生成技能 | 文件夹 README、JSDoc、代码注释三类产物的「解释型」写作，含正反例与反模式清单 | 需支持技能机制的客户端，按名称或技能ID添加，以官方说明为准 | 仓库文档补全、公共 API 文档、注释质量治理 | 优势：输出有原则约束，避免清单式废话，语气可与其他写作技能统一；不足：依赖上下文输入，事实准确性仍需人工复核 |
| 通用大模型直接对话 | 无约束的自由生成 | 任意文档生成 | 极低，打开对话框即可 | 一次性、临时的说明文字 | 优势：零配置；不足：倾向罗列文件名、注释同义反复，缺少反模式约束，风格不稳定 |
| 文档生成工具链（如依据注释生成 API 文档的自动化工具） | 自动化产出结构化 API 文档 | 从注释与类型信息生成站点/HTML | 需接入构建流程与规范注释 | 对外 SDK 文档站点 | 优势：可重复、结构化、随代码更新；不足：只搬运已有注释，不判断注释写得好不好，也不负责解释「为什么」 |
| 团队文档规范手册 / 人工写作指南 | 组织级规范 | 提供写作标准与评审清单 | 需人工培训与评审 | 中大型团队文档治理 | 优势：标准权威；不足：落地靠人自觉，执行成本高，无法直接产出内容 |
5. 该技能的典型应用场景与实际体验情况
场景一：接手陌生仓库，补齐缺失的 README 一位新加入的工程师被分配到一个从未写过文档的核心目录，痛点是「看得懂每行代码，但不知道这个目录在整体架构里的位置」。使用方式是让技能读取入口文件与调用方，输出一份解释模块职责、上下游关系、以及「新代码该放哪」的 README。实际体验上，上手几乎没有难度，关键在于是否愿意花两分钟补充上下文；如果只丢文件名，输出质量会明显下滑。注意事项：ASCII 关系图需要人工确认是否与真实调用链一致。
场景二：公共 API 的 JSDoc 补齐
技术负责人需要为对外暴露的方法补充文档，痛点是现有注释只有一句「返回数组」，调用方根本不知道什么时候该用。使用技能后，输出的注释会包含使用时机说明与 @example 代码块。实际体验：这类任务收益最直接，因为「何时使用」正是调用方最缺的信息；但示例代码里的参数名、返回结构必须逐行核对，模型在此处最容易「想当然」。
场景三：代码评审中的注释质量治理 团队在做 Code Review 时经常看到「// 对条目进行排序」这类无信息量注释，以及大段被注释掉的旧代码。可以让技能对指定文件做一次「注释体检」，按「该删的、该补为什么的、该链接 issue 的」分类给出建议。实际体验：它给出的判断标准非常可执行，尤其「删除注释掉的代码，版本控制就是为此存在的」这条，能有效减少历史包袱。
场景四：把写作规范沉淀成团队模板
团队希望统一文档口吻，技能声明遵循 writing-voice 语气规范，因此可以作为「文档语气基线」。实际体验：多人协作时文风割裂的问题会明显缓解。注意事项：语气类依赖若未一并启用，风格一致性会打折。
6. 该技能能为用户带来的价值
第一，把「写文档」从凑字数变成信息增量。 传统 AI 生成的 README 大约有一半篇幅是文件名的同义复述，读者读完仍然不知道这个目录为什么存在。技能通过反模式清单直接砍掉这部分无效内容，文档的可用信息密度显著提升。
第二，降低文档工作的启动门槛。 「不知道从哪写起」是文档长期缺失的主因。技能给出了明确的结构配方——复杂关系用 ASCII 图、概述关键导出、说明与其它文件夹的关系——照着填就能产出合格初稿，把原本需要半小时的空白页焦虑压缩成几分钟的校对。
第三，把隐性知识显性化。 代码注释解释「为什么用时间戳排序而不是 clientID」，这类知识通常只存在于某位工程师的脑中，人一走就失传。技能强制把「变通原因」和「边缘情况」写进注释与 JSDoc，本质是在做知识资产的沉淀。
第四，形成可复用的质量标尺。 技能内置的好例子与坏例子，可以直接转化为团队 Code Review 的检查项：README 里有没有文件清单式罗列？JSDoc 有没有 @example？注释是否只是在复述代码？这让「文档写得好不好」从主观判断变成可对照的清单。
长期价值在于一致性与可维护性：当每个模块的 README 回答的是同一组问题、每条注释回答的都是「为什么」，新成员的上手时间与跨模块沟通成本会持续下降，而这类收益会随着仓库规模增长而放大。
7. 常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
在支持技能机制的 AI 客户端或技能市场中，用中文名「文档编写技能」、英文名 documentation 或技能ID 11880 检索并添加到工作区即可。技能详情中未包含安装命令、市场链接与定价信息，具体入口与是否收费以官方说明为准。
Q2：它和直接让大模型写 README 有什么区别？ 关键差别在约束。直接对话没有反模式清单，模型倾向于列出所有文件并为每个文件写一句同义解释；本技能明确禁止「只重复 ls 的文件列表」和「重复文件名的描述」，并要求说明文件夹存在的理由、模块间关系与新增文件的约定。
Q3：适合谁用？ 适合三类人：需要为陌生仓库补文档的开发者、负责对外 API 文档维护的技术负责人、以及希望统一团队文档与注释规范的技术管理者。对完全不做代码相关工作的用户，价值有限。
Q4：生成的文档可以直接提交吗？
不建议直接提交。技能解决的是「写什么、怎么写」的结构问题，不保证事实准确。@example 中的参数名、返回结构、以及 ASCII 关系图与实际调用链是否一致，都需要人工核对后再入库。
Q5：它和自动化文档生成工具怎么选？ 两者不冲突。自动化工具负责把已有的规范注释稳定地渲染成 API 文档站点，但它不判断注释本身写得好不好；本技能负责把注释和 README 的内容质量提上去。实践中常见组合是：先用本技能生成或改写注释与 README，再由文档生成工具产出站点。