文档化技能Skill：代码一改，文档自动跟上
核心结论速览
- 技能定位：
documentation（文档化技能Skill，技能ID：11820）是一个"实施成功后立即补文档"的收尾型技能，把文档维护变成开发流程的固定环节，而不是事后的负担。 - 能力范围：覆盖 README、API 文档、代码文档（JSDoc/类型注解/内联注释）、变更日志四类产出，并提供对应的模板文件。
- 差异化亮点：自带文档检查清单与最佳实践准则，不是"随便写点说明"，而是把准确性、示例有效性、链接有效性都纳入检查。
- 交付方式：可直接给出结构化文档内容，也可调用技能内的生成脚本
scripts/generate-docs.py批量产出，并把成果沉淀到docs/reviews/documentation-{session}.md。 - 适配人群：独立开发者、小团队后端/前端工程师、需要对外交付接口文档的技术负责人，以及长期被"文档永远落后于代码"困扰的项目维护者。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
基本信息
- 技能中文名：文档化技能Skill
- 技能英文名：documentation
- 技能ID：11820
- 触发时机（技能描述原文）：从代码生成和更新文档，在成功实施后使用。
它解决什么问题
绝大多数项目的文档不是"不会写"，而是"没人收尾"。一个功能开发完成、测试通过、代码合入之后，文档往往还停留在上个版本：README 里的安装步骤对不上新的依赖，API 端点增加后接口文档没同步，用户升级时遇到不兼容改动却找不到迁移说明。文档化技能Skill 的思路很直接——把"写文档"这一步嵌入到"实施成功"之后，让 AI 在它刚刚读完、改完代码的上下文里顺手把文档补齐，避免二次回忆和上下文丢失。
"一键安装"AI 技能提升效率的思路
所谓"一键安装 AI 技能"，本质是把一段经过沉淀的领域知识（模板、标准、检查清单、脚本）作为可复用能力挂载给 AI 助手，让它按固定规范输出，而不是每次重新"教"它怎么写文档。通用步骤通常是：
- 确认前提：你所使用的 AI 编程助手/技能平台支持安装外部 Skill（不同平台的入口差异较大，具体支持范围与版本要求以官方说明为准）。
- 找到入口：一般位于平台的"技能市场"“插件/扩展”"Skill 管理"或设置页中的技能列表处，可通过技能ID
11820或英文名documentation检索。 - 完成安装：按平台指引添加该技能（部分平台需要登录账号或授权工作区，具体流程以官方说明为准）。
- 验证是否生效：在对话中提出一个明确的收尾型请求，例如"本次改动已完成，请按文档化技能为这个模块补充 README 与 JSDoc"，然后观察 AI 是否按模板结构输出、是否附上文档检查清单。若输出包含 README/API/变更日志的分类结构、检查清单勾选项，即可确认技能已生效。
- 确认失败时：检查技能是否处于启用状态、当前会话是否绑定了对应工作区、以及项目根目录下是否存在模板文件路径（
templates/、scripts/）；如仍无响应，按平台文档排查，以官方说明为准。
需要提醒的是：安装只是"挂载能力"，真正的效率提升来自把它固定在流程里——每次功能实施成功后立即调用一次，而不是攒到月底"补文档周"。
2. 该技能的主要功能和特点
四类文档全覆盖
| 文档类型 | 覆盖内容 |
|---|---|
| README | 项目概述、安装说明、快速入门指南、配置选项、贡献指南 |
| API 文档 | 端点描述、HTTP 方法、请求/响应格式、认证要求、错误代码 |
| 代码文档 | JSDoc/docstrings、内联注释（解释"为什么"而非"什么"）、类型注解、示例用法 |
| 变更日志 | 版本历史、重大更改、迁移步骤、弃用通知 |
三套现成模板
技能内置了可直接复用的模板文件：templates/readme-template.md（README 模板）、templates/api-doc-template.md（API 文档模板）、templates/changelog-template.md（变更日志模板）。这意味着输出不是自由发挥，而是结构统一、团队可对齐的文档骨架。
统一的 JSDoc 标准
技能规定了注释写法规范：先写函数功能的简要描述，再依次标注 @param（含参数名与说明）、@returns（返回值描述）、@throws（异常场景，例如验证失败时）、@example（可运行的调用示例）。这让"注释质量"从个人习惯变成可检查的团队标准。
可执行的文档检查清单
这是该技能与"让 AI 随便写段说明"最大的区别。清单包含：README 是否最新、API 端点是否已文档化、代码示例是否有效、变更日志是否已更新、公共 API 上是否有 JSDoc、链接是否有效、拼写/语法是否正确。七项逐一核对，等于给文档加了一道"上线前自检"。
最佳实践准则：做与不做
- 做：保持示例最新；文档化重大更改；使用一致格式；包含常见用例；解释"为什么"而不仅仅是"如何"。
- 不做：文档化实现细节；让示例过时；跳过错误场景；使用行话而不解释；假设读者知识。
这套准则解决了文档最常见的两种失败：一是写成"给自己看的实现备忘"，二是默认读者什么都知道，导致新人无从下手。
脚本化生成与成果沉淀
技能提供了文档生成脚本 scripts/generate-docs.py，可运行以批量产出文档；同时规定报告保存位置为 docs/reviews/documentation-{session}.md，让每次文档工作的产出有迹可循、可按会话追溯。
3. 如何使用该技能？
以下是基于技能内容整理的推荐使用流程，可直接照做。
步骤 1：在"实施成功后"触发
技能明确定义了使用时机——成功实施之后。因此不要一开始就让它写文档，而是等功能或接口改完、测试通过后调用。
步骤 2：给出明确的上下文与范围
调用示例（对话式）：
“本次改动已完成：新增
POST /api/orders/cancel接口，支持按订单号取消，需要Authorization头认证，参数校验失败返回 400，订单不存在返回 404。请按文档化技能补齐 API 文档与变更日志。”
范围越具体（改了哪些文件、新增了哪些端点、有哪些错误码），输出质量越高。
步骤 3：按文档类型分派模板
- 需要项目说明 → 要求套用
templates/readme-template.md，输出项目概述、安装说明、快速入门指南、配置选项、贡献指南。 - 需要接口说明 → 套用
templates/api-doc-template.md，输出端点描述、HTTP 方法、请求/响应格式、认证要求、错误代码。 - 需要版本记录 → 套用
templates/changelog-template.md，输出版本历史、重大更改、迁移步骤、弃用通知。
步骤 4：要求按 JSDoc 标准补代码文档
输入示例：
“请为
cancelOrder(orderId, options)补 JSDoc：简述功能，标注@param、@returns、@throws（参数校验失败时抛出校验错误），并给一个@example调用示例。”
预期输出形如：一段功能简述 + @param {string} name 说明 + @param {Options} options 说明 + @returns {Result} 返回值说明 + @throws {ValidationError} 校验失败说明 + @example 示例代码。同时内联注释应解释"为什么这样做"，而不是复述代码在做什么。
步骤 5：运行生成脚本（可选）
若项目已包含技能的脚本文件，可运行 scripts/generate-docs.py 批量生成/刷新文档。脚本的参数、依赖与运行环境以官方说明为准。
步骤 6：走一遍文档检查清单
请 AI 逐项核对并按勾选形式输出结果：README 最新 / API 端点已文档化 / 代码示例有效 / 变更日志已更新 / 公共 API 上有 JSDoc / 链接有效 / 拼写语法正确。未通过的项要求它给出具体修正建议。
步骤 7：确认成果落盘位置
最终报告保存到 docs/reviews/documentation-{session}.md，{session} 对应本次会话标识，便于后续回溯"这次改动当时是怎么写文档的"。
输出说明：正常输出为结构化的 Markdown 文档 + 一份检查清单结果 + 一份落盘的报告路径说明；如果输入信息不足（例如缺失错误码定义），技能会表现为提出澄清问题，而不是凭空编造——这一点在接口文档场景尤其重要。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| documentation（文档化技能Skill） | 实施后收尾型文档技能 | README/API/代码文档/变更日志四类产出，三套模板、JSDoc 标准、七项检查清单、生成脚本 | 需在支持 Skill 的平台安装，具体入口与要求以官方说明为准 | 功能上线后补文档、接口变更同步、发版写变更日志 | 优势：有规范、有清单、有落盘路径，输出结构统一；不足：依赖调用者对改动范围的准确描述，仍需人工复核 |
| 通用 AI 对话（不装技能） | 临时性文本生成 | 自由撰写任意文档段落 | 门槛最低，打开即用 | 一次性写个说明、润色文案 | 优势：零配置；不足：结构每次都不一样，容易漏掉错误码、迁移步骤等关键项，也无检查清单 |
| 文档生成工具（如 JSDoc/TypeDoc 类工具） | 代码注释驱动的自动化文档 | 从注释与类型注解提取 API 文档 | 需配置构建流程、依赖与产物目录 | 公共库 API 手册、类型声明文档 | 优势：与代码强绑定，自动化程度高；不足：只管"从注释抽文档"，不产出 README 叙事与变更日志，注释缺失时输出为空壳 |
| 静态站点/文档平台（如文档站生成器类方案） | 文档托管与展示 | 站点构建、导航、搜索、版本化 | 需搭建工程与部署流程 | 对外开发者文档站 | 优势：展示效果好、可搜索；不足：解决"怎么展示"，不解决"内容从哪来、准不准" |
从对比看，文档化技能Skill 的位置很清晰：它不抢"展示层"（那属于文档站工具），也不只做"注释抽取"（那属于 JSDoc 类工具），而是补齐内容生产与质量校验这一段——尤其是变更日志与迁移步骤这种最容易没人写的部分。
5. 该技能的典型应用场景与实际体验情况
场景一：新功能上线后的 README 补全
角色：独立开发者或小团队主程。痛点：项目能跑，但 README 还是三个月前写的，安装步骤、配置选项全对不上。使用方式：功能实施成功后直接说"本次新增了缓存配置项，请按 README 模板更新概述、安装说明、配置选项与快速入门"。实际体验：上手几乎零成本，输出结构完整；注意点是必须告诉它真实的配置项名称与默认值，否则它会写出"看起来合理但不存在"的字段。
场景二：接口迭代中的 API 文档同步
角色：后端工程师，被前端反复追问"这个接口参数到底怎么传"。痛点：接口加了认证要求和新错误码，但没人更新文档。使用方式：把端点、HTTP 方法、请求/响应格式、认证要求、错误代码逐项交代，让它按 API 文档模板输出。实际体验：对"错误码 + 认证要求"这类容易被忽略的字段覆盖得很好，因为模板里就要求写；注意事项是错误码必须由你提供，AI 不会替你定义业务语义。
场景三：版本发布与变更日志、迁移步骤
角色：项目维护者，用户升级后报错却找不到说明。痛点：不兼容改动只存在于提交记录里。使用方式：让它按变更日志模板输出本条版本的历史、重大更改、迁移步骤、弃用通知。实际体验：这是该技能价值感最强的场景——"迁移步骤"这一项通常没人主动写，但模板强制它出现；建议同时要求它显式标注弃用项，避免用户在下一个版本才"突然"发现问题。
场景四：代码评审前补 JSDoc 与类型注解
角色：提交 PR 的开发者。痛点：公共 API 没有注释，评审者只能读实现猜意图。使用方式：要求按 JSDoc 标准为公共函数补描述、@param、@returns、@throws、@example，并按"解释为什么而不是什么"的原则处理内联注释。实际体验：上手难度低，效果直接体现在可读性上；注意别让它把实现细节写进文档——技能的最佳实践里明确"不做：文档化实现细节"。
整体体验小结：上手难度低（自然语言调用即可），最大价值在于"结构化 + 可自检"，最大的坑在于"输入含糊则输出含糊"。把它当成一位严格执行文档规范、但需要你提供事实素材的同事，体验最好。
6. 该技能能为用户带来的价值
效率收益：把"回忆改动 → 组织语言 → 对齐格式 → 自检遗漏"四步压缩成一次对话。文档从"攒着补"变成"每次收尾顺手做"，单次改动往往只需几分钟，且省掉了跨天回忆上下文的时间成本。
质量收益：七项检查清单把"文档准不准"从主观感受变成可核对项。尤其是"代码示例有效"“链接有效”"公共 API 上有 JSDoc"这三项，直接对应文档最常见的失效点——示例跑不通、链接早已 404、核心接口无注释。
门槛收益：不熟悉文档规范的新人，无需先读一堆写作指南，模板与最佳实践已经把"该怎么写"固化下来；不擅长写英文文档或技术写作的开发者，也能稳定产出结构完整的说明。
长期价值：文档沉淀在 docs/reviews/documentation-{session}.md，形成与开发会话对应的可追溯记录。对新成员来说，一份最新 README 加一份带迁移步骤的变更日志，意味着上手时间从"问三个人"缩短到"读两页纸"；对项目来说，这直接减少重复答疑与升级事故。
7. 常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
A：在支持 AI 技能/Skill 的平台中通过技能ID 11820 或英文名 documentation 检索并启用即可。不同平台的安装入口、账号要求与是否收费差异较大，本文不提供具体命令与价格，请以官方说明为准。判断是否安装成功的最快方法：让它按文档化技能补一份 README，看输出是否带模板结构和检查清单。
Q2：它能自动读我的整个仓库然后一键生成所有文档吗？
A：从技能定义看，它的定位是"从代码生成和更新文档，在成功实施后使用"，并提供了生成脚本 scripts/generate-docs.py 与模板体系。但它的输出质量取决于你提供的改动范围信息；不要期待零输入的"全自动魔法"，把它放在具体改动之后调用，效果最稳。
Q3：和直接让 AI 写文档有什么区别？ A：区别在"结构"和"校验"。通用对话写出来的文档每次格式都不同，且极易漏掉错误码、迁移步骤、弃用通知这类关键项；文档化技能Skill 强制走三套模板 + JSDoc 标准 + 七项检查清单，产物是可对齐、可复核的。简单说：一个是"写点东西"，一个是"按规范交付"。
Q4：适合谁用？不适合谁？ A：适合接口有对外契约的项目、需要发版维护变更日志的项目、以及带新人的团队。若你的项目是纯一次性脚本、没有对外接口也不需要他人维护，投入产出比就不高。另外它不替代文档站工具——展示层仍需要专门的平台。
Q5：会不会写出"看起来很对但其实不存在"的文档？
A：技能的最佳实践里明确"不假设读者知识"“不让示例过时”，并要求示例有效、链接有效。但业务事实（如错误码语义、配置默认值）必须由你提供。实操建议：把它生成的 @example 实际跑一遍，并逐项过检查清单，风险就能压到很低。