documentation（技术文档管理）Skill 是什么？能自动写哪些技术文档？

技术文档管理Skill：把“没人愿意写的文档”交给 AI，一次配好覆盖代码注释到 API 参考

它是什么：一个专注于“写文档”的 AI 技能，覆盖代码文档字符串、内联注释、API 参考、README、架构决策记录（ADR）、更新日志与用户指南全链路。
它解决什么：文档缺失、过时、风格不统一、只有作者自己看得懂——这些“技术债”问题，正好对应详情里强调的“评估需求 → 分类型产出 → 遵循技术写作原则”的流程。
怎么用：通过触发关键词（文档、README、更新日志、ADR、JSDoc、API 文档等）自然唤起，也可以用“帮我给这个模块补文档”这类指令直接调用。
权限边界清晰：技能只使用读取、搜索、全局匹配、编辑、写入五类工具，聚焦“看代码 + 写文档”，不涉及执行与部署。
适合谁：需要长期维护开源项目的开发者、要做接口交付的后端团队、需要沉淀架构决策的技术负责人，以及接手遗留系统的新成员。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目	内容
中文名	技术文档管理Skill
英文名	documentation
技能ID	13508
核心定位	创建并维护全层级技术文档
工具权限	读取、搜索、全局匹配、编辑、写入
触发关键词	文档、文档编写、记录、README、教程、指南、参考、更新日志、ADR、架构决策记录、文档字符串、JSDoc、rustdoc、pydoc、标记语言、mdx、API 文档、用户指南、开发者指南、内联注释、代码注释

它解决了什么问题？

大多数团队并不缺“写文档的能力”，缺的是“写文档的意愿和时间”。项目赶进度时，README 停在一年前的版本，接口改了但 API 文档没动，架构为什么这么设计只有当事人记得。这个技能把技术写作拆解成可执行的流程：先判断受众（开发者、使用者、运维、贡献者），再确定文档类型，然后按类型套用对应的写作规范与模板——文档字符串要写清参数、返回值、异常和示例；README 必须包含安装、快速入门、功能、开发、测试、贡献、许可证；ADR 要写清上下文、决策、后果与被否决的替代方案；更新日志要按语义化版本分组为新增、更改、修复、移除、安全。

“一键安装”的思路与步骤

所谓“一键安装”，本质是把这个技能挂载到你的 AI 编程环境里，之后每次对话都能复用同一套文档写作规范，不必反复交代“请用 Google 风格写 docstring”。通用流程如下：

确认前置条件：你的 AI 编程助手或 Agent 平台支持“技能/Skill”机制；当前工作区已能正常读取项目代码（技能依赖读取、搜索、全局匹配来理解代码库结构）。
找到技能入口：在平台的技能市场、技能目录或配置文件中搜索技能英文名 documentation 或技能ID 13508，具体入口名称与位置以官方说明为准。
执行安装/启用：按平台提供的方式完成添加（一键安装按钮、配置文件声明或命令行添加均有可能），命令形式与参数以官方说明为准，本技能详情未提供固定安装命令。
验证是否生效：安装后新开一次会话，输入“帮我给当前项目写一份 README”或“为这个函数补 JSDoc 注释”。如果 AI 能按“受众 → 文档类型 → 模板 → 示例”的结构回应，并主动追问项目名称、安装方式等必要信息，说明技能已生效。
固化到团队流程：把它写进团队规范，例如“每次合并新功能 PR 前，先让 documentation 技能生成更新日志条目和接口说明”，让文档与代码同步更新成为默认动作。

2. 该技能的主要功能和特点

代码级文档：按语言惯例生成 docstring/doc comment（JSDoc、rustdoc、pydoc 等），记录目的、参数、返回值、异常，语言支持时包含类型信息，并为复杂函数提供使用示例。
内联注释的“为什么”原则：明确要求注释解释“为什么”而不是“是什么”，用于标注复杂算法、业务规则、已知限制与待办事项，并保持与代码同步。
API 参考文档：覆盖所有公共端点/方法，包含请求与响应格式及示例、认证与授权、错误响应与状态码、速率限制与分页、版本信息。
README 规范化：给出必要章节清单（项目名 + 一行描述、安装、快速入门、功能、开发、测试、贡献、许可证）与最佳实践（重要信息前置、清晰标题、徽章、可运行示例、链接详细文档）。
ADR 架构决策记录：用“上下文 / 决策 / 后果 / 考虑的替代方案 / 状态”五段式，把“我们为什么这么选”沉淀下来，状态支持提议、接受、弃用、被取代。
更新日志生成：遵循语义化版本与常规提交，按新增、更改、修复、移除、安全分组，链接问题与 PR，突出破坏性变更，使用现在时表述。
技术写作方法论内置：清晰度（短句、一次一个想法、首次出现定义术语）、结构（一致标题层级、列表与表格）、可访问性（少行话、主动语态、配图表与代码块）。
开箱即用的模板库：README 模板、ADR 模板、更新日志模板、API 端点文档模板（含请求参数表、成功响应、错误码表）、Python/Rust 文档示例、内联注释“好与坏”对照示例。
常见问题规避清单：避免记录应私有的实现细节、避免重复代码已表达的内容、避免模糊措辞、避免文档与代码脱节、避免孤立文档。

和普通工具比强在哪？JSDoc、Sphinx、rustdoc 这类工具负责“把注释渲染成网页”，但不会替你判断“该写什么、写给谁看、写到什么颗粒度”。这个技能的差异点在于它先做受众与文档类型评估，再产出内容，遵循的是技术写作方法论（覆盖清晰度、结构、可访问性），还能跨文档类型保持一致性——README 的快速入门、API 文档的示例、更新日志的条目天然互相对齐。

3. 如何使用该技能？

以下是通用使用流程，具体调用入口与命令以官方说明为准：

第 1 步：明确受众与文档类型

不要一上来就说“写文档”，先告诉它读者是谁、用途是什么。示例输入：

这个仓库是一个 Python 数据同步库，读者是第一次使用的数据工程师。请先评估现有文档缺口，再给出补齐清单。

技能会据此判断受众（开发者/用户/运维/贡献者）、所需文档类型，并审阅现有文档查找差距与不一致。

第 2 步：从代码文档开始

示例输入：

请为 sync/billing.py 中的 calculate_invoice 函数补写 Google 风格 docstring，包含参数、返回值、异常和两个可运行示例。

预期输出：符合该语言惯例的文档块，参数含类型与约束说明，异常分条列出，示例为可实际运行的调用。技能会遵循示例中“参数：weight、destination、express；返回：Decimal；引发：ValueError、InvalidDestinationError”的结构。

第 3 步：生成或重写 README

示例输入：

按标准模板重写 README，必须包含：项目名 + 一行描述、安装、快速入门、核心功能、开发与测试、贡献指南、许可证。快速入门示例要能直接跑通。

预期输出：结构化 Markdown，重要信息前置、标题清晰、含可运行代码示例与指向详细文档的链接。

第 4 步：补 API 文档

示例输入：

为 POST /api/v1/users 写接口文档，包含认证要求、请求体字段表、成功响应示例、错误码表（至少覆盖参数校验失败、邮箱已存在、权限不足）。

预期输出：包含端点、认证、请求体字段表（字段/类型/是否必需/描述）、示例请求与 201 响应、错误响应状态码与错误码表的完整章节。

第 5 步：沉淀架构决策与更新日志

示例输入：

我们决定用事件溯源做审计追踪，替代原来的原地更新。请写一份 ADR，并同步在更新日志里加一条“新增”。

预期输出：ADR 含状态、日期、上下文、决策、后果（积极与消极分开）、被否决的替代方案及理由；更新日志条目按“新增/更改/修复”分组，引用相关议题编号。

第 6 步：验收交付成果

按技能给出的六条交付标准自查：覆盖是否完整（公共 API、配置项、工作流）、示例是否可运行、结构是否清晰（长文有目录）、是否与当前代码行为一致、是否匹配目标读者水平、文件名与标题是否利于检索。

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
documentation（技术文档管理Skill）	全层级技术文档的 AI 写作与维护助手	文档字符串、内联注释、API 参考、README、ADR、更新日志、写作规范与模板	需在支持技能机制的 AI 环境中启用，安装方式以官方说明为准；零额外配置即可对话调用	项目文档从 0 到 1 补齐、遗留项目文档翻新、接口交付文档	优势：跨文档类型一致、内置受众评估与模板、能解释“为什么”。不足：需人工把关事实与代码行为是否一致
文档生成工具链（如 JSDoc、Sphinx、rustdoc）	注释渲染与静态站点生成	从源码注释解析生成 HTML/站点，交叉引用	需安装依赖、配置构建流程、编写主题	已写好注释、需要发布 API 站点的成熟项目	优势：确定性高、可进 CI。不足：不生成内容，注释缺失时产出为空
文档站点框架（如 Docusaurus、Mintlify 类方案）	面向产品/开发者文档的建站框架	版本化、导航、搜索、主题定制	需搭建工程与部署流水线	需要长期运营的公开文档站	优势：呈现与检索体验好。不足：解决“怎么展示”，不解决“写什么”
通用大模型对话	通用文本生成	任意文本问答与写作	直接对话即可	临时写一段说明、润色文案	优势：门槛最低。不足：缺少固定文档规范与模板，风格不稳定，容易漏掉错误码、边界情况等要素

选型建议：注释渲染与站点框架解决“发布与展示”，本技能解决“内容生产与维护”，两者是上下游关系而非替代关系——先用技能把注释和文档内容补齐，再交给生成工具与站点框架发布，效果最好。

5. 该技能的典型应用场景与实际体验情况

场景一：接手遗留系统的新成员

痛点：代码能跑，但没有任何文档，新人只能靠读源码猜业务规则。使用方式：让技能先扫描目录结构与关键模块，输出“代码库结构与模式说明 + 关键模块内联注释补充建议 + README 重建”。实际体验：上手难度低，只要描述清楚“读者是谁”，产出结构就比较可用；注意点是要人工确认它总结的业务规则是否与真实行为一致，尤其是历史遗留的特殊分支。

场景二：后端团队的接口交付

痛点：接口改了但文档没改，前端和调用方反复来问。使用方式：每完成一个端点，就让技能生成含认证、请求字段表、成功响应示例、错误码表的标准章节。实际体验：错误码表的补充是明显加分项，很多团队自己写文档时最容易漏掉 400/409/403 这类分支；注意点是一次别让它写十几个接口，分批产出更容易校对。

场景三：技术负责人的架构决策沉淀

痛点：半年后没人记得“为什么不用数据库触发器做审计”。使用方式：用 ADR 五段式把上下文、决策、后果、被否决方案写清楚，并在更新日志中留痕。实际体验：这是该技能差异化最明显的能力——多数工具不管“决策记录”，而它能强制你把“被拒绝的方案及原因”写出来；注意点是决策背景需要你主动提供，信息越具体，ADR 越有价值。

场景四：开源项目的持续维护

痛点：README 长期停留在初版，更新日志靠提交记录硬凑。使用方式：按语义化版本定期生成更新日志条目，按新增/更改/修复/移除/安全分组，并同步修订 README 的快速入门示例。实际体验：模板化产出让风格高度统一，长期维护成本明显下降；注意点是发布前务必跑一遍示例代码，技能本身也把“测试你的示例”列为最佳实践。

6. 该技能能为用户带来的价值

效率提升：把“从空白页开始写文档”变成“审核并微调一份成型草稿”。README、接口文档、更新日志、ADR 都有现成结构，省下的主要是构思结构与回忆规范的时间。
门槛降低：不懂 JSDoc 与 rustdoc 的写法差异、不确定 ADR 该写哪几段、不知道更新日志怎么分组——这些“隐性规范”被内置进技能，新人和非专职文档人员也能产出合格文档。
质量下限抬高：通过强制覆盖错误响应、边界条件、异常与替代方案，减少“只写顺利流程”的常见缺陷；通过统一标题层级与主动语态，让文档可扫描、可检索。
长期可维护：ADR 让决策可追溯，更新日志让变更可回溯，内联注释解释“为什么”让后人不必反复考古。这些资产在人员流动时价值最高。
协作对齐：文档成为团队共享的事实来源，减少“口头解释—重复解释”的沟通成本，也让代码评审有据可依。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

A：在支持技能机制的 AI 环境中搜索技能英文名 documentation 或技能ID 13508，按平台提供的方式启用即可，具体入口、命令与计费方式以官方说明为准，本技能详情未包含定价信息。安装后建议先用“给这个函数补注释”这类小任务验证是否生效。

Q2：它会不会自动改坏我的代码？

A：从技能声明的工具权限看，它只使用读取、搜索、全局匹配、编辑、写入五类工具，工作范围集中在注释与文档文件，不涉及执行、构建或部署。稳妥做法是：先在分支上让它批量补注释，再用代码评审确认改动仅限注释与文档。

Q3：它和 JSDoc、Sphinx、Docusaurus 这些工具是什么关系？

A：互补关系。生成工具和站点框架负责“把已有内容渲染成可浏览的文档站”，本技能负责“把内容写出来并保持规范”。实践中先用技能补齐注释、API 章节、README 与更新日志，再交给生成工具发布，链路最顺。

Q4：适合谁用？小项目有必要吗？

A：最适合三类人：维护开源或个人项目的开发者、需要对外交付接口的后端团队、需要沉淀架构决策的技术负责人。小项目同样受益——README 与更新日志是最低成本、最高回报的两份文档，一次生成即可长期迭代。

Q5：能让它写中文文档吗？

A：可以。技能的核心是文档方法论与结构（受众评估、模板、写作原则），语言由你的指令决定，直接说明“用简体中文撰写，术语首次出现时给出英文原文”即可；同时建议约定专有名词与命令保持原文，避免翻译后无法执行。