generating-documentation（文档生成）Skill 能生成哪些技术文档？

文档生成Skill：一个技能打通 API 文档、代码文档、文档站点、架构决策与图表

核心结论速览

文档生成Skill（英文名 generating-documentation，技能ID 13424） 是一款面向开发者的技术文档生产技能，覆盖 API 文档、代码文档、文档站点、架构决策记录（ADR）和系统图表五个层面。
它内置了一套「文档层面选择 + 工具选型」的决策框架，能帮你在 OpenAPI/Swagger、TypeDoc/Sphinx/godoc/rustdoc、Docusaurus/MkDocs、MADR 模板、Mermaid/PlantUML/D2 之间快速做对选择，而不是先纠结半天工具。
技能自带可复用的模板与示例（如 templates/openapi-template.yaml、templates/adr-template.md），并给出 CI/CD 自动化文档管道的写法，让文档真正做到「文档即代码」。
它解决的核心痛点是文档分散、文档漂移、工具选型靠猜，把过去需要翻十几篇博客才能凑齐的文档体系，收敛成一次对话即可落地的方案。
适合后端/API 团队、开源库维护者、架构师、平台工程与 DevRel 同学使用，零学习成本上手，产出可版本化的工程化文档资产。

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

技能基本信息

项目	内容
中文名	文档生成Skill
英文名	generating-documentation
技能ID	13424
定位	面向开发者的一站式技术文档生成与规范落地技能

它到底解决什么问题？

技术文档的真实困境往往不是「不会写」，而是「不知道写哪一层、用什么工具写、怎么保证不过时」。一个项目里，API 契约散落在零散的接口文档中，代码注释没人管，架构决策只留在某次口头会议里，架构图画完三个月就和代码对不上了。文档生成Skill 把技术文档拆成五个清晰层面：

层面1：API 文档 —— OpenAPI/Swagger 规范，通过 Swagger UI、Redoc 或 Scalar 渲染；
层面2：代码文档 —— 从代码注释生成，如 TypeDoc（TypeScript）、Sphinx（Python）、godoc（Go）、rustdoc（Rust）；
层面3：文档站点 —— 完整指南与教程，如 Docusaurus、MkDocs；
层面4：架构决策 —— 使用 MADR 模板格式的 ADR；
层面5：图表 —— 可视化系统架构与数据流，如 Mermaid、PlantUML、D2。

「一键安装」的思路与步骤

AI 技能的安装本质上是在你常用的 AI 编码助手或技能平台中「启用」该能力，从而在对话里直接调用它，而不需要在每个项目里重复搭建工具链。通用流程如下：

第一步：确认安装前提。 你需要在支持 AI 技能扩展的客户端或平台中工作（例如具备技能市场/技能管理面板的 AI 编程助手环境），并已能正常发起对话。具体支持范围以官方说明为准。
第二步：找到技能入口。 打开平台的技能市场、插件中心或技能管理面板，用中文名「文档生成」、英文名 generating-documentation 或技能ID 13424 搜索定位。不同平台的入口位置与检索方式以官方说明为准。
第三步：一键安装并启用。 点击安装/启用按钮完成装载，在需要时于会话中显式唤起该技能（例如说明「使用文档生成技能为当前项目生成 OpenAPI 规范」）。安装命令、授权方式与是否收费均以官方说明为准。
第四步：验证是否生效。 用一个最小任务测试，例如让助手「按技能里的决策框架判断：我们对外提供 REST API，应该从哪个文档层面开始」——若它能按五层模型作答，并指向 references/api-documentation.md 这类参考文档，说明已生效。
第五步：确认产出可用。 再让它生成一个 OpenAPI 3.1 骨架，检查是否包含 openapi、info、servers、paths、components、security 等标准字段，字段齐全即代表技能工作正常。

这套「一键安装 + 一次验证」的做法，省下的不只是搭工具的时间，更是团队在文档方案上反复拉扯的沟通成本。

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

五层文档体系全覆盖。 API 文档、代码文档、文档站点、架构决策记录、系统图表一个技能全部囊括，避免在多个工具和多个技能之间来回切换。
内置快速决策框架。 通过「为外部消费者提供 API？→层面1」「为维护者提供代码？→层面2」这样的提问式分支，直接把模糊需求翻译成明确的文档动作，新手也能一次选对。
工具选择矩阵。 用一张表给出 Docusaurus 与 MkDocs Material、Swagger UI 与 Redoc、TypeDoc 与 Sphinx、Mermaid 与 PlantUML 的适用边界，减少选型试错。
开箱即用的模板与示例。 提供 templates/adr-template.md（MADR 模板）、templates/openapi-template.yaml（OpenAPI 3.1 入门）以及 OpenAPI、TypeScript、Python、ADR、图表的完整示例目录。
可直接落地的代码与命令。 涵盖 npx typedoc --entryPoints src/index.ts --out docs、sphinx-quickstart docs、npx create-docusaurus@latest my-website classic、mkdocs new my-project 等真实可用命令。
CI/CD 文档自动化。 给出 GitHub Actions 工作流范例，覆盖生成 API 文档、生成代码文档、构建站点、部署到 GitHub Pages 的完整链路。
区分「设计优先」与「代码优先」。 明确指出新 API 建议设计优先、存量 API 建议代码优先，并分别说明优缺点，避免一刀切。
沉淀最佳实践与常见陷阱。 包括文档即代码、单一来源、自动化生成、包含可运行示例、验证规范、随版本化等八条实践，以及文档漂移、过度文档化、碎片化文档、无示例四大坑。
与其它技能协同。 可与 api-patterns、building-ci-pipelines、testing-strategies、sdk-design 等技能串联，形成从设计到文档再到 SDK 的完整闭环。

和普通工具比强在哪？ 普通文档工具只解决「怎么写某一个层面的文档」，而这个技能解决的是「你应该写哪些层面的文档、用什么写、怎么自动写、怎么保证不过时」——它是文档体系的编排者，而不是单一的文档生成器。

3. 如何使用该技能？

步骤一：说清目标，让技能帮你定位层面。 把你的场景直接描述给助手，例如：「我们有一个面向外部开发者的 REST API，另外还有 TypeScript SDK，需要文档站点和几张架构图。」技能会依据五层模型给出组合方案：层面1 + 层面2 + 层面3 + 层面5。

步骤二：生成 API 规范骨架。 请求：「用文档生成技能输出一份用户 API 的 OpenAPI 3.1 规范，包含 GET /users/{userId} 和 Bearer JWT 鉴权。」典型输出结构如下：

openapi: 3.1.0
info:
  title: 用户API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users/{userId}:
    get:
      summary: 获取用户
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required: [id, email, name]
      properties:
        id: { type: string }
        email: { type: string, format: email }
        name: { type: string }
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

随后可按技能建议用 Swagger UI（交互测试）、Redoc（专业只读）或 Scalar（现代设计）渲染。

步骤三：生成代码文档并执行命令。 TypeScript 项目请求规范注释示例，技能会给出符合 TSDoc 风格的写法（含 @param、@returns、@example），再执行：

npm install -D typedoc
npx typedoc --entryPoints src/index.ts --out docs

Python 项目则用如下文档字符串风格（含 Args / Returns / Example），再执行：

pip install sphinx sphinx-rtd-theme
sphinx-quickstart docs
cd docs && make html

步骤四：搭建文档站点。 按需选择 Docusaurus（React 系、功能丰富）或 MkDocs Material（Python 系、简洁美观），技能会给出 docusaurus.config.js 或 mkdocs.yml 的基础配置，包括导航、搜索插件与主题特性。

步骤五：写架构决策记录（ADR）。 直接说「记录一次数据库选型决策」，技能会按 MADR 模板输出：状态、决策者、日期、背景与问题陈述、决策驱动因素、考虑选项、决策结果、正面后果与负面后果。这也正是技能中示例「使用 PostgreSQL 作为主数据库」的结构。

步骤六：画图。 请求「画一个登录流程的时序图」，技能输出 Mermaid 代码，可直接在 GitHub、Docusaurus、MkDocs 中渲染：

sequenceDiagram
    User->>Frontend: 点击“登录”
    Frontend->>API: POST /auth/login
    API->>Database: 验证凭证
    Database-->>API: 用户找到
    API-->>Frontend: JWT令牌
    Frontend->>User: 重定向到仪表板

步骤七：接入 CI/CD 与验证。 让技能生成文档流水线，实现「推送到 main 分支即自动生成 API 文档、代码文档、构建站点并部署到 GitHub Pages」，并按技能建议做 Markdown 检查与规范校验。

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
文档生成Skill（generating-documentation）	五层技术文档体系编排器	五层文档模型、决策框架、工具矩阵、模板与示例、CI/CD 方案、图表生成	低：在支持技能的平台搜索启用即可，无需额外部署	需要成体系落地文档的团队；API + 库 + 架构决策混合项目	优势：覆盖面最全、决策指引清晰、开箱有模板；不足：具体渲染与托管仍需依赖 Docusaurus、Sphinx 等底层工具
单一文档工具（如仅用 TypeDoc 或仅用 Sphinx）	针对某一种语言的代码文档生成	从注释生成静态 HTML 文档	中：需自行安装配置、写配置文件	单语言库、内部代码说明	优势：专注、成熟、生态完善；不足：只管代码文档一层，API、站点、ADR、图表需另找工具
文档站点框架（Docusaurus / MkDocs）	文档门户与内容组织	版本化、导航、搜索、主题、部署	中：需 Node 或 Python 环境与配置维护	产品手册、开源项目官网、教程体系	优势：呈现效果好、支持版本化与多语言；不足：本身不生成 API/代码文档，需要插件拼装
手工维护 Markdown + 人工评审	纯人工文档流程	自由撰写、人工更新	低门槛、高维护成本	需求不稳定的小型项目、临时说明	优势：无工具学习成本、灵活；不足：极易文档漂移，缺乏规范校验，规模一大就碎片化

从对比可以看出：底层工具解决「怎么渲染」，文档生成Skill 解决「写什么、用什么写、怎么自动写」。二者并非替代关系，而是「决策层 + 执行层」的互补关系。

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

场景一：后端团队对外提供 REST API

角色：后端工程师 / API 负责人。
痛点：接口文档靠人工维护的表格，字段与真实实现经常对不上，联调阶段反复解释。
使用方式：先用技能生成 OpenAPI 3.1 规范骨架，再选择「设计优先」路线——先写规范、与前端和利益相关者评审、生成服务器存根、最后实现处理程序。渲染层按需选 Swagger UI（便于测试）或 Redoc（对外的专业展示）。
实际体验：上手几乎零成本，技能给出的示例直接可改成自己项目；要注意的是规范编写本身比较冗长，建议只对核心接口先落地，逐步补齐。

场景二：开源库维护者补全代码文档

角色：开源项目维护者。
痛点：README 写得很漂亮，但函数级文档缺失，使用者只能读源码。
使用方式：让技能分别给出 TSDoc 风格注释与 Python 文档字符串风格示例，再执行 TypeDoc 或 Sphinx 命令生成 docs 目录，并把生成步骤写进 CI。
实际体验：注释模板质量高，含可运行示例这一点对使用者非常友好；注意 Python 侧 sphinx-quickstart 需要交互式回答几个问题，建议提前约定好目录结构。

场景三：架构师记录关键决策

角色：架构师 / 技术负责人。
痛点：数据库选型、微服务拆分这类决策只有结论没有过程，半年后新人反复追问「为什么不用另一个」。
使用方式：按技能的判定标准，仅对技术选择、架构模式、有权衡的决策、需要团队对齐的事项写 ADR；命名、格式化这类琐碎决策不写。用 MADR 模板把背景、驱动因素、备选方案、正负面后果一次写清。
实际体验：模板结构非常实用，写完后能显著降低重复讨论；需注意 ADR 应是「一次性写定、长期留存」，不要在原文上反复改写结论。

场景四：平台团队搭建文档门户并自动化

角色：平台工程 / DevRel。
痛点：文档散落在 Wiki、README、接口平台三处，搜索不到、版本对不上。
使用方式：用 Docusaurus 或 MkDocs 搭统一站点，通过 OpenAPI 插件把 API 文档嵌入站点，再把「生成 API 文档 → 生成代码文档 → 构建站点 → 部署」写成 CI 工作流。
实际体验：技能给出的工作流结构清晰，照抄改造即可跑通；注意事项是生成物要纳入版本控制策略并随发布打版本，否则仍然会出现文档漂移。

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

提升效率：从「找方案」到「拿方案」。 过去搭建一套完整文档体系，需要分别研究 API 文档规范、代码文档工具、站点框架、ADR 模板和图表语法，耗时以天计；现在一次对话即可拿到成套方案与可执行命令，选型环节的时间成本被大幅压缩。
降低门槛：让非文档专家也能产出规范文档。 决策框架与工具矩阵把「隐性经验」显性化，新同学不必先成为文档专家，也能按五层模型判断该写什么、怎么开始。
减少返工：从源头抑制文档漂移。 通过「文档即代码、单一来源、自动化生成、CI 中验证」这套实践，把文档从一次性交付物变成随代码一起演进的资产。
提高协作质量：契约先行的开发节奏。 用 OpenAPI 规范约束前后端契约，配合 ADR 沉淀决策背景，可以明显减少联调期的反复沟通与「历史决策考古」。
长期价值：可版本化、可传承的工程资产。 文档随发布版本化、示例可运行、图表可渲染、决策可追溯，这些资产在人员流动时依然保值，新人上手曲线更平缓。
生态协同价值。 与 api-patterns、building-ci-pipelines、sdk-design 等技能组合后，可形成「API 设计 → 文档生成 → SDK 产出 → 流水线自动化」的完整开发闭环。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要我在项目里先装一堆工具吗？

不需要。安装方式是在支持 AI 技能的平台中搜索技能名「文档生成」、英文名 generating-documentation 或技能ID 13424，找到后一键启用即可，具体的入口位置与命令以官方说明为准。技能本身不需要你在项目里预装 TypeDoc、Sphinx 等工具，它负责给出方案、模板与命令，真正的执行仍由你所在项目的开发环境完成。

Q2：这个技能收费吗？

技能本身的计费方式取决于你所在平台的规则（例如是否需要订阅、是否按调用计费），这些信息以官方说明为准。需要区分的是：技能内推荐的开源文档工具（TypeDoc、Sphinx、Docusaurus、MkDocs、Mermaid 等）均为各自项目独立分发，其许可与使用条件同样以各项目官方说明为准。

Q3：它和直接问我用的 AI 助手「帮我写个 OpenAPI」有什么区别？

普通问答通常只给你一段文本；文档生成Skill 提供的是一套体系化路径：先判断你该写哪一层文档，再给出对应工具选型，再输出符合规范的模板、可运行命令、CI/CD 工作流，并附上最佳实践与常见陷阱提醒。区别在于它输出的不是「一段文档」，而是「一套可以长期维护的文档工程方案」。

Q4：适合谁用？小团队会不会太重？

它适合后端/API 团队、开源库维护者、架构师、平台工程与 DevRel 人员。小团队完全可以从单层切入——比如只做层面1 的 OpenAPI 规范，或只做层面2 的代码文档，不必一次上齐五层。技能内也明确提示避免「过度文档化」，应聚焦「为什么」而非显而易见的行为。

Q5：和 Docusaurus、Swagger UI 这些工具是竞品关系吗？该怎么选？

不是竞品，是上下游关系。Docusaurus、MkDocs、Swagger UI、Redoc、TypeDoc、Sphinx 属于「执行层」的渲染与生成工具，文档生成Skill 属于「决策与编排层」，帮你在这些工具中做出正确选择并组织成体系。实际用法是：先用技能确定层面和工具组合，再用具体工具完成生成与发布。若项目只需代码文档，直接上 TypeDoc/Sphinx 即可；若需要 API + 代码 + 站点 + 架构图的全套方案，就优先用技能做整体规划。