authoring-developer-guide

authoring-developer-guide — SKILL.md

变体： 标准 · 适用场景： 编写（或修订）开发者工具的采用与集成叙述，达到这样的标准：开发者只看指南，就能安装工具、理解其模型、完成常见集成场景、自主解决常见错误，并在生产环境中运行工具；代码可运行，且每个步骤都与工具的实际行为相符。

概述

此技能介绍如何编写出色的开发者指南——面向开发者工具产品（SDK、库、CLI、框架或 API 平台）的使用者，讲述采用与集成过程。开发者阅读这份文档，可以从零开始完成有效集成，并进一步实现正确的生产环境集成：快速完成首次成功调用，通过清晰指引找到入门路径，理解工具的心智模型，按照以代码为核心的操作指南逐步实践，从头到尾构建一个小型的真实项目，遵循生产环境最佳实践，并自主解决常见错误，同时通过指引链接跳转到详尽的参考文档。它面向技术读者，涵盖完整的 Diataxis 四象限（教程／操作指南／解释／参考）。此技能提供编写者的判断力——研究方法和质量标准——而非章节列表。它假定有两项协作支持：提供章节结构的开发者指南模板工具，以及用于深入研究的能力，以便依据成熟的开发者体验（DX）文档实践、Diataxis 和开发者文档质量标准（易查找性／准确性／相关性／清晰度／完整性／可读性）来撰写指南。编写者会拿到计划确定的、与本指南相关的上游文档，而非面对一张白纸。需要达到的标准是：开发者只看指南，就能安装工具、理解其模型、完成常见集成场景，并从常见错误中恢复；代码可运行，且每个步骤都与工具的实际行为相符。

此技能也适用于修订现有指南（常见的实际工作——见步骤 6）：开发者指南是最常需要随变化更新的文档，因为其主题（工具）会不断演进。

何时启用

• 为开发者工具产品（SDK、库、CLI、框架或 API 平台）编写采用与集成叙述。
• 编写开发者所需的入门指南、核心概念、集成操作指南、端到端教程、最佳实践和故障排除内容。
• 工具发生变化（新版本、功能弃用／重命名／变更），或需要纠正操作指南／概念时，修订现有开发者指南——见步骤 6。
• 根据提供的功能规格和 API 参考文档，填充开发者指南模板，编写经过研究、可运行且准确的内容。

以下情况请勿启用：

• 编写详尽的、按端点／符号划分的 API 参考目录 → 应单独编写文档。本指南负责叙述并链接到参考文档，不会重新罗列其中的内容。
• 编写面向非技术最终用户的用户指南（产品任务帮助、无代码、面向不同受众）→ 编写者应根据上游 PRD 中的受众来选择。
• 编写内部工程文档——API 规格（线协议契约）、架构文档（系统设计）或数据模型（持久化架构）。
• 审阅或评定已完成的开发者指南 → 使用 reviewing-developer-guide；此技能仅用于编写。

输入

阅读计划交给你的每份文档——即 depends_on 集合中的文档——并将每个操作指南和概念追溯到这些文档。常见的上游文档可供参考，但不是固定上限。

• 常见上游文档。 feature-spec（指南要讲解的功能）、api-reference（集成示例调用的端点——如果工具提供 API）和 PRD（受众 + 价值）；如果有，还包括 user-flows（集成场景）和 architecture-doc（身份验证/部署背景）。根据交给你的 api-reference 编写示例——使用真实端点和真实功能。对于修订，还会交给你现有指南 + 变更请求 + 已更改的上游文档（第 6 步）。
• 内容自足 + 灵活应对。 根据实际收到的上下文编写。若缺少预期的上游文档（例如，非 API 的库/CLI 没有 api-reference），就依据现有材料继续，并将缺口明确标注为假设；绝不虚构功能、端点或代码路径。
• 研究以确保全面。 使用 deep-research，依据成熟的 DX 文档和 Diataxis 实践编写指南，而不只是填充模板。

工作流

步骤 1：采用模板工具中的结构——不要自行设计大纲

从你的开发者指南模板工具（全面版）中获取章节结构。不要在此重新列出或推导章节列表；此技能提供的是如何高质量填充这些章节的方法。如果没有可用模板，请获取一套全面的开发者指南结构（请求或创建一套，或退而采用标准章节：概览/方向说明 + 明确标注的入门指南、快速上手、核心概念、集成操作指南、端到端教程、最佳实践、故障排除/常见错误、API 参考索引、工具版本管理/迁移、文档变更日志、待解决问题），然后继续。

步骤 2：加载上游文档；根据 feature-spec + api-reference 确定覆盖范围

阅读交给你的文档——它们是你的输入，而不是空白页。feature-spec 中的功能是概念和示例覆盖范围的检查清单；api-reference 中的端点是示例调用的对象。每个示例和代码样例都必须追溯到真实的上游功能/端点——不得虚构 API。如果上游文档内容不足或缺失，请将缺口明确标注为假设，不得悄悄虚构端点。识别工具类型（API 平台 / 按语言划分的 SDK / CLI / 框架——一个工具可以属于多种类型），这将决定全文的侧重点（步骤 4）。

步骤 3：通过研究为指南提供依据

开展一轮深度研究，以成熟的 DX 文档实践（Stripe/Twilio/Auth0 的标准——快速完成首次调用、代码可运行、按目标组织内容、概念先于参考资料；以缩短首次调用所需时间为目标，尽可能减少实现首次验证成功所需的步骤）、完整的 Diataxis（正确区分并分开呈现四种模式），以及开发者文档质量评估标准（易于查找/准确/相关/清晰/完整/易读）为依据，针对本产品编写内容。如果没有可用的研究能力，切勿虚构安装命令、端点、参数或错误结构；应将其标注为待验证的假设。

步骤 4：应用各章节的编写方法

按照上述方法填充模板各章节。精简不适用于轻量工具的章节；内容篇幅应与产品及其类型相称。（深度——评估标准、信息架构、快速上手、概念：references/structure-onboarding.md；最佳实践、故障排除、工具类型、修订流程：references/bestpractices-archetype-amend.md。）

• 围绕开发者的目标组织内容，而不是围绕端点。 整份指南都应以开发者想要完成的事情来命名和编排操作指南（如“接受付款”），绝不要以 API 符号命名。开篇先说明可以构建什么。
• 信息架构——明确标示“从这里开始”，并按读者的阅读路径排序。 让入口一目了然（导览 → 首次成功 → 概念 → 操作指南 → 教程 → 最佳实践 → 故障排查 → 参考文档）；突出展示身份验证和入门内容；让交叉链接保持可预测；使用便于浏览的标题和聚焦的目录；逐步展现复杂内容（先讲常见路径，边缘选项通过链接提供）。让正文具备基本的无障碍性：使用有意义的链接文本（绝不写“点击这里”）、为所有示意图添加替代文本、首次出现时定义缩写，并使用正确的标题层级。（可查找性是评估标准的首要维度；“没有明确的入门指引”是导致读者放弃的主要原因之一。）
• 概览／导览——用两句话说明工具的功能及其解决的问题、预期读者和前置条件、2–4 个重点使用场景（每个场景链接到对应操作指南）、入门路径，并明确说明完整参考文档位于其他位置（本指南会链接到该文档）。
• 入门内容 = 快速且可验证的首次成功。 提供能完成一次真实且成功的调用的最小完整程序：前置条件 → 安装 → 配置凭据 → 首次调用 → 验证。说明凭据的获取方式（从注册到获取密钥／控制面板的路径），并引导读者通过测试／沙盒模式（而非正式环境）进行首次调用。代码必须可运行且可直接复制粘贴；凭据必须来自环境变量／配置，绝不硬编码；调用应展示真实价值，而不是 hello-world。尽量减少首次验证成功所需的步骤（TTFC 目标）。最后给出预期输出原文，以及最常见的 2–3 个首次调用失败情况（更深入的问题放到故障排查中）。（Diataxis 教程。）
• 核心概念应先于参考文档和操作指南。 解释心智模型——客户端／资源对象、领域术语及其关系、请求生命周期（同步／异步、Webhook、幂等性的基本概念）、环境（测试与正式）——让参数和操作指南有意义。（Diataxis 解释。）
• 集成操作指南 = 以目标命名、以代码为核心、可独立跟读的操作方案，面向已了解基本情况的读者（Diataxis 操作指南）。每个常见场景设一个小节，其中包括目标、额外前置条件、精简且聚焦的可运行代码（仅展示相关行）、成功结果，以及指向参考文档中完整选项集的链接——不要在此内嵌整个目录。内容规模应与工具的实际功能相称。
• 端到端教程 = 从头到尾构建一个小型且真实的项目（Diataxis 教程）。将其与第 4 节的查询型操作指南分开——混合操作指南和教程是文档令人困惑的最常见原因。结尾说明成果以及接下来可以阅读的内容。
• 基于真实生产实践的最佳实践（Diataxis 解释，而非选项罗列）：身份验证／密钥（环境变量或密钥管理器、最小权限范围、测试密钥与正式密钥）；错误处理，明确区分可重试错误与致命错误；重试 + 幂等性（带随机抖动的退避、遵循 retry-after、写入操作使用幂等键）；分页（自动迭代器或游标循环；避免游标丢失的陷阱）；速率限制（429、Retry-After）；适用时的Webhook（签名验证、重放／去重、顺序）；资源管理（复用一个客户端、连接池、超时）——每项都提供推荐模式和简短代码片段。
• 故障排查／常见错误 = 帮助读者自行解决常见且可预知的问题（超出入门内容中的首次调用失败情况）：将常见错误（身份验证 401/403、验证 400、速率限制 429、未找到 404、版本不匹配）按症状 → 原因 → 解决方法分组；工具提供错误代码时，使用“错误代码 → 含义 → 解决方法”表格；为反复出现的概念性疑问提供简短 FAQ（测试与正式环境、异步时序、幂等性）。内容应与工具规模相称——功能简单的工具可将这些内容并入入门部分。（“遇到问题时没有帮助”是导致读者放弃的主要原因之一。）
• 代码示例必须与工具的当前版本一致。 每个示例都应反映所提供的上游资料中的真实功能／端点；编写示例时应确保其可以测试（尽可能自包含，并基于单一的可运行代码来源），并注明指南针对的工具版本，以便发现内容过时——版本标记是为了帮助修订时进行过时内容检查（第 6 步），不是要求门禁在全新项目中检查版本是否最新。（示例的 CI 测试属于项目流水线，而非指南内容——但示例应便于测试。）
• API 参考文档指引——只链接出去，绝不重复编写。 说明完整目录是事实依据，位于单独的 api-reference 中；可以将本指南中的概念／操作指南对应到参考文档各章节；列出支持性资源（示例仓库、支持渠道、状态页）。
• 工具版本管理 + 迁移——说明版本方案（SemVer／基于日期）以及主版本／次版本／补丁版本的含义和固定版本的方法；弃用政策及时间安排；变更日志链接；针对每次主版本升级提供迁移说明，为每项破坏性变更列出变更前后对比，并说明迁移步骤顺序。
• 根据工具类型调整重点（内容应与工具规模相称）。 API 平台 → curl + 一种编程语言、身份验证流程、Webhook；按语言提供 SDK → 为每种受支持语言提供首次成功示例和操作指南、客户端生命周期、符合该语言习惯的模式；CLI → 参数／标志、退出代码、stdout/stderr 契约、非交互式／脚本化用法、Shell 补全；框架 → 脚手架、约定、生命周期钩子。要求应灵活调整，不要让每份指南都变得臃肿。

第 5 步：交付前，依据可采纳性 + 准确性标准进行自检

确认以下各项均满足（这是 reviewing-developer-guide 所要求的标准——编写者与把关者共用同一标准，确保要求始终一致）。每项都应适度：对于精简的工具，可以合理省略它不需要的内容。

1. 按目标组织——围绕开发者可以构建什么来编写；食谱按目标命名，而非按端点命名。
2. 入门指南应引导用户获得可验证的首次成功——前置条件（包括凭据的来源 + 测试 / 沙盒路径）→ 安装 → 配置凭据 → 一次真实且成功的调用 → 带有预期输出的验证步骤；内容应可运行、可复制粘贴并能实现实际价值（而非 hello-world），使用环境变量提供凭据（而非硬编码）；路径应简短、畅通（符合 TTFC 意图）。
3. 核心概念应齐备，并置于参考文档 / 食谱之前。
4. 集成操作指南应涵盖所提交的上游项目中的常见场景——按目标命名、以代码为中心、可独立遵循、可运行，并链接至参考文档。
5. 端到端教程应构建一个小型的实用项目，并与用于查阅的食谱分开。
6. 最佳实践应以实际使用为依据——身份验证 / 密钥、可重试与致命错误、重试 + 幂等性 + 退避、分页、速率限制、Webhook（适用时）、资源管理——提供推荐模式 + 代码片段，而非罗列选项。
7. Diataxis 模式应正确分类并彼此分开——不得混淆不同模式。
8. 链接至 api-reference，不得重复其中的内容。
9. 代码示例应可运行，且准确反映实际 / 当前工具——每个示例都应体现所提交上游项目中的真实功能 / 端点；不得与上游契约相矛盾；应注明所针对的工具版本。
10. 应说明工具版本管理与迁移——版本方案、弃用政策 / 时间线、变更日志链接，以及每次主版本升级前后的说明。
11. 以事实为依据，不得捏造——功能 / 端点 / 代码应反映上游项目；对资料缺口应明确说明为假设，不得自行编造。
12. 迭代修改应保持为清晰的增量——就地编辑，检查工具变更是否导致示例过时，保持内容内部一致，升级指南自身的版本 + 更新变更日志，并标记已被取代的内容（第 6 步）。（全新首次编写时不适用。）
13. 应提供故障排查 / 常见错误路径——常见且可预见的错误应能由用户自行解决（症状 → 原因 → 修复方法）；内容应适度（对于精简的工具，可并入入门指南）。
14. 易于查找——初次阅读的用户无需预先了解 API，就能找到入门内容 + 自己目标对应的章节（明确标示入口 + 按读者旅程排序）。

输入不足时的把关要求：如果指南必须讲解的某个场景无法通过调研确认，甚至无法合理假设为可运行的食谱，应将其明确列为阻塞项（“集成场景定义不足——需要 api-reference / 产品决策”），而不是编造端点或代码路径。

第 6 步：修订现有指南（迭代／增量）

开发者指南是最常需要修订的文档——其主题（工具）会不断变化：推出新版本、弃用或重命名端点、更改签名、新增身份验证流程。修订由上游变化驱动 + 内部调整，没有衍生文档下游（指南是叶节点——唯一的使用者是开发者自己的集成）。修订时（提供现有指南、变更请求和已变更的上游内容）：

1. 明确变更范围。 说明本次增量涉及哪些内容（涉及哪些配方／示例／概念／步骤，针对哪个工具版本），以及哪些内容刻意保持不变。
2. 就地编辑——只更改受影响的内容块；不要重新生成整份指南（这会丢失来源信息，还可能破坏未受影响且仍然准确的示例）。
3. 执行由上游变化驱动的过时内容检查——找出指南中所有引用已变更／已移除功能的位置（示例、配方、概念、入门调用、API 参考指针），并逐一更新，确保其符合当前工具状态。示例仍在调用已移除／已重命名功能，是影响最大的修订缺陷（因过时内容而捏造事实）。
4. 重新确保内部一致性——先讲概念再讲配方的顺序仍然成立；端到端教程仍可运行；配方与（可能已变更的）概念部分没有矛盾；首次成功验证仍然有效。
5. 更新指南文档的版本并记录变更——提升指南自身的版本（与工具版本和技能的语义化版本不同）；添加一条变更日志记录（谁／何时／更改了什么／为什么，例如“更新以适配 SDK v3——Client(key=) → Client.from_env()”）。
6. 标记已被取代／已弃用的内容——注明版本和替代方案，而不是悄悄删除，以便仍在使用旧版本的开发者了解如何操作。

规则

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

• 讲解并链接到 api-reference；绝不重新推导目录。 完整选项请指向该参考资料，不要在指南中重新列出参数、类型或错误。
• 入门指南必须引导用户取得可验证的首次成功。 提供一条快速、可运行、可复制粘贴的路径，完成一次真实的成功调用，并以验证步骤结束；凭据必须来自环境变量或配置文件，绝不能硬编码；说明凭据的来源，并引导用户使用测试环境或沙盒。
• 先讲概念，再讲参考资料。 在介绍操作步骤或参考资料前，先解释心智模型。
• 按目标组织，而非按端点组织，并清楚标明从哪里开始。
• 正确区分 Diataxis 模式并保持彼此分离。 不要把参考资料塞进教程，不要把概念藏在操作指南里，也不要混合操作指南与教程。
• 代码示例必须可运行，并准确对应当前工具。 绝不能提供上游资料未展示的功能示例；注明目标工具版本。
• 故障排除应当是一条适度的自助路径——将常见且可判断的错误对应到解决方法；对于内容较少的工具，绝不要强制要求设置名为“故障排除”的章节（将其并入入门指南）。
• 就地修改，并全面检查过时内容。 工具变更时，查找并修正所有过时的示例、操作步骤和引用；更新指南版本和变更日志；标记已被取代的内容。绝不要重新生成整份指南。
• 绝不捏造。 不要虚构端点、功能、安装命令或代码路径。没有来源时，应将其明确标记为假设。
• 使用提供的上游资料；绝不从白纸开始，也绝不只覆盖一个硬编码输入。 缺少预期的上游资料时（例如，非 API 工具没有 api-reference），应基于现有资料编写，并将资料缺口标记为假设。
• 组合内容，而非重复内容。 章节结构采用模板工具的结构；本技能负责填充内容。
• 写叙述性内容，而非目录、面向终端用户的帮助或工程文档。

偏好（可覆盖）：

• “全面”决定输出的目标范围；内容仍应与工具及其类型相称——精简的 CLI 应合并操作步骤、简化概念，并将故障排除并入入门指南；功能广泛的 API 平台则应扩展操作步骤、Webhook、故障排除及迁移说明。衡量标准是首次成功，以及正确的生产环境集成，而非字数。
• 如果工具提供多种 SDK，优先提供多语言示例（每种语言各有一个首次成功示例）；对于 API，优先提供 curl 和至少一种语言的示例。
• 推荐使用基于游标的分页和带随机抖动的退避重试模式；详尽选项留给参考资料。

常见问题

• 在指南中重复列出 api-reference。 讲述使用场景，展示聚焦的操作指南，并链接到完整的选项集。
• Hello-world 式入门教程。 首次成功必须带来实际价值，并提供可验证的检查，否则读者无法建立信心。
• 在示例中硬编码凭据。 这会教人采用不安全的做法，而且读者也无法运行示例。每次都从环境变量或配置中读取。
• 没有明确的入门指引。 直接把读者丢进端点、没有任何引导的指南会被弃读；应标明入口并安排好学习顺序。
• 操作指南和教程混为一谈。 这是最常见的 Diataxis 失败模式——第 4 节中的操作指南应作为查阅资料，教程则应是一个循序渐进的构建过程。
• 教程中混入参考资料。 只提及当前步骤所需的内容，其余内容用链接指向。
• 工具变动后示例过时。 这是最主要的维护失败模式——工具发生任何变更时，都要检查每个示例和操作指南，找出已移除或重命名的功能（第 6 步）；过时的示例看起来没问题，运行时却会出错。
• 故障排查一节只罗列通用调试建议。 应列出该工具常见且可预知的错误，并对应给出具体的修复方法，而不是“检查日志”。
• 上游资料不足时，捏造端点或功能。 应将信息缺口作为假设明确说明。
• 复述模板大纲。 应结合判断来填写各个章节，而不是照抄大纲。

对比示例——泛泛而谈（看似合理）与可直接采用（用它来自我检查）：

方面	泛泛而谈（拒绝）	可直接采用（交付）
入门教程	“安装 SDK 并发起一次调用。”	“1. pip install acme；2. 从 Dashboard → API keys 获取 TEST 密钥；3. export ACME_KEY=...；4. 运行这段 6 行代码来创建一笔扣款；5. 预期结果：{\"id\": \"ch_...\", \"status\": \"succeeded\"}；如果出现 401，说明密钥有误 → 查看故障排查。”
概念	“SDK 有一个客户端。”	“Client 保存你的密钥和连接池——创建一个并重复使用；每个领域对象（Charge、Customer）都是你通过它操作的资源。”
操作指南	“有一个发送消息的方法。”	“发送短信——client.messages.create(to=..., body=...)；返回一个带有 sid 的 Message；完整参数列表（媒体、定时发送）请参阅参考文档。”
参考资料（链接而非重复）	指南重新列出全部 40 个端点及其参数表	“各端点的完整参数、类型和错误说明请参阅 API reference——这是权威信息源；本指南会链接到其中的相关内容。”
故障排查	“如果无法运行，就调试一下。”	“429 Too Many Requests → 触发了速率限制；请延迟重试并遵守 Retry-After（请参阅最佳实践）。”
修订	为 SDK v3 重新生成整份指南	编辑受影响的示例，将所有 Client(key=) 替换为 Client.from_env()，更新指南版本和变更日志，并标记 v2 操作指南已被取代
代码准确性	调用 api-reference 中未列出的端点	每次调用都使用所提交的 api-reference / feature-spec 为指定工具版本定义的端点或功能

如果你的内容读起来像左栏——适用于任何工具、没有可运行的首次成功体验、没有真正的概念、直接粘贴目录、没有入门指引，或不符合工具当前版本——那就还没完成。

反模式

• “我要列出每个端点，这样指南就完整了。” 这是 api-reference 的工作——讲解并提供链接。
• “Hello-world 是不错的首次调用。” 应触达真正的价值，并验证结果。
• “我会把密钥硬编码，让示例更短。” 从环境中读取密钥。
• “操作指南和教程是一回事。” 它们属于不同的 Diataxis 模式——应分别编写。
• “这也是 user-guide，所以我要面向非技术用户来写。” 受众和文档都不同。
• “api-reference 内容太少了，我来编造一些端点。” 将这一缺口明确标为假设。
• “工具发布了 v3，我只要重新生成指南就行。” 应在原文中修订，并全面检查过时示例；说明版本和变更日志，并标记已被取代。
• “跳过调研吧，我知道 SDK 是怎么工作的。” 调研能为本产品的功能范围、使用场景和惯例提供依据。
• “我自己来写大纲。” 这会重复模板工具已有的内容——应采用它提供的结构。

输出

一份全面的开发者指南，达到步骤 5 的可采用性与准确性标准（按目标组织内容并明确指出从何开始；入门指南能引导用户取得可验证的首次成功；先介绍概念，再提供参考资料；集成操作指南涵盖给定场景；端到端教程构建一个小型的真实项目；最佳实践有据可依；故障排查路径与问题规模相称；正确分类并区分 Diataxis 模式；链接至 api-reference，而不是重复其内容；示例可运行且与当前工具相符；说明工具版本管理和迁移；修订时维护指南自身的版本和变更日志；不编造任何内容）。该产物是文本形式——包含编号的设置步骤、围栏格式的安装命令和围栏格式的集成代码示例（涉及 API 时包含 curl 和至少一种语言），并用文字描述屏幕和流程；方法与标准不受媒介限制。抽象消费者是负责采用并集成工具的开发者，以及 reviewing-developer-guide（它要求达到相同的 14 项标准）。指南使用给定的上游资料（通常包括 feature-spec、api-reference 和 PRD），并向下游链接至 api-reference。指南的结构来自模板工具；此技能提供内容质量。

相关内容

• 开发者指南模板工具（例如 content-template-gateway）——提供此技能要填充的章节结构。应与其配合使用；切勿重述其大纲。
• 深度研究能力——依据 DX 文档实践（Stripe/Twilio/Auth0）、Diataxis 和开发者文档质量标准，为指南提供依据。
• reviewing-developer-guide——运行时质量关卡；用相同的 14 项可采用性与准确性标准审核完成的指南；作者与审核关卡共用一套标准，以免标准偏移。
• api-reference-authoring skill——生成详尽的端点/符号目录；本指南负责讲解并链接至该目录，绝不重新整理。
• user-guide-authoring skill——面向非技术终端用户的产品帮助；它面向不同的受众，是一份不同的文档，本技能不负责此类内容（由编写者根据 PRD 的受众选择相应技能）。
• feature-spec（所讲解的功能）、api-reference（操作指南所用的端点）、PRD（受众与价值）——典型的上游输入；如有，还包括 user-flows 和 architecture-doc。

渐进式呈现

• references/structure-onboarding.md — 深入介绍结构与入门方面：开发者文档质量评估标准 + Diataxis 模式；信息架构 / 从这里开始 / 读者旅程 + 易于浏览性 / 渐进式呈现 + 基础无障碍设计；6 步入门流程 + TTFC + 凭据获取 / 沙盒；先讲概念，再讲操作指南。
• references/bestpractices-archetype-amend.md — 深入介绍生产与变更方面：最佳实践目录（身份验证 / 错误 / 重试 / 分页 / 速率限制 / Webhook / 资源卫生）；按症状→原因→修复组织的故障排查方法；四种工具原型的补充说明；文档即代码 / 保持新鲜度的习惯；以及修订（第 6 步）过时内容扫描流程。
• references/sources.md — 方法与质量标准的研究来源（Diataxis；DX 文档 / 信息架构实践；开发者文档质量评估标准；SDK / API 文档、错误处理、重试 / 幂等性、分页、速率限制、故障排查、版本控制 / 迁移，以及文档即代码 / 常青文档指南）。仅在审查指南来源时加载。

正文篇幅限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个 token。
• 大量内容放在 references/ 中，按需加载。