authoring-user-guide

authoring-user-guide — SKILL.md

变体： standard · 适用时机： 产品编写者正在编写面向最终用户的指南， 需要采用以 Diataxis 为依据的编写方法，以及可用性与准确性标准（包括通俗易懂的语言、无障碍性、易查找性和修订）， 并使用单独的模板工具来组合章节结构。

概述

此技能用于编写面向最终用户的用户指南：真实用户借助它完成使用产品的目标。它涵盖判断方法——如何根据上游文档为每个用户目标提炼一个操作指南，而不是凭空编造步骤；如何区分 Diataxis 的四种文档模式（混用是文档令人困惑的最常见原因）；如何确保每一步都准确描述产品的实际行为，并使用其准确的 UI 标签；如何使用非技术读者也能理解的通俗易懂的语言；如何确保指南无障碍且易于查找；以及产品发生变化时如何修订已发布的指南。它不提供章节列表，章节列表由模板工具提供。受众是（通常不具备技术背景的）最终用户，而非集成工具的开发者：开发者工具的采用与集成说明属于单独的 authoring-developer-guide，HTTP/SDK 端点目录则属于单独的 authoring-api-reference。本指南中的“参考”模式指面向最终用户的产品参考资料（功能、设置、CLI 命令），而非 API。指南基于其所描述的产品/行为文档编写，并由 reviewing-user-guide 按照可用性与准确性标准进行检查。

适用场景

• 根据产品的上游文档（通常包括功能规范、用户流程和线框图），编写面向最终用户/客户的用户指南、帮助中心或产品手册。
• 编写完整的最终用户文档集——入门教程、任务操作指南、概念说明、面向最终用户的功能/配置参考、故障排除/常见问题解答以及术语表——帮助真实用户完成所有受支持的目标。
• 上游内容变更后修订已发布的指南（例如设置重命名、功能移除/新增、流程变更、屏幕重新设计），并按版本检查内容是否过时。

请勿在以下情况激活：

• 审查/评判已完成的用户指南——这属于审查侧的关卡（reviewing-user-guide），用于检验本技能所产出的指南是否达到同一标准。
• 为库、SDK、CLI、框架或 API 平台编写开发者工具的采用、集成或入门说明——这属于 authoring-developer-guide。
• 编写 HTTP/SDK 端点目录（面向集成者的逐端点线缆契约）——这属于 authoring-api-reference。本技能的参考模式面向最终用户使用的产品界面，而非 API。
• 编写内部工程文档（功能规范、数据模型、架构）——用户指南是基于这些文档编写的外部帮助内容，而不是契约本身。

输入

阅读计划交给你的每一份文档——即你的 depends_on 集合（上游文档发现流程判定会为本文档提供信息的文档）——并追溯每篇操作指南和每个章节的依据。典型的上游文档包括 feature-spec（指南要说明的行为）、user-flows（每篇操作指南介绍的任务路径）和 wireframes（步骤中提及的屏幕）；如果有，也要阅读 PRD（是什么／为什么）、design-system（UI 术语——使用其中的组件／术语名称，使指南的用词与产品保持一致），以及 api-reference（针对开发者产品）。不要假定输入固定：这份清单是方法指导，不限制你收到的内容——绝不要把输入硬编码为单一的狭窄范围。

请做到内容自足、灵活应对，根据你实际收到的上下文撰写指南。若缺少预期的信息来源文档（例如没有 wireframes），就基于现有内容继续，并将这一缺口明确列为假设；绝不要为填补缺失内容而虚构功能、设置、屏幕或步骤。并且，在可用时使用研究能力（deep-research 能力，否则使用网页搜索），让指南内容全面，依据成熟的终端用户文档实践（Diátaxis、以任务为导向的简约写法、通俗语言指南、针对文本帮助的 WCAG、可靠的文档风格指南），而不只是填充模板。

迭代时（修订）：流程会提供现有指南＋变更请求＋发生变更的上游文档。运行第 9 步（修订），不要从头重写——输入约定不变。

工作流程

**先使用模板工具撰写。**起草前，先从内容模板工具（content-template-gateway 能力，或已安装的其他模板提供方）获取用户指南的章节结构。它会提供章节槽位——简介／概述、入门教程、操作指南、概念说明、功能／配置参考、故障排除／常见问题、术语表、版本与变更日志／修订历史章节（指南自身的文档版本，用于修订），以及假设说明部分。绝不要硬编码另一套大纲与之竞争——这项技能负责用推导出的内容填充模板槽位，而不是重新定义槽位。对于不确定的文档惯例，使用研究能力作为依据。

第 1 步：列出用户目标——每个目标对应一篇操作指南，不留遗漏

从交给你的上游文档中列出用户目标：若有 user-flows，则从中提取（每个流程都代表一个用户目标／任务）；否则从 feature-spec / PRD 中提取。为每个目标恰好撰写一篇以任务为导向的操作指南——每个目标都要有一篇操作指南，每篇操作指南都要对应一个目标。这就是无孤儿覆盖规则，并且可以灵活适应：不要假定一定会收到 user-flows；应从实际收到的上游文档中提取目标。

第 2 步：将入门教程写成一条必定成功的顺畅路径

教程是一堂通过实践学习的课程：只有一条路径，不提供选择或替代方案；每一步都要产生可见结果，确保成功是作者的责任。将“为什么”留给说明部分，并把所有失败分支放入故障排除——分叉或失败的教程就不是教程。选择新用户能实现的第一个有意义的成功，并尽量减少抵达该目标的步骤（尽可能减少从“打开产品”到“首次看到成果”之间的前置条件和决策）。

第 3 步：将每篇操作指南写成祈使句式的编号步骤——不要堆砌概念

每篇操作指南都面向已经熟悉基本情况、且有一个明确目标的用户。标题应直接描述任务（使用任务导向的动词原形）。按照成熟的文档风格规范撰写：使用编号步骤，每步只执行一个操作（步骤过长时应拆分），采用第二人称、现在时、祈使语态／主动语态。涵盖顺畅路径，并在出现故障时指向故障排除部分。把操作指南写成散文或概念说明，是最常见的 Diátaxis 缺陷——请始终使用步骤。

Step 4：撰写不含步骤的说明，并补全参考资料

• 说明提供心智模型并解释“为什么”；其中不包含任何步骤，并交叉链接到介绍如何运用这些概念的操作指南和参考资料。只保留用户真正需要了解的概念，不要全面介绍内部架构。
• 功能／配置参考应保持中立、客观，并完整涵盖面向终端用户的产品功能——包括每项功能、设置以及 CLI 命令／快捷键。它只做描述，不提供操作指导；其结构应与产品结构一致，方便用户对照查看。这是产品参考资料，不是 HTTP API 端点目录。

Step 5：根据已知错误状态编写故障排除内容

根据用户流程中的错误／恢复路径和功能规格中的错误处理，编制故障排除目录——每种已知错误状态都应有对应条目。按用户可见的症状（而非内部原因）组织内容；每个条目依次说明症状、原因和解决方法，解决方法使用编号步骤；如有错误消息／代码，也应一并提供。为常见问题添加 FAQ，并提供“获取更多帮助”的指引。教程和操作指南刻意省略的故障处理内容，都应放在这里。

Step 6：使用控件的准确标签命名；用文字描述屏幕

此交付物是 Markdown 文本：用文字描述每个屏幕，并链接到线框图，而不是嵌入截图。提及控件时，使用产品中显示的准确 UI 标签；如果设计系统为组件／术语命名，应始终统一使用这些名称——这样用户看到的界面才能与步骤一一对应（例如，按钮标签是“应用”，步骤却写“点击保存”，就会让非技术用户无所适从）。命令／配置内容应放在围栏代码块中。

Step 7：使用浅白语言；确保指南易于理解

• 浅白语言（面向非技术读者）。 先说明用途；优先使用短句和日常用语。首次使用时，解释每个产品专用术语和缩写（并将其收录到术语表中）；不要留下未解释的缩写。内容应达到一般读者都能理解的程度——判断标准是实际用户能否看懂，而不是可读性分数。
• 无障碍性（针对文本帮助内容）。 提及控件时应使用其标签，切勿只用颜色（“绿色按钮”）或只用位置（“右侧的按钮”）来指代。链接应使用有意义的文字（说明链接目的地，而不是“点击此处”）。标题应按顺序嵌套（不得跳级）。描述屏幕时，应确保看不到线框图的读者仍能理解屏幕内容（满足替代文本的意图）。像素对比度／焦点外观属于渲染后的文档站点／设计系统所负责的范畴，不属于这份文本材料。

Step 8：明确从何处开始；追溯每个步骤；将缺失信息标注为假设

• 易于查找。 在第 1 节提供入门指引，让初次阅读者找到教程、要完成特定任务的用户找到对应操作指南、查找信息的用户找到参考资料，以及遇到问题的用户找到故障排除内容——读者无需事先了解产品，也能找到适合自己的入口。
• 准确性。 将每个操作步骤追溯到功能规格中的行为（或其他已提交的上游资料）。如果上游资料不完整或缺失，应说明你所做的假设（以便审核者提出质疑），并将未解决的问题列为待解问题——绝不能凭空编造功能、设置或步骤，并将其藏在操作流程中。

步骤 9：修订时——界定变更范围、全面检查过时内容、重新确保一致性

收到现有指南、变更请求和已变更的上游资料时，应编辑，不要重写：

1. 界定变更单元（操作指南／参考条目／入门步骤／屏幕说明／故障排除条目／术语表词条／解释性主张）。
2. 全面检查上游变更导致的过时内容（首要工作）。 对每项已变更／已移除／已重命名的功能，找出指南中所有提及它的位置——涵盖所有模式（步骤、参考条目、屏幕／线框链接、故障排除、术语表、解释）——并逐一更新，使其准确反映当前产品。若某个步骤仍在描述已移除／已重命名的功能，这是影响最大的缺陷（因过时而捏造内容）。
3. 重新确保内容内部一致。 教程仍能基于新行为从头到尾顺利完成；各模式类型保持明确；参考内容仍与产品一致；交叉链接和术语表保持完整。
4. 版本和变更日志。 更新指南自身的文档版本，并添加修订历史条目（说明变更内容、时间和原因）——这与产品版本及任何技能语义化版本号不同。
5. 标记已被取代／已移除的内容。 删除或标记已移除功能的操作指南（注明替代方案）；对于已重命名的设置，保留一次旧名称以便搜索，然后移除旧名称。用户指南是叶节点——没有下游衍生文档。

步骤 10：交付前根据下方的易用性／准确性标准进行自检

按照质量标准（12 项自检条件）检查。交付审核前修正所有不符合项。各方法的详细说明见 references/method-depth.md。

规则

硬性规则（绝不违反）：

• 组合，不要重复。 章节结构由模板工具提供；本技能绝不另行提供与之竞争的大纲。
• 从上游推导，不要凭空编造。 每个步骤都必须对应已提供的上游行为；若缺少上游资料，应明确说明为假设，绝不编造内容来填补。
• 每个目标对应一个操作指南——不留遗漏。 已提供的上游资料中，每个用户目标都必须有对应的操作指南；若有用户流程，则以此为目标来源，否则以功能规格／产品需求文档（PRD）为准。
• 区分 Diataxis 的四种模式。 教程、操作指南、解释和参考内容彼此独立，类型正确；绝不混为一谈（不得将操作指南写成概念堆砌，也不得把解释内容埋在教程中）。
• 面向终端用户＋以产品为参照。 指南面向终端用户；参考内容应描述产品界面（功能／设置／命令），而不是 HTTP／SDK API。
• 语言通俗，天然易于理解。 首次使用时解释术语／首字母缩略词；使用控件标签为控件命名，绝不能只用颜色或位置来指代；链接文字应清楚说明链接内容。
• 修订是有范围、经过全面检查并记录版本的增量变更。 编辑受影响的单元，全面检查所有指向已变更功能的过时引用，重新确保一致性，更新版本和变更日志，并标记已被取代的内容——绝不悄无声息地直接改写。

偏好（可覆盖）：

• 操作步骤细节：使用编号步骤；每步只执行一个操作；采用第二人称、现在时和祈使语气；标题以任务为导向。
• 以任务为核心，保持精简——先说操作，围绕用户的实际任务展开；删去所有无助于完成任务的内容（错误是可用于故障排除的学习契机）。
• 根据产品的目标／功能集调整指南的篇幅——既不凑篇幅，也不删减过度。

易踩之处

• 把操作指南写成概念堆砌。 内容看似详尽，却把用户真正想了解的步骤埋了起来。操作指南应采用祈使句并按编号列出步骤；“为什么”应放在说明中。
• 教程中途分岔或可能失败。 带有分支或失败路径的入门课程不是教程，而是伪装成教程的操作指南或故障排查。教程应提供一条必定成功的顺畅路径；失败情况应放到故障排查中。
• 参考文档不完整。 跳过那些“看起来显而易见”的设置或命令，会让用户无法查找相关信息。参考文档必须涵盖产品的全部功能。
• 步骤中提到了错误的控件名称。 如果按钮上写的是“应用”，却写成“点击保存”，非技术用户就会无从操作。控件名称应与产品或设计系统中的准确标签一致。
• 术语未解释／只给出缩写。 对非技术读者来说，内容即使准确，也会难以理解。首次出现时应给出定义，并将术语汇总到词汇表中。
• 只根据颜色或位置说明操作。 “点击绿色按钮”／“点击右边那个”会让无法辨别颜色或看不到布局的读者无从操作；应写明控件名称。
• 根据内容单薄的上游资料编造步骤。 上游资料缺失时，编造产品可能并不具备的步骤会造成隐蔽缺陷。应将资料缺口明确列为假设。
• 产品变更后内容已过时。 如果步骤、参考文档或词汇表条目仍在描述已移除或改名的功能，就会因内容过时而造成虚构信息；修订时的过时内容检查必须覆盖所有模式中的每一处引用。
• 嵌入截图。 Markdown 不支持二进制资源；请用文字描述屏幕，并链接到线框图。真实截图属于未来后端的工作范畴。
• 混淆参考文档与 API 目录。 面向最终用户的功能／配置参考文档不是 HTTP/SDK 端点参考文档（authoring-api-reference）。

反模式

• “我自己把章节列表写进文档就行。” 这样会重复模板内容，并逐渐偏离模板。请始终使用模板工具来构建文档结构。
• “一个完整的操作流程就能涵盖所有内容。” 把教程、操作指南、说明和参考文档合并成一篇叙述，是造成文档混乱的首要原因。请将不同模式分开。
• “上游没提到，那我就描述它大概会怎么做。” 未说明的虚构行为应放到假设／待解决问题部分，而不是写进操作步骤。
• “读者会自己弄懂这些术语。” 非技术读者做不到；请给出定义。
• “产品变了，我只要修改记得的那个界面就行。” 如果不全面检查过时内容，其他过时引用就会残留；请检查所有模式。
• “这是开发者工具，所以我会在这里写集成／入门流程。” 这属于 authoring-developer-guide；本技能用于编写面向最终用户的产品帮助文档。
• “我会把 API 端点表嵌入参考文档。” 参考文档应涵盖产品功能；端点目录属于 authoring-api-reference。

易用性／准确性质量标准

当以下条件全部满足时，用户指南才算完整、易用且准确（这与评审侧门槛断言的 12 项条件相同，采用同一来源，编号也完全一致）：

1. 覆盖目标——每个目标对应一篇操作指南，不留孤项。 提交的上游材料（如有用户流程，则以用户流程为准；否则以功能规范／PRD 为准）中的每个用户目标都恰好对应一篇操作指南；每篇操作指南也都能追溯到一个目标。
2. 包含且正确区分四种 Diataxis 模式。 教程（一个有保障的路径）、操作指南（使用祈使式步骤，而非概念堆砌）、解释（不含步骤）、参考（中立且完整）——彼此不得混淆。
3. 终端用户功能／配置参考完整。 文档涵盖所有面向用户的功能、设置和 CLI 命令／快捷方式；参考内容与产品保持一致。（指产品表面，而非 HTTP API。）
4. 步骤符合实际产品行为，包括 UI 术语。 每个步骤都符合已提交上游材料中的行为；不得虚构步骤／设置／界面；每个控件都必须使用其准确的产品／设计系统标签命名。虚构内容一律不合格。
5. 操作流程编写规范。 使用编号步骤，每步执行一个操作，采用第二人称、现在时和祈使语气，标题以任务为导向（使用准确标签）。
6. 故障排除涵盖已知错误状态。 上游材料中的每条错误／恢复路径都以“症状 → 原因 → 解决方法”的条目呈现，并按用户可见的症状组织；常见问题纳入 FAQ；提供“获取更多帮助”的指引。
7. 目标受众可以使用。 普通用户（通常不具备技术背景）仅凭指南就能完成每个受支持的目标；前提条件已说明；界面已描述并附有线框图链接。（语言是否易懂属于条件 10——本条件考察的是能否达成目标、前提条件和界面描述；不要在此重复评判术语。）
8. 明确说明假设／缺口。 如果上游材料缺失或内容单薄，应明确说明假设（以便质疑），不得默默虚构。
9. 修订是范围明确、全面检查且有版本记录的增量更新。 迭代时：所改动内容符合质量标准；已全面检查上游材料是否过时（各模式中均不得继续引用已移除／更名的能力）；内容内部一致；已更新修订历史；已标明已取代／移除的条目。（首次从零构建时不适用。）
10. 使用浅白语言，易于阅读。 以目的为先；句子简短；每个术语／首字母缩写首次出现时都要定义（并收入术语表）；不得出现未解释的首字母缩写；阅读难度应符合受众水平。判断标准是非技术读者能否理解，而非某个分数。（与条件 7 不同：术语／可读性问题属于条件 10；流程难以遵循／缺少前提条件的问题属于条件 7。）
11. 无障碍性（按比例评估）。 链接文本有意义（不单独使用“点击此处”）；标题层级正确；步骤不得仅依赖颜色或位置；对界面的描述应体现替代文本意图。（没有链接／图像／颜色提示时不适用；像素对比度和焦点显示效果由设计系统负责，不在此处评判。）
12. 易于查找／从此处开始。 首次阅读的用户能够在整个文档集中找到起始内容和目标对应的章节。（这不同于条件 1“按目标组织”和条件 2“模式类型正确”——此项考察读者能否导航至相关内容；对于单页指南，此项自然满足；不要对已由条件 1／条件 2 发现的问题重复扣分。）

输出

一份面向终端用户的 Markdown 用户指南，按照模板工具的结构编写：包含介绍/概览（带有入门指引 + 通俗易懂/无障碍规范）、入门教程（一个有保障的顺畅使用路径）、每个用户目标对应一篇任务导向的操作指南（使用祈使句编号步骤）、概念说明（不含步骤）、面向终端用户的功能/配置参考（产品功能界面——功能、设置、CLI 命令，而非 HTTP API）、根据已知错误状态整理的故障排除/常见问题、术语表、版本与变更日志/修订历史部分（指南自身的文档版本），以及假设/未决问题部分。屏幕以文字描述，并附线框图链接；命令/配置使用围栏代码块；控件名称使用其确切标签。修订时，输出应为范围明确、带版本的差异内容 + 更新后的修订历史，而非重写全文。该文档由评审侧关卡使用（根据上文的 12 项条件门槛进行评判），最终供真实用户使用，以完成所有受支持的目标。此方法 + 门槛不依赖媒介：未来的文档平台或包含丰富截图的后端只会改变呈现方式（如何展示屏幕），不会改变推导过程或门槛。

相关内容

• 模板提供方（content-template-gateway capability）——提供本技能所遵循的用户指南章节结构；此处不重复。
• 研究能力（deep-research，否则使用网络搜索）——为文档规范（Diataxis、极简主义、通俗语言、面向文档的 WCAG、风格指南）和推导依据提供支持。
• 上游输入——交付的 depends_on 集合。 通常包括功能规格 + 用户流程 + 线框图（以及可用时的 PRD/设计系统/API 参考）。不得从空白页面开始编写。
• reviewing-user-guide——评审侧关卡，用于验证同一套 12 项可用性/准确性门槛；产出侧与评审侧使用同一来源。
• authoring-developer-guide——用于讲述开发者工具的采用/集成流程的同类技能；本技能面向终端用户，提供产品帮助，与之不同。
• authoring-api-reference——用于整理 HTTP/SDK 端点目录的同类技能；本技能的参考模式面向终端用户的产品界面，与之不同。

渐进式披露

• references/method-depth.md——深入介绍方法：通俗语言/可读性规范、面向文本类文档的 WCAG 无障碍检查、信息架构/入门指引读者路径、UI 术语规范、任务导向的极简主义，以及修订时的过时内容扫描流程。撰写需要深入了解方法的章节时加载。
• references/sources.md——章节集合、以 Diataxis 为依据的编写方法，以及可用性/准确性门槛的研究出处。核实主张依据时加载。

正文预算

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个令牌——每轮都保留在上下文中。
• 每个参考文件：超过 10k 个令牌时警告，超过 25k 个令牌时报错。

变更日志

• 1.1.0（2026-06-15）——生产级重构：统一来源的 12 项条件门槛（新增条件 9：修订、条件 10：通俗语言、条件 11：无障碍、条件 12：易于查找；深化条件 4/5 的 UI 术语要求；将术语条款从条件 7 移至条件 10）；新增步骤 6（准确标签）/步骤 7（通俗语言 + 无障碍）/步骤 8（入门指引）/步骤 9（修订）；新增 references/method-depth.md。增量式更新——输入约定 + 门槛的核心框架保持不变。（1.0.0 → 1.1.0。）