Storybook 文档审查工作流docs-review Skill 的五种模式、六类文档类型与七步诊断流程docs-review是 Storybook 官方仓库中面向 AI Agent 的文档技能skill它把 Storybook 文档/docs目录下的 MDX 页面的审查、改进、重写、新写与规划沉淀为一套可复用的诊断-干预工作流。读完本文你将掌握该技能的适用范围与触发条件、五种干预模式maintenance/improve/rewrite/author/strategy的路由规则、六种文档类型doc type的形状规范、七个质量维度、十个典型反模式以及yarn fmt:write/yarn docs:check验证环节在 scripts/docs/check-docs.ts 中的实际实现逻辑。技能定位仓库中的位置与文件结构技能入口位于 .claude/skills/docs-review/SKILL.md。该文件在仓库中是一个单行指针内容指向共享的 .agents/skills/docs-review/SKILL.md即技能真正的主体文件这种.claude指针 .agents实体的布局让同一个技能可以被不同 Agent 工具复用。.agents/skills/docs-review/目录下的完整结构如下.agents/skills/docs-review/ ├── SKILL.md # 技能主体作用域、触发条件、7 步工作流、交接规则 └── references/ ├── docs-principles.md # 北极星目标、双读者要求、7 个质量维度 ├── docs-strategy.md # 5 种模式、6 种文档类型、干预阈值、拆分判据 ├── docs-antipatterns.md # 10 个诊断模式与纠正手段 └── storybook-style.md # 文风、MDX 组件、frontmatter、格式化与校验规则四个参考文件按职责严格分工这一点在 SKILL.md 的 Ownership Rules 中被显式约束参考文件职责Owns加载时机docs-principles.md北极星目标、质量维度、双读者要求总是——最先读docs-strategy.md模式、文档类型、干预阈值、页面形状指引总是——第二先读docs-antipatterns.md诊断模式与纠正手段诊断出草稿薄弱或晦涩时storybook-style.md编辑风格、MDX 组件、frontmatter、格式化、校验规则maintenance模式或作为编辑类模式的最后一遍归属规则Ownership Rules确保三个文件互不越界策略类参考文件principles/strategy/antipatterns不负责格式与组件规则storybook-style.md不负责文档类型识别与干预逻辑SKILL.md本身只负责工作流编排与交接handoffs。适用范围与触发条件技能的作用域Scope非常明确只适用于/docs下的文档文件以及文档拥有的片段文件docs/_snippets/。仓库中/docs是一个按主题组织的 MDX 文档站get-started、writing-stories、writing-tests、configure 等目录加上 docs/_snippets/ 中数百个被CodeSnippets组件引用的代码片段而docs/_snippets/里的文件如csf-3-example-starter.md、main-config-typical.md正是页面示例代码的真实来源。对于/docs之外的非文档文件业务代码、配置、/docs之外的 README该技能明确声明不适用。触发时机Use This Skill When有三类被要求审查、改进、重写或撰写/docs中的文档被就页面结构、文档类型、目标读者或内容策略征求建议被要求修复/docs中的格式、风格或合规问题。同时定义了轻触Light Touch情形避免流程过重请求只是琐碎的语法或错别字修复不需要完整诊断页面结构本就健全只需少量编辑性清理。七步工作流前四步诊断后三步行动技能主体要求对每个请求按固定序列执行七步其中第 1–4 步是诊断第 5–7 步是行动。第 1 步确定请求目标模式路由先读用户请求把它映射到一种模式请求模式模式Fix links, callouts, formatting修链接、提示框、格式maintenanceMake this clearer、improve this page写得更清楚、改进此页improveThis doc is a mess; rewrite it这文档一团糟重写rewriteDraft docs for feature X为功能 X 起草文档authorWhat kind of page should this be?这应该是什么类型的页面strategyReview this doc未指明具体要求的审查一下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 中的质量维度依次评估Intent clarity意图清晰度Audience fit读者匹配度Information shape信息形状Conceptual clarity概念清晰度Task usability任务可用性Example quality示例质量Economy经济性对于次级章节维度 3信息形状和维度 5任务可用性按该次级章节自身类型的标准评估而非页面主类型其余维度按全页评估。如果页面出现结构性薄弱的迹象则加载 docs-antipatterns.md 对照常见反模式。第 4 步选择干预级别依据 docs-strategy.md 中的阈值无结构问题、只有轻微风格问题 →maintenance结构尚可但框架、顺序或示例偏弱 →improve结构与页面职责不匹配 →rewrite页面尚不存在 →author用户要的是建议而非修改 →strategy两条硬性规则Hard rule硬规则当草稿结构薄弱时不要停留在句子级编辑。要重排、拆分、替换示例或直接重写页面形状。Split/escalation rule拆分/升级规则如果页面的主职责不清晰、或同时承担多个互不相关的职责先切换到strategy模式或建议拆页再去打磨。结构良好的次级章节见下文不构成拆页理由。第 5 步执行修改或规划按所选模式执行maintenance应用编辑与合规修复以 storybook-style.md 为主指引improve强化框架、顺序、解释与示例保持页面身份不变最后用 style 规则收口rewrite实质性替换页面——保留健全的内容其余丢弃或重构最后用 style 规则收口author以主文档类型的形状为指引从零写页面最后用 style 规则收口strategy只返回规划产物planning artifact包含目标读者、页面职责、主文档类型、推荐大纲、拆分/合并建议如适用、保留清单值得保留的内容并且不编辑文件、不运行验证。补充授权编辑文档时如果示例质量依赖片段文件允许顺带改进docs/_snippets/中的文档片段。第 6 步应用 Storybook 风格对所有编辑类模式maintenance/improve/rewrite/author若尚未加载 storybook-style.md 则加载应用视角、语气、标题、链接、组件、frontmatter 规则这一步永远位于结构工作与编辑工作之后绝不作为第一遍。第 7 步验证仅编辑类模式执行yarn fmt:write yarn docs:check修复yarn docs:check报告的所有错误然后再次运行以确认通过。strategy模式或未编辑任何文件时不运行验证。这两条命令在仓库中都有明确落点见下文验证的源码实现一节根 package.json 定义docs:check为yarn --cwd scripts docs:check、fmt:write为oxfmt .。五种模式触发条件与产物对比docs-strategy.md 对五种模式给出了何时使用 输出的完整定义模式何时使用输出maintenance页面结构健全只需编辑、合规或格式修复清理风格、组件、frontmatter、格式运行验证improve页面能看但可以更清晰、组织更好、示例更好在保持页面身份的前提下强化框架、顺序、解释与示例运行验证rewrite局部编辑无法救活因为形状、框架或范围根本性错误实质性替换页面保留健全内容其余丢弃或重构运行验证author需要新建页面或从笔记/纲要补全草稿以合适的文档类型为指导从零撰写运行验证strategy用户要规划而非修改——页面职责分析、大纲、拆分/合并建议返回规划产物读者、页面职责、主类型、推荐大纲、拆分/合并建议、保留清单不运行格式化与验证模式选择规则Mode Selection Rules用户明确点名模式如 rewrite this时照用用户只说 review this doc 时走混合行为strategy类请求或明显薄弱草稿先批评critique-first普通清理/改进请求先改improve-first请求含糊improve this doc、make this better时默认improve诊断发现结构薄弱时从improve升级到rewrite——当问题出在页面形状上不要停留在句子级编辑。六种文档类型与页面形状每种页面有且仅有一个主文档类型主类型决定页面的整体形状与评估标准。各类型的页面职责Page Job与形状Shape文档类型页面职责形状concept帮读者理解某物是什么、为何重要定义 → 心智模型 → 与其他概念的关系 → 何时使用task帮读者完成具体目标目标陈述 → 前置条件 → 有序步骤 → 预期结果 → 故障排查reference帮读者查询具体细节选项、API、配置简短引言 → 结构化条目名称、类型、默认值、描述→ 有用的示例troubleshooting帮读者诊断并修复问题症状 → 原因 → 修复 → 验证migration帮读者从一个版本或方案迁移到另一个改了什么 → 为什么 → 逐步迁移路径 → 破坏性变更 → 验证decision guide帮读者在选项间做选择决策背景 → 带权衡的选项 → 推荐 → 日后如何切换Overview 页面的处理/docs中的概览页如章节着陆页没有特殊类型——默认按concept处理多数概览在解释一个功能域及其组成部分的关系当页面以比较为主时如选择 builder 或 renderer改用decision guide。常见次级章节组合是惯例上已组织良好的类型搭配不构成反模式主类型常见次级章节示例taskreference— 末尾的 API 选项或配置表Configure visual tests 任务页以配置选项表收尾tasktroubleshooting— 步骤之后的常见错误Set up Storybook 任务页以 Common issues 收尾concepttask— 简短 how-to 展示概念Decorators 概念页含一段 Add a decorator 步骤conceptreference— 相关 API 面汇总表Controls 概念页以注解类型表收尾migrationtroubleshooting— 迁移期已知问题迁移指南以 If you see error X 条目收尾decision guidereference— 选项对比表Choose a builder 页含详细功能对比表一个次级章节组织良好当且仅当它同时满足(1) 拥有能提示内容切换的清晰标题如 API reference、Troubleshooting、Quick start(2) 遵循其自身类型的形状reference 章节用结构化条目而非散文(3) 支撑主页面职责而非引入无关话题。何时算真正的超载需要拆页或转strategy页面没有清晰的主类型——两种及以上类型以大致均等的权重争夺主导页面在一个标题下覆盖多个互不相关的功能某个次级章节已膨胀到可以独立成页粗略信号超过主内容长度的一半概念性散文与步骤式指令在整个页面中交错混杂而非被隔离进各自章节。反过来结构良好的次级章节不算超载末尾带配置表的 task 页、带简短步骤的 concept 页都是正常形态。七个质量维度与双读者要求docs-principles.md 定义了文档工作的第一性原理北极星North Star好的文档要降低读者的time-to-understanding理解时间或time-to-success成功时间。每一次编辑、重构或重写都应让页面更靠近这两个结果之一。双读者要求Dual-Reader RequirementStorybook 文档必须同时服务两类读者——前端开发者快速扫描答案、示例和可立即执行的步骤LLM 与检索系统解析文档以获取准确、结构化的信息支撑 AI 辅助工作流。原则是先为人写为两者组织Write for the human first. Structure for both.。这正是整个技能结构优先于文笔的设计动因。七个质量维度从最结构性排到最表层——先修列表顶部再打磨底部Intent Clarity意图清晰度页面在前两句话内说明它能帮读者做什么或理解什么读者或检索系统无需滚动即可判断页面是否相关。Audience Fit读者匹配度假设正确的前置知识水平不过度解释 Web 基础也不低估读者对 Storybook 特有行为的陌生程度。Information Shape信息形状围绕读者的任务或问题组织而非围绕功能实现组织章节遵循逻辑递进context → action → result或 definition → usage → edge cases含其他类型次级章节的页面每个章节遵循其自身类型的递进。Conceptual Clarity概念清晰度抽象概念落到具体术语概念间关系显式化读者能建立心智模型而不只是跟着步骤走。Task Usability任务可用性步骤完整、有序、可验证默认路径在前变体与边缘情况在后。Example Quality示例质量代码示例代表真实用法而非最小到具有误导性示例要展示页面所讲的概念或任务而不只是语法有效。Economy经济性每句话都要挣得自己的位置删掉冗余解释、填充性过渡与铺垫性开头。简洁服务于读者但不以牺牲清晰为代价。十个文档反模式诊断对照表docs-antipatterns.md 提供十个问题—识别信号—纠正手段三元组用于第 3 步的结构诊断#反模式识别信号纠正手段1Background-First Opening背景先行开头首个标题或段落先谈历史、动机、抽象问题才说功能是什么开头直接讲它是什么 你能用它做什么背景移到后面或内联到支撑具体论点的处所2Unseparated Mixed Doc Types类型混杂不分区同一章节内交替出现概念段落、步骤、无标题的配置表确定主类型次级内容提取为带独立标题的章节并遵循其类型形状大到可独立的建议拆页3Edge Cases Before the Default Path边缘案例抢跑第一个代码示例处理非默认场景警告 callout 出现在基础用法之前默认路径先行例外与高级配置后置。例外必须先于行动的安危类警告4Technically Valid but Weak Examples技术正确但弱示例示例用foo/bar占位名、只展示最小必需 props、脱离任何真实语境换成反映真实用法模式的示例真实的组件名、props、数据让读者可移植到自己的项目5Late Term Definition术语定义迟到decorator、loader、play function 等 Storybook 术语在前几段被反复使用定义却在后文才出现首次使用时定义或加链接若页面正是讲这个术语开头句就应定义它6Feature List Without Action无行动指向的功能罗列以 X supports Y、You can also Z 罗列能力不连接读者目标或决策用 Use X when you need Y 的方式把能力框定在读者任务或决策周围7Buried Procedure Outcome埋没的操作结果步骤走到最后一步就结束没有 you should now see… 之类的结果陈述在步骤之后陈述预期结果最好展示成功长什么样截图、终端输出、行为描述8Preserving Weak Structure Because It Is Clean因干净而保留弱结构语法正确、格式一致、链接不断但读者要读完全页才能找到所需章节按实现细节而非读者需求排序升级到improve或rewrite——干净的格式不是保留无效页面形状的理由9Overexplaining Basics过度解释基础用段落解释通用 Web 开发概念同时只用一句话带过没有类比可循的 Storybook 特有行为默认读者掌握 HTML/CSS/JS/组件基础把解释预算投给 Storybook 特有概念、行为与心智模型10Tightening Prose When Rewrite Is Actually Needed该重写却在收紧句子一轮句子级收紧后页面仍不能清晰履行其职责读者体验没有实质性改善退到页面级重新诊断形状错了就重构或重写不要继续打磨注意第 2 条中的反例说明主类型清晰、次级章节各自成区各有标题且遵循自身形状的页面不算此反模式——这体现了技能对结构良好的混合与混乱的混合的区分。Storybook 风格规范编辑收尾的规则集storybook-style.md 只负责编辑与格式层面明确声明不拥有文档类型识别、模式路由或干预逻辑。核心规则如下视角与语气默认第二人称 you代表 Storybook 说话时用 we如 We recommend…或同行走流程时用 Lets…禁用第一人称单数 I 和把读者称为 the user 的第三人称。语气专业但对话化、鼓励但不过度、方案导向强调能做什么、直接自信We recommend… 而非无谓含糊。指令措辞步骤式指令用祈使句Run this command、Create a new file可选或替代方案用建议式You can also…、You might want to…引入代码示例用陈述式上下文To define the args of a single story, use theargsCSF story key:。缩略语自然使用 dont、wont、its 等以强化对话感但警告类 callout 等需要精确性的严肃语境中避免。限定语Hedgingcan 表能力may/might 表条件性结果should 表建议must 表要求typically/generally 描述有例外的常见模式陈述直白时不要加限定。用词避免 simply、just、easily、obviously 这类弱化词powerful/useful/great 节制使用具体优于模糊renders in under 2 seconds 好过 renders quickly。标题H1 只能来自 frontmattertitle正文中绝不写# Heading[auto]可机器校验H2/H3 用 sentence case不跳级[auto]。链接内部链接用指向.mdx文件的相对路径text外部链接必须完整 URL 且包在 markdown 链接语法中禁止裸 URL[auto]。组件规则Callout必须指定variantinfo或warning裸Callout不允许图标映射固定 提示、 实验/预览特性、ℹ️ 补充上下文、 公告配合title、♿ 可访问性、⚠️ 必须配variantwarning而非info[auto]variantpositive非标准应改用info[auto]。If renderer{[...]}/If notRenderer{[...]}条件渲染CodeSnippets path... /的 path 必须存在于docs/_snippets/[auto]另有Video、YouTubeCallout嵌入组件。frontmatter值不加引号除非含、|、:、逗号等特殊字符需要时用单引号sidebar.title仅在与title不同时才写。文件给出的正例/反例对比# 正确title 与 sidebar.title 不同时才声明 sidebar.title --- title: Component Story Format (CSF) sidebar: title: CSF order: 2 ---# 错误重复引用、无谓的 sidebar.title 与引号 --- title: ArgTypes sidebar: title: ArgTypes order: 2 ---块级 JSX块级元素Callout、details、If等前后要空行元素内容前后也要空行summary例外details开标签与summary之间不空行内容不缩进代码块、嵌套列表项除外。storybook-style.md 中给出了完整的正确/错误 MDX 排版对照示例值得在编辑前直接参照。验证的源码实现yarn docs:check到底检查什么风格规范中大量规则带有[auto]与[oxfmt]标记其含义在 storybook-style.md 的 Validation 一节说明确切[auto]项由yarn docs:check检查实现在 scripts/docs/check-docs.ts[oxfmt]项由yarn fmt:write即oxfmt .见根 package.json处理。这两类工具都是末段验证——应在结构与编辑工作完成后再运行而不是第一步。从 scripts/docs/check-docs.ts 的源码可以确认docs:check的实际检查项该脚本经 scripts/package.json 中的jiti ./docs/check-docs.ts执行相对链接校验checkRelativeLinks扫描所有.mdx文件的相对链接验证目标文件存在带锚点时还会解析目标文件的标题 slug 集合验证#fragment对应的标题真实存在。跨版本链接形如../../../release-8-6/docs/...指向其他 release 分支的文档被显式豁免因为无法在本地验证片段路径校验checkCodeSnippetPaths对每个CodeSnippets path... /检查docs/_snippets/下对应文件是否存在——这解释了为何技能允许编辑docs/_snippets/里的文件示例代码与文档页面的耦合是通过这些片段文件实现的弃用组件检查checkDeprecatedIfRenderer检测仍在使用的IfRenderer提示改用IfCallout variant 检查checkCalloutVariant对Callout开标签支持跨行收集到检查是否包含variant缺失则报错与风格规范中裸Callout不允许的规则一一对应。每条错误都携带file/line/ 具体message可直接定位修复位置——这正是第 7 步修复后重跑确认能落地的机制基础。交接Handoffs边界技能主体最后定义了与相邻流程的交接边界PR 创建本技能不自动创建 PR。如果用户要求含 PR 在内的端到端执行交接给pr技能.claude/skills/pr/SKILL.md片段文件本技能在示例质量需要时可以编辑docs/_snippets/中的文件但不拥有非文档目的的片段创建职责。实践落点一次完整调用该技能的执行顺序把上述规则压缩成可执行的检查单任何对/docs文档的修改请求都应按此顺序走判定请求模式维护/改进/重写/撰写/规划模糊时默认improve识别主文档类型并列出遵循其他形状的次级章节按七维度诊断意图 → 读者 → 形状 → 概念 → 任务 → 示例 → 经济性结构薄弱时对照十个反模式定干预级别结构问题触发升级improve→rewrite或转strategy拆页建议执行修改strategy只产出规划产物读者、页面职责、主类型、大纲、拆分/合并建议、保留清单最后一遍套 style 规则语气、标题、链接、Callout variant、frontmatter、块级 JSX 空行编辑类模式才运行yarn fmt:write与yarn docs:check修复后重跑至通过。这套技能的价值在于把文档好坏从主观感受变成了可枚举的判据模式 × 类型 × 维度 × 反模式 × 风格规则并用仓库内真实的校验脚本兜底——文档既服务人读也结构化地服务 LLM 与检索系统这正是 Storybook 文档工程自身的核心主张。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
