生成组件文档Skill：让新组件的文档一键对齐团队既有规范
- 它解决什么问题：新组件写完了，文档却没人写、写得散、风格不统一——这个技能让 AI 按照仓库里已有的文档范式，自动产出结构完整、风格一致的组件文档。
- 核心工作方式：先读
docs文件夹里已有的同类文档（如button.md、accordion.md）学习格式，再参考crates/story/src/stories中同名故事实现理解真实用法，最后按固定结构输出文档。 - 产出结构固定：组件描述与用途、属性/API 文档、使用示例、视觉示例（如适用），四块内容一次到位。
- 一个细节很加分：API 参考部分会使用 Markdown
code块，并链接到 docs.rs，让读者能直接跳到真实 API 定义。 - 适用人群：组件库维护者、设计系统团队、前端/客户端开发者、开源项目贡献者。
该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：生成组件文档Skill 技能英文名：generate-component-documentation 技能ID：13284
这个技能要解决的，是组件开发流程里那个"最后 10% 却最容易被跳过"的环节：给新写的组件补文档。在真实项目里，组件代码往往已经合并、已经被业务方调用，但文档还停留在"待补充"状态；即便有人补，也常常出现格式各异、属性漏写、示例跑不通的情况。久而久之，docs 目录就变成了风格拼盘。
生成组件文档Skill 的思路不是"凭空写一篇文档"，而是先向仓库学习：它会参考 docs 文件夹中已有的文档风格，比如 button.md、accordion.md 的章节顺序与写法；再参考 crates/story/src/stories 中同名故事（story）的真实实现，理解组件实际暴露的属性与用法；最后在 API 参考处使用 Markdown code 块，并在适用时链接到 docs.rs，指向组件的真实 API 定义。这样产出的文档既能"读起来像同一套体系"，又能"对得上代码"。
一键安装的思路与步骤
第一步：确认安装前提。
你需要在一个可以访问技能的市场/技能管理中心里操作，并且当前工作区里已经存在该组件的代码仓库（至少包含 docs 目录与 crates/story/src/stories 目录），否则技能缺少参考样本，效果会打折扣。具体支持的客户端与版本要求，以官方说明为准。
第二步：通过技能入口一键安装。
在技能市场中搜索技能英文名 generate-component-documentation，或直接以技能ID 13284 定位，找到对应条目后点击安装/启用即可。安装入口的具体位置（命令行工具、IDE 插件还是 Web 端技能面板）与是否需要登录授权，以官方说明为准。
第三步：验证是否生效。 安装完成后，不要直接拿正式组件试水，建议先在对话中提一个明确的请求，例如：
“请按照
docs/button.md的风格，为docs下还没有文档的DatePicker组件生成文档，实现参考crates/story/src/stories中的同名故事。”
如果返回结果出现了"组件描述与用途、属性/API 文档、使用示例、视觉示例"这几块结构，并且引用了 docs 中的既有风格与故事实现，就说明技能已被正确触发。若没有触发，可以显式说出技能名或技能ID再试一次。安装命令、鉴权方式与调用参数等细节，均以官方说明为准。
该技能的主要功能和特点
- 遵循现有文档模式：技能会主动读取
docs文件夹中已有的组件文档（例如button.md、accordion.md），复用其章节结构、标题层级与行文习惯，保证新文档与旧文档"看起来是一套人写的"。 - 参考真实实现而非猜测：文档内容基于
crates/story/src/stories中同名故事实现来编写，属性名、默认值、用法路径都有代码依据，避免 AI "想当然"编造 API。 - API 参考可点击：在适用场景下使用 Markdown
code块呈现类型、属性与方法，并链接到 docs.rs，读者可以一键跳到真实 API 定义页核对。 - 固定四段式产出：组件描述和用途、属性/API 文档、使用示例、视觉示例（如果适用），覆盖了组件文档最常被追问的全部信息。
- 和普通写作工具比强在哪：通用写作工具只能"按你的描述写文档"，需要你手动把组件信息喂给它；这个技能把"找风格样本、找实现依据、找 API 出处"这三件费时的事变成了自动动作，你只需要点名组件。
如何使用该技能？
步骤 1：定位待写文档的组件。
打开你的组件仓库，确认目标组件在 docs 目录下确实没有文档，或文档处于待更新状态。记下组件名，例如 DatePicker。
步骤 2：确认参考样本存在。
检查 docs 文件夹里是否有可参考的同级文档（如 button.md、accordion.md），并确认 crates/story/src/stories 中存在同名故事实现。这两处是技能的主要信息来源。
步骤 3：发起请求，把"风格、实现、组件名"三点说清楚。 推荐使用这样的输入示例：
“为
DatePicker组件生成文档。请遵循docs文件夹中button.md、accordion.md的文档风格；实现细节参考crates/story/src/stories中的同名故事；API 部分请使用 Markdowncode块，并链接到 docs.rs 上的对应条目。”
步骤 4：阅读输出并核对四块内容。 正常情况下输出应包含：
- 组件描述和用途——这个组件是什么、什么时候该用；
- 属性/API 文档——属性名、类型、用途说明；
- 使用示例——可直接参考的代码片段；
- 视觉示例（如果适用）——对组件外观与状态的说明。
步骤 5：人工校对后落盘。
重点核对三处：属性名是否与代码一致、示例代码是否能在当前版本跑通、docs.rs 链接是否指向正确的组件路径。确认无误后写入 docs 目录，与既有文档并排放置。
步骤 6（可选）：批量补齐历史欠账。
对多个长期缺文档的组件，可以逐个发起同样的请求，统一采用同一份参考风格，快速把 docs 目录的文档水位拉齐。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 生成组件文档Skill | 面向仓库上下文的组件文档生成技能 | 学习 docs 既有风格、参考 crates/story/src/stories 同名故事、API 链接 docs.rs、四段式固定产出 |
需在技能入口安装启用（以官方说明为准），并要求仓库存在参考目录 | 组件库、设计系统持续迭代、需要文档风格统一 | 优势：风格一致、有代码依据、产出结构完整；不足：依赖仓库内已有参考样本，首次建仓时需要先有示范文档 |
| 人工手写 Markdown 文档 | 传统方式 | 完全由开发者撰写与维护 | 零工具门槛，但时间成本高 | 组件数量少、文档要求极高定制化 | 优势：最灵活；不足：易拖延、易漏属性、多人协作时风格漂移 |
| 自动 API 文档抽取工具（如 rustdoc 等） | 从源码注释生成 API 参考 | 抽取类型签名、注释生成 API 页面 | 需配置构建与注释规范 | 纯 API 索引、需要强一致的类型说明 | 优势：与代码零偏差；不足：缺少使用示例、缺少"什么时候用"的说明，可读性偏弱 |
| 通用 AI 对话助手 | 通用文本生成 | 按用户输入写任意文档 | 无安装门槛 | 临时写一段说明、非仓库上下文场景 | 优势：通用灵活；不足：不了解本仓库风格与故事实现，容易臆造属性，需要大量人工喂料 |
从对比可以看出，生成组件文档Skill 的位置很清晰：它介于"纯自动抽取"与"纯人工撰写"之间，用仓库里已有的风格与实现作为约束条件，既拿到了自动化的速度，又保住了文档的一致性与准确性。
该技能的典型应用场景与实际体验情况
场景一：组件库开发者新增了一个组件变体。
角色：组件库维护者。痛点是新组件合了代码，但 docs 目录里还是一片空白，评审时被反复追问"文档呢"。使用方式：在提交 PR 前，点名组件名与参考文档，一次性拿到四段式文档草稿，补齐后再提 PR。实际体验：上手几乎没有学习成本，关键是说清"参考哪份文档"和"参考哪个故事实现"；产出后仍建议人工核对默认值，因为文档质量取决于参考样本的质量。
场景二：设计系统团队要统一文档风格。
角色：设计系统负责人。痛点是以往文档由不同人接力撰写，button.md 与 accordion.md 的章节顺序、标题层级都不一样。使用方式：先把最规范的两三份文档沉淀为"参考范本"，之后所有新组件文档都以它们为风格来源。实际体验：风格一致性提升明显，但前提是范本本身足够规范——技能会忠实地复制风格，包括缺点。
场景三：新人接手历史组件，需要补文档。
角色：新加入团队的开发者。痛点是看不懂老组件怎么用，也不好意思一直问同事。使用方式：让技能参考 crates/story/src/stories 里的同名故事实现来写文档，等于让 AI 帮忙把"代码里的用法"翻译成"文档里的话"。实际体验：对理解组件属性帮助很大，尤其是故事实现里已经覆盖了典型用例；建议把生成的示例代码实际跑一遍再入库。
场景四：开源项目接收外部贡献。
角色：开源维护者。痛点是外部 PR 常常只改代码不写文档。使用方式：在贡献指南里写明"新增组件请使用该技能生成文档，参考 docs 中既有风格"。实际体验：降低了贡献者的写作门槛，也让 Review 时有了明确的对齐基准；注意公开仓库中生成的 docs.rs 链接要指向正确的 crate 路径。
该技能能为用户带来的价值
第一，把"要不要写文档"变成"校对文档"。 过去写一份组件文档，需要翻代码、找示例、对齐格式，动辄占用半小时以上；现在最耗时的部分由技能完成，人只需要做最后的事实核对。对于组件数量多、迭代快的团队，这个时间差会在每新增一个组件时重复出现。
第二，降低文档写作的门槛。 很多开发者并非不愿写，而是不知道该怎么组织——先讲属性还是先讲示例？标题层级用几级？技能直接给出与既有文档同构的结构，写作从"创作"降级为"填空"。
第三，保住长期一致性。 文档的价值在于可预期：读者打开任何一份组件文档，都知道描述在哪、属性表在哪、示例在哪。技能以 docs 中已有文档为模式来源，等于把这种可预期性固化下来。
第四，让文档与代码保持可追溯。 参考 crates/story/src/stories 的同名故事实现、API 部分链接 docs.rs，让文档中的每一处说明都能追回到真实代码，减少"文档写的是旧版 API"这类经典问题。
第五，提升协作与评审效率。 有了统一的文档产出，Code Review 时可以直接比对结构与内容，而不是每次重新讨论"文档该怎么写"。
常见问题 FAQ
Q1：这个技能怎么安装？
在技能市场或技能管理入口中搜索英文名 generate-component-documentation，或用技能ID 13284 定位条目，点击安装/启用即可。具体的安装命令、支持的客户端版本与鉴权方式，以官方说明为准。
Q2：使用这个技能收费吗？ 技能本身是否收费、是否包含在所属平台的订阅权益内，取决于平台的计费策略，请以官方说明为准。从成本角度看，它主要消耗的是模型调用额度，通常远低于人工撰写同等文档的时间成本。
Q3：它会不会编造组件属性和默认值？
技能的编写依据是 crates/story/src/stories 中的同名故事实现与 docs 中已有文档，因此具备较强的代码依据；但当仓库中缺少对应故事实现时，准确度会下降。建议始终在产出后人工核对属性名与示例代码，并对 API 部分确认 docs.rs 链接指向正确路径。
Q4：适合谁用？
最适合正在维护组件库或设计系统的团队、需要为历史组件补文档的开发者，以及希望统一开源项目文档风格的项目维护者。如果你的项目还没有 docs 目录或任何示范文档，建议先手写一到两份规范文档作为参考样本，再引入技能。
Q5：和自动 API 文档生成工具、通用 AI 助手怎么选？ 如果只需要一份与代码完全同步的 API 索引，自动抽取类工具更合适；如果只是临时写一段说明，通用 AI 助手更快。如果你需要的是"有使用示例、有用途说明、并且和团队既有文档风格一致"的组件文档，生成组件文档Skill 更贴合这一需求。三者也可以组合：用抽取工具保证 API 准确，用本技能补齐用法与示例。