reviewing-user-guide

reviewing-user-guide — SKILL.md

**变体：**标准 · **使用时机：**将已完成的终端用户指南作为验收关卡进行评判——检查真实用户能否依据指南完成所有受支持的目标，并按照单一来源的 12 项条件标准进行评估，随后给出 VERDICT: approve|revise，并提供可执行的发现。

概述

此技能是终端用户指南编写/评判配对流程中的评审部分。评审者加载此技能时，手中已有一份完成的终端用户指南——面向消费者的帮助文档，供使用产品的人（通常不具备技术背景）阅读，以实现其目标（入门教程、面向任务的操作指南、概念说明、面向终端用户的功能/配置参考、故障排除/常见问题解答和术语表）。此技能依据一个问题评判指南：真实产品用户能否仅凭这份指南，无需询问作者，按照符合产品实际行为的步骤，并用非技术读者能够理解的语言，完成所有受支持的目标？它使用固定的12 项可用性 + 准确性检查清单——与终端用户指南作者遵循的标准相同；两者使用同一来源，且编号完全一致，以免编写标准与评审标准发生偏差——随后输出单个可由机器解析的判定结果，以及作者可在一轮修订中处理的发现。它评判的是文本形式的 Markdown 文档（正文、围栏代码片段、用文字描述并附有线框图链接的屏幕），而不是渲染后的帮助网站；其方法和标准不受媒介影响。这是一个验收关卡——它不会编写、修复或改写指南；它只负责评判并返回发现，由编写者进行修订。

何时启用

• 已完成的终端用户指南需要在发布给用户之前作出接受/修订决定。
• 你是刚完成指南编写的人员所对应的独立评审者/验收关卡。
• 在之前给出 revise 判定后，重新评审修订过的终端用户指南。
• 评审 amend——上游变更后对已发布指南所作的带版本增量修改（按增量范围评判，条件 9）。

请勿在以下情况启用：

• 编写或修复终端用户指南 -> 使用用户指南编写技能（它遵循此技能所采用的相同标准）。此技能绝不编写指南。
• 评审开发者采用/集成指南——供开发者阅读、用于集成工具的 SDK、库、CLI、框架或 API 平台入门说明 -> 使用开发者指南评审技能。该关卡评判开发者采用情况；此关卡评判终端用户产品指南。
• 评审 API 参考文档——面向开发者的 HTTP/SDK 端点目录（端点、字段、错误、契约一致性） -> 使用 API 参考文档评审技能。该关卡评判契约一致性，而非终端用户可用性；此处的终端用户参考文档指产品界面（功能、设置、CLI 命令），而不是 HTTP API。
• 评审工程设计文档——架构规范、设计文档、ADR 或 RFC -> 使用设计评审技能，根据代码库验证设计声明。这是不同的关卡，也采用不同的标准。
• 检查模板/章节是否符合要求 -> 这是模板问题。此技能评判的是质量是否达到标准，而非是否包含所有标题。

工作流

步骤 1：以全新、独立的视角通读整份指南，并收集上游文档

从头到尾阅读指南，假设自己是第一次接触它的目标用户（通常是非技术用户），不受作者的阐述方式影响。你的立场是为用户把关：只有当你发现用户无法按照指南中所写的内容完成受支持的目标，或者某个步骤会误导用户，因为它与产品不符时，这一发现才有分量。

然后找出编写该指南时提供的上游文档，即其 depends_on 集合（通常包括功能规格、用户流程和/或线框图；有时只有 PRD；有时还包括用于界面术语的设计系统）。如果存在用户流程，则列出其中的用户目标（每个流程对应一个用户目标/任务）；**如果不存在用户流程，则从功能规格/PRD 中提取目标。**依据实际提供的上游文档判断覆盖情况——绝不要假设用户流程必然存在。如果缺少预期的上游文档，请注明你是在该假设下进行审查；不要臆造上游文档不支持的目标，也不要因项目从未生成某份文档而指责指南。

修订模式（根据输入信号判断）：如果提供的是现有指南 + 变更请求 + 已更改的上游文档，则根据 cond-9 审查差异，而非全面重新审查。

步骤 2：运行 12 项可用性与准确性检查清单——逐项判定

对以下每项条件作出通过或存在缺口的判定。只有存在具体且明确的不足时，条件才算未通过——“我会换个说法”不算缺口。对于每个缺口，记录准确位置以及缺少的内容（步骤 4 会将其整理成可执行的发现）。这些条件是统一的评判标准（与作者第 10 步的自检完全一致，编号也相同）；不要自行添加检查项。

1. 目标覆盖 — 每个目标对应一篇操作指南，不留孤项。 从提交的上游资料中（步骤 1）枚举出的每个用户目标，都恰好有一篇以任务为导向的操作指南；每篇操作指南也都能追溯到一个目标。如果某个目标没有操作指南（覆盖缺口），或某篇操作指南不对应任何上游目标（可能意味着功能是凭空编造的孤项），则视为缺口。
2. 四种 Diataxis 模式齐全，且类型正确。 教程、操作指南、解释和参考资料都齐全，且彼此不混淆——教程是一条单一且有保证的顺利路径（没有选择或失败分支，每个步骤都会产生可见结果）；操作指南采用祈使语气的编号步骤（不是概念堆砌）；解释不包含步骤；参考资料保持中立且完整。如果缺少某种模式，或某种模式被写成了另一种模式，则视为缺口——例如，把操作指南写成掺杂概念的长篇内容、在解释中暗藏步骤，或让教程分支出多个选项。（模式混淆是文档令人困惑的首要原因。）
3. 面向终端用户的功能／配置参考完整。 产品提供的每项面向用户的功能、设置及 CLI 命令／快捷方式都已记录；参考资料与产品保持一致，且只描述，不指导操作。如果缺少或未及时更新某项面向用户的功能／设置／命令，则视为缺口。（这里指终端用户产品界面，而非 HTTP API——不要因为没有记录端点而判定不合格。）
4. 步骤准确反映产品的实际行为，包括 UI 术语。 每个操作步骤都与提交的上游资料中的行为一致（对照功能规格／用户流程抽查）；没有虚构的步骤、设置、屏幕或菜单；每个控件都使用其准确的产品／设计系统标签命名（如果步骤提到了产品中不存在的控件，或使用了错误的标签，则属于准确性缺口）。步骤与上游行为矛盾、虚构了没有上游依据的功能／屏幕，或标签与产品不符，都属于缺口。编造内容属于严重失败。
5. 操作步骤合理。 操作指南和教程都使用编号步骤；每步只执行一项操作；采用第二人称、现在时和祈使语气；使用以任务为导向的标题（裸不定式，例如“添加账号”）；控件名称使用其准确标签。如果操作步骤写成未编号的大段散文、每步捆绑多项操作，或标题使用名词短语／功能名称而非任务标题，则视为缺口。
6. 故障排除涵盖已知错误状态。 提交的上游资料中的每条错误／恢复路径（用户流程中的错误／恢复路径，以及功能规格中的错误处理）都以症状 -> 原因 -> 修复方法的条目形式呈现，并按用户可见的症状组织；常见问题收录在 FAQ 中；还提供“获取更多帮助”的指引。如果已知错误状态未记录，或条目按内部原因而非用户可见症状组织，则视为缺口。
7. 便于目标受众使用。 真实用户（通常是非技术用户）只靠指南就能完成所有受支持的目标，无需询问作者；前置条件明确说明；屏幕以文字描述，并提供线框图链接，而不是假定读者能看到屏幕。如果存在歧义、缺少前置条件或步骤未定义，以致用户在任务过程中受阻，则视为缺口。（语言易懂程度——术语／可读性——属于条件 10；此处不要重复评判。此条件评估的是用户能否完成目标、前置条件和屏幕描述。）
8. 明确指出假设／缺口。 上游资料缺失或内容不充分时，指南所依据的假设都应明确说明（以便质疑），而不是默默编造。如果缺少上游答案，却被编造出来以营造内容完整的假象，则视为缺口。
9. 修订应为范围明确、全面检查并带有版本记录的增量更新（全新项目的首次构建不适用）。对于迭代更新：变更内容应达到相应标准；上游资料过时项的全面检查必须完成——没有任何已变更／移除／重命名的功能仍出现在过时的步骤／参考条目／屏幕链接／故障排除条目／术语表词条中（应通过结构化方式“查找所有引用”）；内部内容保持一致（教程仍可顺利执行，各模式类型正确，参考资料仍与产品一致）；修订历史已更新；已标记被取代／移除的项目。如果全面检查不完整（仍有过时引用）、内容一致性遭到破坏、缺少变更历史或未标记移除项，则视为缺口。根据输入信号判定（已有指南 + 变更请求 + 已更新的上游资料）。
10. 语言平实／易读。 非技术读者能够理解并遵循指南：先说明目的；句子长度适中；首次出现时解释每个产品专用术语和缩写（并将其收录在术语表中）；不留未解释的缩写；阅读难度符合受众水平。根据实际效果判断（真实用户能否理解并遵循指南），而非根据可读性评分。未解释的术语或未解释的缩写若会让非技术读者在步骤中受阻，则视为缺口。（交叉评估注意：术语／可读性问题属于条件 10；流程难以遵循／缺少前置条件的问题属于条件 7——同一问题不要在两项条件下重复扣分。）
11. 无障碍性（按比例评估）。 对于文本内容：链接文本应当有明确含义（不要只写“点击此处”）；标题层级应当正确嵌套（不跳级）；任何步骤都不应仅依赖颜色（“点击绿色按钮”）或仅依赖位置（“右侧的按钮”）——应使用标签命名控件；描述的屏幕应说明替代文本的意图。如果仅靠链接／颜色／位置提示会让无法感知该提示的读者受阻，则视为缺口。（按比例评估——没有链接／图片／颜色提示时不适用。像素对比度和焦点外观属于已渲染网站／设计系统的关注点，不在此处评估。）
12. 便于查找／从这里开始。 首次阅读的读者无需预先了解产品，就能找到从这里开始的内容（教程）以及与其目标相关的章节（例如通过 §1 的指引／可导航的结构）。如果没有从这里开始的指引，且读者无法判断哪份文档能回答自己的问题，则视为缺口。（交叉评估注意：措辞应区别于条件 1 的“按目标组织——覆盖”，以及条件 2 的“模式类型正确”；对于单页指南，此项自然满足；不要在条件 12 下重复修订已在条件 1／条件 2 中发现的问题。） 比例原则。“可用于实现每个目标”的要求应根据产品规模调整。精简产品的指南可以合理地省略不需要的章节，只保留少量操作指南——这是规模适配得当，并非内容缺失。精简指南也可能确实没有需要修订的内容（首次构建时 cond-9 不适用），没有需要定义的术语（cond-10 自然满足），没有图片或颜色提示（cond-11 不适用），而且很容易找到（cond-12）。评判时应关注上游材料实际涵盖的目标是否得到覆盖、内容是否准确，以及非技术读者能否看懂并照着操作，而不是章节数或字数。一份篇幅精简但内容完整、满足每项适用条件的指南，应予通过。不要因为内容简短就凭空认定存在缺陷。（条件 1 中的硬性底线无论指南长短都适用：上游材料涵盖的目标必须有对应的操作指南。）

第 3 步：确定结论

• approve — 每项适用条件均满足。真实的（非技术）用户按照指南所写内容，可以实现每个受支持的目标；各模式归类正确；步骤与产品相符，控件名称准确；语言通俗易懂。即使你能想到措辞上的改进，也应予以通过；标准是可用性和准确性，而非完美无缺，更不是追求面面俱到。
• revise — 一项或多项条件存在明确缺陷，会妨碍用户操作（例如，某个目标没有对应的操作指南、Diátaxis 模式混淆或归类错误、参考资料不完整、步骤内容杜撰或不准确或标签错误、已知错误状态未记录、修订时的过时内容排查不完整、术语未解释、指令仅依赖颜色或位置，或没有读者可以据此开始并逐步导航的入门指南等）。

不要为了体现工作量或索要锦上添花的内容而要求修订。条件要么满足，要么不满足。

第 4 步：给出结论和可执行的发现

结论单独占一行，使用字面文本 VERDICT: approve 或 VERDICT: revise，不得在其周围添加代码围栏、引号或其他文字（此处的围栏仅作示例）：

VERDICT: approve

然后在后续行列出发现。结论为 revise 时，每条发现都必须可执行——注明未通过的条件（按编号）、确切位置，以及如何修复——让作者可以一次性解决问题。结论为 approve 时，可以列出非阻塞性意见；这些意见不得暗示必须修订。

好的发现会指出缺陷及修复方法：

revise — 目标覆盖（条件 1）：用户流程中包含“重置密码”目标，但指南没有相应的操作指南。修复方法：添加面向任务的“重置密码”操作指南（根据流程中的正常操作路径编写编号步骤）。

revise — 通俗易懂（条件 10），“配置 SSO”操作指南：第 2 步写道“通过 SAML 元数据配置 IdP”，却没有向非技术读者解释 IdP/SAML。修复方法：首次提及时定义 IdP 和 SAML（并在术语表中收录），或用通俗语言重述该步骤。

不好的发现模糊且无法执行：

指南可以更清晰。（哪个目标？哪种模式？哪一步？该如何修复？）

规则

硬性规则（绝不可违反）：

• 只输出一行判定：VERDICT: approve 或 VERDICT: revise——该字面标记必须独占一行，不得附带其他内容。下游工具会解析它。
• 评审，不撰写。 返回问题；不要重写、修正或补全指南。由编写者进行修订。
• 统一评审标准。 按照步骤 2 中的十二项条件评审——与作者编写时遵循的标准完全一致，编号也相同。不得另立条件或采用更严格的私有标准。
• 不得误判为需要修订。 若指南满足所有适用条件，即应予以批准，即使小型产品的指南篇幅较短也一样。只要仍能涵盖目标，按比例精简就不是缺陷。只有存在真实且明确的问题时才要求修订。
• 不得误判为批准。 不要为了表示友好而忽略真实问题。阻断性问题必须判为 revise。
• 遵守两项重叠防护规则。 不要重复扣分：术语或可读性缺陷属于条件 10（不再同时归入条件 7）；导航或可查找性缺陷属于条件 12（不再同时归入条件 1/条件 2）。单个缺陷只在负责该问题的条件下报告一次。
• 根据实际收到的上游材料列举目标。 从用户流程（若有，否则从功能规格说明/PRD）中提取目标——切勿假定用户流程必定存在。未提供的上游材料绝不能成为要求修订的理由；应将其缺失标注为一项假设。但若指南忽略了已提供的上游材料（已提交的用户流程中某个目标没有对应操作指南，或某个步骤与已提交的功能规格说明矛盾），则可以据此提出问题。
• 参考依据是终端用户接触到的产品界面，而非 HTTP API。 评估是否完整时，应覆盖产品提供的功能、设置和 CLI 命令（条件 3）；不要因指南遗漏端点而判其有问题。
• 杜撰属于严重失败。 凭空编造且没有上游依据的步骤、设置、屏幕或功能，不符合条件 4——真实问题应标注为一项假设（条件 8），而不是用编造的步骤掩盖。修订后仍保留对已移除或重命名功能的描述，属于因内容过时而杜撰（条件 9）。
• 每项修订意见都必须可执行——指出未通过的条件、具体位置和明确的修复方法。不得给出含糊的意见。

偏好（可覆盖）：

• 按严重程度排列意见——先列阻断性问题，再列较小问题。
• 在每项意见中注明条件编号/名称，方便作者对应评审标准。
• 批准时的备注应尽量少，并明确说明其不构成阻断问题。

易踩坑点

• 为了完整而批准，而不是为了可用性。 每个部分都齐全，用户仍可能无从下手（名为操作指南的内容其实只是在解释，某个步骤与产品相矛盾，某个目标没有操作方法，或术语过于晦涩，受众难以理解）。判断真实用户能否实现每个目标，而不是模板是否填写完整。
• 模式类型写错。 最常见的缺陷：一篇“操作指南”写了三段背景介绍，却没有步骤（伪装成操作指南的解释），或者教程提供了多个分支选项（伪装成教程的操作指南／参考文档）。逐节判断其实际内容，而不是标题（条件 2）。
• 孤立的操作指南暴露了虚构功能。 如果某个目标没有对应的上游需求，却有一篇操作指南，通常意味着有虚构的功能／界面混入其中（条件 1 + 条件 4）。追溯每篇操作指南，确认其对应某个上游目标。
• 步骤写错控件名称。 产品上的按钮写着“Apply”，步骤却说“点击 Save”，这会让非技术用户无所适从——标签不匹配属于条件 4 的准确性缺口，不是吹毛求疵。
• 把参考文档误当成 API 文档。 因为面向终端用户的参考文档没有列出 HTTP 端点而判其不合格，或者接受端点目录作为面向终端用户的参考文档——面向终端用户的参考文档描述的是产品界面（条件 3）。
• 没有运行产品却评判步骤准确性。 你无法在实际运行的产品中逐步操作，但可以根据提交的功能规格／用户流程逐项抽查步骤（条件 4）。没有上游依据的步骤若作为事实呈现，而非标记为假设，就是缺口。
• 按原因而非症状组织故障排查内容。 故障排查部分可能列出了所有内部错误代码，却仍无法帮助只看到某个症状（“页面无法加载”）的用户。条目必须能按用户可见的“症状 -> 原因 -> 解决方法”查找（条件 6）。
• 跨重叠防护条件重复扣分。 同一个未解释的缩写同时按条件 10 和条件 7 标记，或同一处缺少“从这里开始”同时按条件 12 和条件 1 标记——一个缺陷，只对应一个条件。设置这些防护条件，正是为了避免这种情况。
• 以可读性分数作为门槛。 要求达到特定的 Flesch-Kincaid／年级水平分数——条件 10 评判的是非技术读者能否看懂，而不是分数（分数只是写作辅助工具）。
• 对简短指南过度严格地要求无障碍功能。 只有两个链接且没有图片的指南显然符合条件 11；若因“没有替代文本”而判其需要修改，就是误判。条件 11 的要求与内容相称，也不涉及像素对比度（这是设计系统的职责）。
• 不完整的修订检查却被放过。 修订时，只更新一个界面并不算全面检查——其他模式中若仍残留过时内容（如词汇表术语、故障排查条目），就不符合条件 9。检查每种模式。
• 系统性过度标记（误判为需修改）。 评审者受命寻找问题时，容易矫枉过正，把合格的指南也判为有缺陷。把握评判标准：只有明确指出具体存在的缺陷，才算缺口；不能仅仅因为措辞与你偏好的不同就判定有问题。
• 对篇幅适当的指南误判为需修改。 内容精简的产品，其指南本来就应简短——只有少数操作指南、折叠的章节，初稿没有更新日志。这是篇幅适当，并非文档不足。
• 因 Markdown 不是帮助网站而判其不合格。 交付物是文本形式（用文字描述的界面 + 线框图链接）。应评判描述和链接，而不是有没有像素图。
• 评审结论标记格式漂移。 “Approved”“LGTM”“needs work”，或藏在段落中间的结论，都无法解析。必须单独一行输出原样格式：VERDICT: approve|revise。

反模式

• 盖章式批准。 为避免进入修改循环而草草浏览后批准——模式拼写错误、捏造的步骤、未检查的修订，或未经解释的行话被放过，都会让用户陷入困境或受到误导。
• 吹毛求疵式修改。 因措辞、标题偏好或被包装成缺陷的锦上添花项而阻止通过。只有真正妨碍可用性或准确性的问题才需要修改。
• 悄悄重写。 “直接修好步骤更省事”——在评审过程中代为撰写，会混淆产出与评判的界限，也剥夺作者了解问题所在的机会。
• 凭空添加条件。 添加评审标准未包含的私设要求（“还应该加入视频 / 营销介绍 / 特定阅读年级评分”）。只评判这 12 项条件；简洁性、导航分类质量、替代文本写法和章节集合都只是辅助参考，按结果评判，绝不能作为硬性要求。
• 凭空假设上游要求。 因指南未涵盖某个目标而判其有问题，但该目标只存在于项目从未编写的文档中。缺少上游文档属于假设，不构成修改理由。
• 贪多求全。 要求轻量产品的指南必须包含完整的广泛章节集合（或变更日志、或术语表）。标准是覆盖目标 + 准确 + 易于遵循，而不是尽可能长的指南。
• 含糊的结论。 “基本批准，但是……”或给出两行结论。必须且只能有一个决定，且只能有一个标记。

输出

针对一份面向终端用户的指南，给出一条评审结果：

• 一行结论 — VERDICT: approve 或 VERDICT: revise，逐字输出并单独占一行。
• 发现项 — 若为 revise，每个阻断性问题列出一条可执行的发现项（未通过的条件编号 + 位置 + 具体修复方法）；若为 approve，可选择提供非阻断性备注。

抽象的使用者是负责协调产出→评审循环的对象：approve 表示指南已可供用户使用；revise 则将发现项退回给产出者，进行范围明确的修订。

相关内容

• user-guide-authoring 技能——配套流程中的产出环节；它按照本技能评判所依据的同一套 12 项可用性 + 准确性标准编写指南。产出侧和评审侧共用同一来源：本技能在 references/usability-bar.md 中完整列出标准，作者则在 Step-10 自检中按照编号完全相同的标准进行创作，以免两者出现偏差。
• developer-guide-review 技能——负责把关开发者采纳 / 集成指南（SDK / 库 / CLI / 框架 / API 平台入门）。文档和受众均不相同；本技能评判的是面向终端用户的产品指南，而不是开发者入门说明。
• api-reference-review 技能——负责把关面向开发者的 HTTP / SDK 端点目录（契约一致性）。文档和标准均不相同；此处评判的终端用户参考文档针对的是产品界面，而非 API。
• design-review 技能——负责把关工程设计文档（架构规范、设计文档、ADR、RFC），并根据代码库核实其中的声明。把关流程和标准均不相同；不适用于面向终端用户的指南。
• user-guide template / content-template 工具——负责章节结构；本技能评判的是指南是否符合标准，而非结构是否合规。

渐进式披露

• references/usability-bar.md — 详细说明共用来源的 12 项标准：每项条件的通过 / 缺陷信号 + 示例发现项（新增的条件 9：amend 过期内容清查；条件 10：浅白语言；条件 11：无障碍；条件 12：可查找性；以及进一步细化的条件 4 / 5：UI 术语），以及两项重叠防护规则。评判边界情况时加载。
• references/sources.md — 评审方法的研究依据（共用来源的质量标准：Diátaxis 四种模式分类、逐目标的操作指南覆盖规则、步骤机制规范、浅白语言 + 面向文档的 WCAG 基础，以及支撑“不误判为需修改”原则的评审者过度纠正证据）。仅在审查指导的依据时加载。

正文预算

• description <= 1,024 chars（agentskills.io 上限）。Claude 会在列表中将 description + when_to_use 的合计长度截断为 1,536 chars。
• 正文 <= ~500 行 / 5,000 tokens — 每轮都会保留在上下文中。
• 每个参考文件：超过 10k tokens 时警告，超过 25k 时报错。参考文件总计：超过 25k tokens 时警告，超过 50k 时报错。

更新日志

• 1.1.0（2026-06-15）— 生产级重构：统一定义 12 条件标准（从 8 条增至 12 条；新增 cond-9 修订、cond-10 通俗语言、cond-11 无障碍、cond-12 可发现性；通过 UI 术语深化 cond-4/5；将术语条款从 cond-7 移至 cond-10），并添加两条明确的重叠防护规则（cond-10↔cond-7、cond-12↔cond-1/cond-2）和逐条件比例原则；添加 references/usability-bar.md；根据每对来源重新确立标准。仅新增内容 — VERDICT 输出 + 输入约定保持不变。（1.0.0 → 1.1.0。）