Storybook docs-review 技能详解：AI Agent 系统化评审与重写 /docs 文档的七步工作流

在 Storybook 仓库中，.agents/skills/docs-review/ 定义了一个面向 AI Agent 的文档评审技能（Skill）：当被要求审查、改进、重写或起草 /docs 下的文档时，Agent 会加载该技能，按照"诊断四步 + 执行三步"的固定工作流，从五个模式中选择干预级别，以六个文档类型和七个质量维度为标尺评估页面，最后以 storybook-style.md 的规则做风格收尾，并用 yarn docs:check 等命令完成机器校验。读完本文，你可以完整掌握这套技能的模式路由逻辑、文档类型判定方法、反模式诊断清单，以及与之配套的 MDX 写作规范与校验链路，并能在自己的文档仓库中复刻类似的 Agent 化文档治理流程。

技能定位与适用边界

该技能的入口文件是 .agents/skills/docs-review/SKILL.md，其 YAML frontmatter 声明了技能的名称与触发条件：

---
name: docs-review
description: Review, improve, rewrite, author, or plan Storybook documentation in /docs. Use this when asked to review docs, improve a page, rewrite documentation, draft new docs, or advise on docs strategy.
---

技能的作用域被明确限定为 /docs 下的文档文件，以及文档拥有的片段文件 docs/_snippets/ 中的条目。文档明确指出：不要对该范围外的文件（代码、配置、/docs 之外的 README）使用这个技能。

技能还规定了两种轻触模式（Light Touch）：

• 请求只是琐碎的语法或拼写修复，无需完整诊断；
• 页面结构本身已经健康，只需少量编辑层面的清理。

四个参考文件与职责划分

SKILL.md 本身只负责工作流与交接（workflow and handoffs），具体知识分散在 references/ 下的四个文件中，按需顺序加载：

文件	职责	加载时机
docs-principles.md	北极星目标、质量维度、双读者要求	总是——第一个读
docs-strategy.md	模式、文档类型、干预阈值、页面形态指导	总是——第二个读
docs-antipatterns.md	诊断模式与纠正动作	诊断薄弱或令人困惑的草稿时
storybook-style.md	编辑规范、MDX 组件、frontmatter、格式、校验规则	maintenance 模式下，或作为编辑类模式的最后一遍

三个文件的**归属规则（Ownership Rules）**保证了职责不重叠：

• 策略类参考文件不拥有格式或组件规则；
• storybook-style.md 不拥有文档类型或干预逻辑；
• SKILL.md 只拥有工作流与交接。

这种"单一事实来源"的拆分方式值得借鉴：策略文件回答"这个页面应该长什么样"，风格文件回答"这个页面应该怎么写"，入口文件回答"按什么顺序干活"。

七步工作流：诊断（1–4）与行动（5–7）

SKILL.md 要求每个请求都遵循固定顺序：步骤 1–4 是诊断，步骤 5–7 是行动。

步骤 1：确定请求的期望产出（模式路由）

读用户请求，把它映射到一个模式：

请求模式	模式
"修链接、callout、格式"	maintenance
"讲清楚一点"、"改进这个页面"	improve
"这文档一团糟，重写它"	rewrite
"为功能 X 起草文档"	author
"这类页面应该做成什么类型？"	strategy
"审查这份文档"（未指定）	hybrid——见下

Hybrid 行为：面对"review this doc"这类模糊请求：

• 如果草稿明显薄弱，或请求隐含规划意图 → critique-first（以诊断为主导）；
• 如果页面尚可，且请求隐含清理意图 → improve-first（以编辑为主导）。

默认值：含糊时默认 improve，而不是 maintenance。

步骤 2：确定主要文档类型

读页面，用 docs-strategy.md 中的文档类型分类，六种类型：

• concept —— 解释某物是什么、为何重要；
• task —— 带领读者完成一个目标；
• reference —— 选项、API 或配置的查询参考；
• troubleshooting —— 诊断并修复问题；
• migration —— 从一个版本或方案迁移到另一个；
• decision guide —— 在多个选项之间做选择。

规则是必须选定唯一的主类型，即使页面包含次要元素。选定后还要识别次要章节（secondary sections）——拥有独立标题、内容形态遵循另一种文档类型的章节，留给步骤 3 单独评估。

步骤 3：诊断草稿

按 docs-principles.md 中的七个质量维度依次评估（顺序即优先级，从最结构性到最表层）：

1. 意图清晰度（Intent Clarity）——前两句话就说明页面帮读者做什么；
2. 受众匹配（Audience Fit）——假设正确的前置知识水平；
3. 信息形态（Information Shape）——围绕读者的任务组织，而非围绕功能实现；
4. 概念清晰度（Conceptual Clarity）——抽象概念落到具体术语上，读者能建立心智模型；
5. 任务可用性（Task Usability）——步骤完整、有序、可验证，默认路径在前；
6. 示例质量（Example Quality）——示例代表真实用法，而非"最小可行"到产生误导；
7. 经济性（Economy）——每句话都值得存在，删掉冗余铺垫。

对次要章节，用第 3 维（信息形态）和第 5 维（任务可用性）按该章节自身的类型评估，而非按页面的主类型；其余维度全页适用。若页面出现结构性薄弱的迹象，则加载 docs-antipatterns.md 检查常见反模式。

步骤 4：选择干预级别

依据 docs-strategy.md 的阈值：

• 无结构问题、仅小风格问题 → maintenance
• 结构尚可，但框架、顺序或示例薄弱 → improve
• 结构与页面的职责不匹配 → rewrite
• 页面尚不存在 → author
• 用户要的是建议而非修改 → strategy

硬性规则：当草稿结构性薄弱时，不能止步于句子级编辑——要重排、拆分、替换示例或重写页面形态。

拆分/升级规则：如果页面的主导职责不清晰，或一个页面承载多个互不相关的职责，先切换到 strategy 模式或建议拆分页面，再谈润色。但结构良好的次要章节不构成拆分理由。

步骤 5：改进或规划（按模式执行）

• maintenance：应用编辑与合规修复，以 storybook-style.md 为主指南；
• improve：强化框架、顺序、解释与示例，保持页面身份，风格规则做最后一遍；
• rewrite：实质性替换页面，保留健康内容，丢弃或重构其余部分；
• author：从零写页面，以主文档类型的形态为骨架；
• strategy：返回一份规划产物，包含受众、页面职责、主文档类型、推荐大纲、拆分/合并建议（如适用）、保留清单（值得保留的内容），且不编辑文件、不运行校验。

编辑文档时，如果示例质量依赖片段文件，可以顺带改进 docs/_snippets/ 中的文件。

步骤 6：应用 Storybook 风格

对编辑类模式（maintenance、improve、rewrite、author）：

• 若尚未加载则加载 storybook-style.md；
• 应用语气、标题、链接、组件与 frontmatter 规则；
• 这一步永远在结构性与编辑性工作之后——绝不作为第一遍。

步骤 7：校验

仅编辑类模式执行：

yarn fmt:write
yarn docs:check

修复 yarn docs:check 报告的所有错误，然后再次运行确认。strategy 模式下或没有编辑任何文件时不得运行校验。

五个模式与六种文档类型

docs-strategy.md 对模式与模式选择规则做了更完整的定义。各模式及输出如下：

模式	使用时机	输出
maintenance	页面结构健康，只需编辑、合规或格式修复	清理风格、组件、frontmatter、格式，然后运行校验
improve	页面可用，但可以更清晰、组织更好、示例更好	在保持页面身份的前提下强化框架、顺序、解释与示例，然后运行校验
rewrite	局部编辑无法修复，因为形态、框架或范围根本性错误	实质性替换页面，保留健康内容，运行校验
author	需要创建新页面，或从笔记/简报完成草稿	以合适的文档类型为指导从零写页面，运行校验
strategy	用户要规划而非编辑	返回规划产物；不运行格式或校验

模式选择规则：用户显式点名模式（如"rewrite this"）就直接用；"review this doc"这类未指定请求走 hybrid 行为；含糊请求（"improve this doc"）默认 improve；诊断发现结构性薄弱时从 improve 升级到 rewrite。

文档类型各有固定形态（Shape）：

类型	页面职责	形态
concept	帮助读者理解某物是什么、为何重要	定义 → 心智模型 → 与其他概念的关系 → 何时使用
task	帮助读者完成具体目标	目标陈述 → 前置条件 → 有序步骤 → 预期结果 → 排障
reference	帮助读者查询具体细节（选项、API、配置）	简短引言 → 结构化条目（名称、类型、默认值、描述）→ 按需示例
troubleshooting	帮助读者诊断并修复问题	症状 → 原因 → 修复 → 验证
migration	帮助读者从一个版本/方案迁移到另一个	变更内容 → 原因 → 分步迁移路径 → 破坏性变更 → 验证
decision guide	帮助读者在选项间做选择	决策背景 → 带权衡的选项 → 建议 → 如何日后切换

概览页的处理：/docs 中的分区落地页没有特殊类型——默认 concept；当页面以比较为主（如选择 builder 或 renderer）时用 decision guide。

常见次要章节组合（约定俗成的良好搭配）：

主类型	常见次要章节	示例
task	reference——末尾的 API 选项或配置表	"配置视觉测试"任务页以配置选项表收尾
task	troubleshooting——步骤后的常见错误	"设置 Storybook"任务页以"常见问题"条目收尾
concept	task——展示概念的简短操作	"Decorators"概念页含简短的"添加装饰器"步骤
concept	reference——相关 API 面摘要表	"Controls"概念页以注解类型表收尾
migration	troubleshooting——迁移期间的已知问题	迁移指南以"如果你看到错误 X"条目收尾
decision guide	reference——选项对比表	"选择 builder"页面带详细功能对比表

次要章节结构良好需满足三点：有独立且提示内容切换的标题；遵循其类型的形态（如 reference 章节用结构化条目而非散文）；支撑主页职责而非引入无关主题。

真正的过载信号：页面没有清晰的主类型（两种及以上类型势均力敌地争夺主导权）；一个标题下覆盖多个不相关功能；某个次要章节大到可以独立成页（粗略信号：超过主内容长度的一半）；概念散文与步骤说明全文交错而不分节。

十个文档反模式

docs-antipatterns.md 给出了十种诊断模式，每种都包含"问题、如何识别、如何修复"三要素：

1. 背景先行开场（Background-First Opening）——页面先讲历史、动机、上下文，才告诉读者页面是关于什么的。修复：先讲这个东西是什么、读者能拿它做什么，背景挪到后面。
2. 混合文档类型未分离（Unseparated Mixed Doc Types）——解释性散文、步骤说明与参考表在同一节内交替出现。注意：有清晰主类型、次要章节各自独立分节并遵循各自形态的页面不算反模式。
3. 边界情况先于默认路径（Edge Cases Before the Default Path）——第一个代码示例就处理非默认场景。修复：默认路径打头，例外、异常与高级配置后置（例外：必须先于操作的安全警告）。
4. 技术正确但薄弱的示例（Technically Valid but Weak Examples）——示例语法正确但不代表真实用法，只有 foo/bar 占位名和最小 props。修复：换成反映真实用法的示例，用现实的组件名、props 和数据。
5. 术语定义过晚（Late Term Definition）——"decorator"、"loader"、"play function" 这类 Storybook 术语在开头出现多次，定义或链接却在后面。修复：首次使用时即定义或链接。
6. 只列功能却不帮读者行动或决策（Feature List Without Helping the Reader Act or Decide）——"X 支持 Y"式的罗列。修复：围绕读者任务组织能力描述，"需要 Y 时使用 X"优于"X 支持 Y"。
7. 埋没的操作结果（Buried Procedure Outcome）——任务页走完全程却从不说明完成后读者拥有什么。修复：在步骤后陈述预期结果，最好展示成功长什么样。
8. 因"整洁"而保留薄弱结构（Preserving Weak Structure Because It Is "Clean"）——语法正确、格式一致、链接无坏，但结构不服务读者；maintenance 遍会漏掉真问题。修复：升级到 improve 或 rewrite，干净的格式不是保留失效页面形态的理由。
9. 过度解释基础、欠解释 Storybook 特有行为（Overexplaining Basics While Underexplaining Storybook-Specific Behavior）——篇幅花在读者已知的通用 Web 概念上，却一笔带过真正令人困惑的 Storybook 特有行为。修复：假设读者懂 HTML/CSS/JS/组件，把解释空间投给 Storybook 特有的概念与心智模型。
10. 该重写却只在收紧散文（Tightening Prose When Rewrite Is Actually Needed）——句子级编辑后页面确实变短变干净，但读者体验没有实质改善。修复：退回到页面层面诊断，形态错了就重构或重写。

北极星目标与"双读者"要求

docs-principles.md 开篇给出整个技能的价值锚点：

好的文档降低读者的理解时间（time-to-understanding）或成功时间（time-to-success）。每一次编辑、重构或重写都应让页面更接近这两个结果之一。

更值得注意的是其中的双读者要求（Dual-Reader Requirement）：Storybook 文档必须同时服务两类受众——

1. 扫描答案、示例与可立即执行步骤的前端开发者；
2. 解析文档以获取准确结构化信息、用于 AI 辅助工作流的 LLM 与检索系统。

原则是"先为人类写作，结构上为两者兼顾"。这正是文档从"给人看的说明书"升级为"机器可读的知识源"这一趋势在工程规范中的落地。

风格收尾：storybook-style.md 的核心规则

storybook-style.md 拥有 Storybook 特有的编辑、MDX 组件、frontmatter 与校验规则。关键约束摘录：

视角与语气：默认第二人称 "you"；从 Storybook 角度发言用第一人称复数 "we"（如 "We recommend…"）；不用第一人称单数 "I"，也不把读者称为 "the user"。语气专业但会谈话——像对同事解释，而非教科书；解决导向、直接自信。

指令措辞：分步指令用祈使句（"Run this command"）；可选/替代方案用建议式（"You can also…"）；代码示例前的上下文用陈述句（"To define the args of a single story, use the args CSF story key:"），且引导句以冒号结尾。

缩略与措辞：自然使用缩写（don't、it's），但 callout 警告等严肃语境避免缩写；避免 "simply"、"just"、"easily"、"obviously" 这类弱化词；要具体——"renders in under 2 seconds" 优于 "renders quickly"。

标题与链接：H1 只通过 frontmatter 的 title 提供，正文禁止 # Heading（标注 [auto]，即由机器校验）；H2/H3 用句首大写式（sentence case）；不跳级；内部链接用相对 .mdx 路径。

自定义组件：

• <Callout> 必须显式指定 variant（"info" 或 "warning"），裸 <Callout> 不允许；variant="positive" 非标准，应用 variant="info"；⚠️ 图标必须配 variant="warning"；
• <CodeSnippets path="..." /> 的 path 必须存在于 docs/_snippets/（[auto] 校验）；
• 条件渲染用 <If renderer={[...]}> / <If notRenderer={[...]}>。

Frontmatter：值不加引号，除非含 &、|、:、逗号等需加引号的特殊字符（加引号时用单引号）；sidebar.title 与 title 相同时必须省略。

块级 JSX 排版：<Callout>、<details>、<If> 等元素前后必须空行；元素内部内容前后也空行（<summary> 是唯一例外，紧跟 <details> 开头标签）。

校验链路：从 Skill 到可执行脚本

SKILL.md 步骤 7 的两条命令在仓库中都有真实落点：

• package.json 定义了 "docs:check": "yarn --cwd scripts docs:check" 与 "fmt:write": "oxfmt ."；
• scripts/package.json 中 "docs:check" 进一步指向 jiti ./docs/check-docs.ts。

从源码结构看，scripts/docs/check-docs.ts 实现了 storybook-style.md 中标注 [auto] 的规则，例如：

• checkRelativeLinks() 扫描所有 .mdx 文件的相对链接，既验证目标文件存在（fs.access），也验证锚点片段在目标文件中标题 slug 集合中真实存在，并跳过指向 release-* 分支的跨版本链接（/^(?:\.\.\/)+release-[\w.-]+\//）；
• checkCodeSnippetPaths() 检查每处 <CodeSnippets path="..." /> 对应的 docs/_snippets/ 文件是否存在。

文件中还定义了 DeprecatedIfRendererError、CalloutVariantError、DocLineError 等错误接口，与风格文件中"⚠️ 必须配 variant="warning"""variant="positive" 非标准"等 [auto] 标注一一对应。这形成了一个闭环：风格文件声明规则 → 校验脚本机器执法 → Skill 要求 Agent 在编辑后运行并复跑直到零错误。

交接规则（Handoffs）

SKILL.md 结尾定义了两条边界：

• PR 创建：不自动创建 PR。若用户要求包含 PR 的端到端执行，交接给 pr 技能；
• 片段文件：当示例质量需要时，本技能可以编辑 docs/_snippets/ 中的文件，但不拥有面向非文档用途的片段创建。

小结

.agents/skills/docs-review/ 是 Storybook 把"文档评审"从个人经验固化为可执行流程的范例：入口文件只描述工作流，四个参考文件分别独占"为什么好、该长什么样、哪里写坏了、怎么写"，yarn docs:check（scripts/docs/check-docs.ts）把关键规则变成机器校验，配合"双读者"的北极星目标，使同一套标准既约束人类贡献者也约束 AI Agent。对于希望在自家仓库中引入 Agent 化文档治理的团队，这套"单一职责拆分 + 诊断/行动两阶段 + 校验收尾"的结构可以直接借鉴。