authoring-api-reference

authoring-api-reference — SKILL.md

变体： standard · 使用时机： 编写（或修订）面向使用者发布的 API 参考文档——达到客户端开发者仅凭该文档就能完成身份验证、成功发起首次调用并集成其中的每项操作的标准，且每个端点、字段和错误都与上游 api-spec 契约一致（不得偏离，不得杜撰）。

概述

这项技能讲解的是如何编写高质量的面向使用者发布的 API 参考文档——供集成 API 的客户端开发者阅读和调用 API 的文档。它提供编写者的判断力——研究方法和质量标准——而非章节列表。它假设有两项协作能力：一个提供章节结构的 api-reference 模板工具，以及一项深度研究能力，用于依据成熟的公共 API 文档实践来构建入门叙述、示例和惯例。编写者拿到的是上游 api-spec（每个端点、字段和错误所依据的工程线协议约定），以及（如有）feature-spec（使用场景——每项操作的用途）和architecture-doc（身份验证／版本控制背景）——而不是一张白纸。需要达到的标准是：开发者仅凭参考文档就能完成身份验证、成功发起首次调用并正确使用每项操作，且每个记录在文档中的端点、数据结构和错误都能追溯到 api-spec 契约——不得偏离，不得杜撰。

参考文档是在 api-spec 契约之上增加的叙述、入门指引和完整示例层。它补充了入门教程、身份验证教程、完整示例、分页／错误／速率限制／弃用指南，以及契约中未涉及的故障排查——但不会重新定义、取代或违背契约。

何时启用

• 根据定义了客户端集成操作的上游 api-spec，编写面向使用者发布的 API 参考文档。
• 记录每个端点的用法（用途、带类型的参数、完整的请求和响应示例、错误响应），以及入门指南、身份验证；若 API 会发出事件，则记录事件／webhook；此外还包括分页、错误和速率限制指南、代码示例，以及版本控制和弃用说明。
• 为 api-reference 模板补充经过研究、与契约一致且可运行的端点内容。
• 在端点目录由 OpenAPI 自动生成的参考文档之上，添加人工编写的叙述、示例和偏差检查。
• 当上游契约发生变化（新增／变更／弃用端点）时，修订现有参考文档——重新同步受影响的内容（参见第 7 步）。

请勿在以下情况启用：

• 编写工程线协议契约本身（操作、完整的架构定义、内部错误模型）——这属于上游的 authoring-api-spec。api-reference 是与该契约保持一致的下游使用者文档；它引用契约，而不是重新推导契约。
• 编写终端用户产品指南／开发者采用指南（帮助产品终端用户完成任务，或介绍 SDK／CLI／平台的使用方法）——这属于面向不同受众的 authoring-user-guide／authoring-developer-guide。
• 编写持久化数据模型或系统架构——这些是独立的上游事项（authoring-data-model／authoring-architecture-doc）。
• 审核或评定已完成的 api-reference——这属于运行时门禁 reviewing-api-reference；本技能仅用于产出。
• 编写项目专属端点、SDK 教程或任何其他类型的文档。

输入

阅读计划交给你的每一份文档——即你的 depends_on 集合（上游文档；发现阶段确定这些文档会为本文档提供信息）——并追溯本文档的内容，确认其依据来自这些文档。

• 使用交给你的全部文档；不要将输入写死为一份。 上游的主要文档是 api-spec（工程线级契约；REST 使用 OpenAPI，事件使用 AsyncAPI / OpenAPI-3.1 webhooks，GraphQL 使用 SDL，RPC 使用 proto）；如有 feature-spec（使用场景），也要阅读；如有 architecture-doc（认证/版本控制相关背景），同样要阅读。此处列出的典型上游文档仅为方法指引，不限制你实际收到的文档。
• 修订时，你还会收到现有参考文档和变更内容（已变更的契约 / 变更请求）。请参阅步骤 7。
• 从 api-spec 推导每个端点。 参考文档中的每个端点、参数、字段类型、必填/可选标记、错误代码、事件和认证方案，都必须来自交给你的契约。契约提供事实；研究提供惯例（入门指南/错误文档/速率限制/分页/示例格式）——不提供端点。
• 确保文档自包含，并能妥善处理上下文缺失的情况。 根据你实际收到的所有上下文编写参考文档。如果缺少预期的信息来源（例如没有单独的 feature-spec），则仅依据 api-spec 继续编写，并将信息缺口明确标注为假设——绝不捏造端点、参数、字段、错误或事件来让文档显得完整。
• 如有可用的研究能力（deep-research），请使用它，以成熟的公开 API 文档实践为参考，而不只是填充模板。如果没有研究能力，则将惯例明确标注为假设——绝不捏造。

工作流程

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

使用你的 API 参考文档模板工具（content-template-gateway，综合版）获取章节结构。不要在此处重述或重新推导章节列表；本指南提供的是填充这些章节的方法。如果没有可用模板，则获取一份完整的 API 参考文档结构（申请/创建一份，或使用规范章节集作为后备：概览、入门指南、认证、基础 URL + 版本控制 + 弃用、逐端点参考、事件/webhooks、核心对象、分页/筛选/排序、错误、速率限制、代码示例 + SDK、API 版本控制 + 更新日志、文档自身的修订历史），然后继续。

步骤 2：加载上游文档；依据 api-spec 确保覆盖完整

阅读上游 api-spec 及交给你的所有上下文（feature-spec、architecture-doc）——这些就是你的输入，不是空白页。api-spec 中的操作是你的端点覆盖检查清单：契约中声明的每项操作（以及每个契约声明的事件/webhook）都必须出现在参考文档中；参考文档中的每个端点/事件也都必须存在于契约中（不得有孤立或虚构的端点，也不得有遗漏）。从契约中提取每项操作的参数、字段类型、错误响应和认证方案——不得自行重新输入或与之矛盾。如果上游信息不充分（例如契约列出了某项操作，却未说明其使用场景），则将信息缺口明确标注为假设，绝不默默编造形式或结构。

Step 3：选择模式——默认以文字说明为先，适配生成方式

判断项目如何呈现端点目录：

• 手动编写（默认）。 根据 api-spec 手动编写面向使用者的参考文档：入门／身份验证说明、完整的请求／响应示例、各端点的文字说明，以及契约一致性检查。
• 根据 OpenAPI 生成。 如果项目会自动生成端点目录（Swagger UI、Redocly、Stoplight、Mintlify、Fern、Scalar），目录会因自动生成而保持最新——不要重新手动编写它（手动重写的副本会立即出现偏差）。你的工作转而侧重于：(i) 生成器不会编写的入门／身份验证说明，(ii)示例质量（可运行的完整请求／响应示例 + 代码示例），以及 (iii) 对生成内容的偏差／一致性检查。更深层的规范是文档即代码，单一事实来源：OpenAPI 描述是 SSoT，目录由它生成，而契约测试（根据规范验证实时响应）是自动化的偏差防护机制——人工偏差检查则对说明、示例和手写部分进行补充。

同一项技能，同一工作的两种呈现方式。两种模式的质量标准（Step 6）完全相同——生成方式改变的是由谁编写端点表，而不是参考文档是否易用且与契约一致。

Step 4：开展研究，为说明和惯例提供依据

通过深入研究，依据成熟的公共 API 文档实践（Stripe／Twilio 风格的标准）编写参考文档——针对这个产品的接口，而非泛泛地编写“API 文档”。研究的内容包括入门快速入门的结构、身份验证指南、错误文档惯例、速率限制／重试惯例、分页惯例、弃用／终止服务惯例，以及代码示例惯例。如果没有研究能力，不要编造惯例、状态码或限制——应将它们明确标记为待验证的假设。

Step 5：应用各部分的编写方法

按照此方法填写模板各部分。对于不需要某部分的简单 API，可将该部分精简；篇幅应与实际需要相称。（各项惯例的详细说明见 references/conventions-and-styles.md。）

• 概览 + 快速入门 — 完成首次成功调用。 快速入门部分必须先端到端完成一次成功调用（获取密钥、发出一个请求、识别响应），然后再介绍高级功能。这是最能推动用户采用的部分。
• 身份验证指南 — 说明使用的流程，展示成功和失败。 说明契约使用的方案／流程——静态 API 密钥，或具体使用哪种 OAuth 2.0 流程（授权码／客户端凭据／PKCE）——作用域（遵循最小权限原则，按需逐步申请）、凭据获取方式、确切的发送方法（附完整示例）、令牌生命周期（过期 + 刷新），以及成功情况和身份验证失败（401／403）响应。（持有令牌代表获得了委托的授权，而非证明身份。）
• 基础 URL + 版本管理 + 弃用 + 约定。 基础 URL、版本的表示方式、开发者如何固定版本／升级、哪些变更属于破坏性变更、弃用／下线政策（见下文），以及预先说明的约定（内容类型、日期格式、ID 格式、幂等键、请求 ID 标头）。
• 逐端点参考 — 完整演示每项操作。 对契约中的每项操作，说明：方法 + 路径、用途说明、带类型的参数（路径／查询／正文，逐项标明必填／可选及约束）、包含真实值的完整请求示例、完整响应示例（成功响应 — 至少一个失败响应）、返回的错误／状态码及其原因 + 解决方法，以及操作已弃用时的弃用标记（弃用时间／下线时间／迁移目标）。只展示 200 正文的内容块不算完成。（对于 GraphQL，应根据架构文档记录操作；对于 gRPC，则记录服务方法——每项操作的要求相同。）
• 事件／Webhook — 说明 API 会在哪里发出事件。 记录事件目录（每种事件类型 — 与操作相反的方向）、每种事件的负载架构 + 示例、签名验证（对原始正文 + 时间戳使用 HMAC，以阻止重放），以及投递语义（至少一次投递 → 使用投递 ID 幂等键；带退避的重试；在 N 秒内返回 2xx 确认）。内容应与实际情况相称 — 仅支持请求／响应的 API 可省略。
• 核心对象／共享数据类型 — 每种只定义一次。 在核心对象部分定义每种可复用的对象结构，随后在各端点／事件内容块中引用；不要在每个端点中重复定义资源。
• 分页／筛选／排序 — 模型只说明一次。 对包含列表操作的 API，说明模型（针对大型／变化中的集合使用游标，针对小型／稳定集合使用偏移量）、标准参数名称（limit、after／before、page／per_page）、响应元数据（可行时提供 has_more、next_cursor、total_count）、默认页大小 + 文档说明的最大页大小、最后一页的标志，以及稳定且打破平局的排序方式（使用唯一的次级键，确保跨页排序具有确定性）。内容应与实际情况相称 — 如果没有列表操作则省略。
• 错误指南 — 作为一等内容，明确命名标准。 只定义一次一致的错误响应结构（优先采用 RFC 9457 Problem Details、application/problem+json，这是 7807 的后续标准），状态码表（原因 + 解决方法）、区别于 HTTP 状态码的机器可读错误 code，以及语义正确的状态码（速率限制用 429、冲突用 409、下线用 410）。只介绍 2xx 的文档会迫使开发者靠反复试错来了解失败情况。
• 速率限制。 说明限制、429 信号、Retry-After（以及适用时的 RateLimit-*／X-RateLimit-*，并注明它们在 429 响应中由 Retry-After 取代）、指数退避 + 随机抖动，以及用于安全重试的幂等键。
• 代码示例 + SDK。 对每项主要操作提供 curl + 至少一种语言的示例，且示例值须与架构完全一致；仅在存在官方 SDK 时才增加其他语言。不要为了凑数而提供未随产品发布客户端的语言示例。
• API 版本管理 + 更新日志。 说明版本管理／弃用政策，并提供按日期标注、从新到旧排列的 API 更新日志（记录 API 表面发生的变更）——与文档自身的修订历史（第 7 步／修订日志）区分开来。

Step 6：交付前根据易用性与契约一致性标准进行自检

确认以下各项均满足（这是运行时审核关卡采用的标准——作者与关卡共用同一标准，来源一致，因此不会出现偏差）。cond-5 是关键检查项。

1. 可完成首次调用——入门指南和身份验证说明（明确命名方案/流程、提供可获取并发送的凭据，以及身份验证失败的示例）能让开发者完成身份验证，并通过复制粘贴端到端地成功完成首次调用。
2. 记录每项操作——api-spec 中的每项操作（包括契约声明的事件/Webhook）都包含用途、类型化参数、完整的请求示例、完整的响应示例及其错误响应。不能遗漏任何契约操作；文档中也不能出现契约未声明的操作。
3. 将错误作为一等内容处理——采用统一的错误结构（Problem Details 格式）+ 机器可读代码 + 状态码表 + 各端点的错误行 + 语义正确的状态码。只涵盖 2xx 的参考文档不合格。
4. 记录速率限制——记录限制、429、Retry-After、RateLimit-*、退避与抖动、幂等键（按实际情况处理——如果 API 没有限制，则无需说明）。
5. 与契约保持一致——每个端点、字段类型、必填/可选标记、错误代码、事件和身份验证方案都能追溯到 api-spec；不得偏离或捏造内容；不得手动重复输入生成的目录。这是关键检查项。
6. 示例可运行且保持一致——提供 curl 示例和至少一种语言的示例，使用与架构完全匹配的真实值。与其架构矛盾的示例属于缺陷。
7. 说明版本控制与弃用——说明版本控制/弃用政策（Sunset/Deprecation 机制、已弃用接口的迁移路径），并提供注明日期的 API 更新日志（按实际情况处理——仅适用于 v1 的 API 可从简）。
8. 共享类型仅定义一次并供引用——可复用对象在核心对象章节中定义一次，并在需要时引用，而不是在每个端点下重新定义。
9. 有据可依，不得捏造——端点/事件须与 api-spec 一致；约定须基于调研所得的实践；将缺失信息列为假设，而不是自行编造。
10. 分页/列表约定（按实际情况处理）——对于包含列表操作的 API，须一次性记录模型、标准参数、元数据、默认值/最大值以及采用稳定排序规则打破平局的排序方式。不提供列表操作的 API 无需此项。
11. 修订（针对修订内容）——差异须与变更后的契约重新同步，重新检查示例，记录弃用/迁移信息，并更新文档版本和修订日志（Step 7）。全新初次构建时不适用。

输入信息不足关卡：如果无法按标准记录契约中声明的某项操作（例如缺少使用场景或错误响应信息，且无法通过调研或可信假设补足），应将其列为阻碍项（“操作文档不足——需要 api-spec 作者/产品决策”），而不是捏造结构。端点、错误或示例含有猜测内容的参考文档，不适合用于安全集成。

步骤 7：修订现有参考文档——由上游驱动的重新同步

收到现有参考文档和一项变更后（最常见的是上游 api-spec 契约发生变化），只修改差异，不要重写。（详细说明和示例见 references/amend.md。）

1. 界定变更范围，确定受影响的端点、字段、错误、事件和身份验证；只编辑相关部分，保留未变更的目录。
2. 根据变更后的契约重新同步——仅对变更部分重新执行 cond-5 一致性检查：每个变更或新增的端点、字段和错误都必须能追溯到变更后的 api-spec；已移除的契约操作也必须移除（或标记为已弃用）。如果编辑时发现契约缺口（文档需要某项契约未声明的操作），请向 api-spec 作者反馈——绝不要擅自编造。
3. 同步内部连带变更——共享对象条目及所有引用它的端点；根据新架构重新检查示例和代码样例（过时的样例属于缺陷）；以及各端点的错误行。
4. 处理弃用→停用生命周期——移除或变更的端点必须标记为已弃用（包括 Deprecation/Sunset、停用日期和迁移指南/替代项链接），并在过渡期内保留；只有在停用后才能移除，不能悄然删除。
5. 版本 + 修订日志——提升参考文档自身的版本，并添加一条记录谁在何时因何原因做了哪些修订的日志条目，同时标记已被取代的内容。这与API 变更日志（API 中发生了什么变化）以及技能版本均不相同。

API 风格补充指南（编写辅助——按比例应用，以结果评判）

参考文档的结构会随 API 风格而变化：REST（默认——资源 + 逐端点表格）、GraphQL（一个端点 + 类型化架构；记录类型 + 查询/变更/订阅，而非路径表格）、gRPC/RPC（proto + 方法 + 流式传输）、webhooks/事件驱动（上文的事件目录）、流式传输/WebSocket/SSE（连接生命周期 + 消息架构）。这些辅助指南根据 API 特性设定，按需应用——标准会相应调整，不会导致文档臃肿。（详见 references/conventions-and-styles.md。）**不在范围内（由渲染后的文档站点负责，而非此 Markdown 文档）：**全文/AI 搜索、交互式试用功能/API 浏览器/Postman 集合，以及文档站点的无障碍/i18n——此方法与媒介无关；不要在此处夸大其涵盖范围。

规则

硬性规则（绝不违反）：

• 每个端点都必须依据契约。 每个端点、参数、字段类型、错误代码、事件和认证方案都必须来自提供的 api-spec。不得出现无依据或虚构的端点，也不得遗漏契约中定义的操作。
• 绝不捏造。 不要为了显得完整而虚构端点、参数、字段、状态代码、错误、事件或限制。如果没有来源，请将其明确标记为有待验证的假设。
• 与 api-spec 保持一致，不得偏离。 字段类型、必填／可选标记、错误代码、事件和认证方式都必须与契约一致。参考文档可以补充说明、新手引导和完整示例，但不得重新定义或与契约矛盾。文档中记录了契约未声明的端点，或包含了契约中没有的字段，都属于缺陷。
• 记录错误，而不只是成功场景。 使用统一的错误结构，以及状态代码表和各端点的错误行。只列出 2xx 的参考文档是不完整的。
• 确保能完成首次成功调用。 新手引导和认证流程必须从头到尾可执行，并最终成功完成一次调用，然后再介绍高级功能。
• 示例必须符合架构。 每个完整的请求／响应示例和代码样例都必须使用契约声明的准确字段名、类型和状态代码。示例与其架构矛盾即为缺陷；每次修改契约后都要重新检查示例。
• 提供 curl 和至少一种语言的示例，不要凑数。 示例必须包含 curl 和至少一种语言；只有在存在官方 SDK 时才添加更多语言示例。
• 每种结构只定义一次。 共享对象类型放在一个核心对象章节中定义，并在其他地方引用；不要在每个端点中重复定义资源。
• 通过重新同步来修订，而不是重写。 契约变更时，编辑受影响的部分，重新检查变更差异的一致性，复核示例，记录弃用／迁移信息，更新文档版本并修订日志。不要悄悄删除已移除的端点；应将其标记为弃用并提供迁移路径。
• 组合内容，不要重复。 按照模板工具中的章节结构编写；本指南说明如何填充这些章节。不要另起一套结构。
• 面向使用者的参考文档，不是线协议契约，也不是最终用户指南。 编写面向开发者发布的参考文档，而不是工程用 api-spec（上游资料）、面向最终用户的产品指南（受众不同）或实现文档。

偏好（可覆盖）：

• “全面”决定输出的目标范围；但仍须保持适度——精简的 API 应省略不需要的章节（没有列表操作就不需要分页；有 SDK 后再添加 SDK 表；适用时才添加 Webhook／速率限制／弃用内容；变更日志可以从一行开始）。评判标准是开发者能否完成集成，而不是文档字数。
• 在资源分组内，优先按照开发者实际使用操作的顺序编排（创建 -> 获取 -> 列出 -> 更新 -> 删除）。
• 让 curl 示例与语言示例保持一致，使开发者能看到同一调用的两种写法。

注意事项

• 偏离契约。 参考文档悄然偏离 api-spec——例如，文档中有某个端点，但契约已将其删除；参考文档展示了契约从未声明的字段；或参考文档遗漏了某个错误——这是危害最大的缺陷。无论手工编写还是生成，都会出现同类问题；漂移检查（步骤 6.5）在这两种模式下都会加以防范。
• 端点只展示成功路径。 展示 200 响应正文后就结束，是参考文档最常见的缺陷。每个端点都必须至少展示一种失败情况及其返回的错误／状态码。
• 重新手动编写生成的目录。 如果目录由工具生成，手动重写就等于重复实现生成器，并会立刻产生偏差。让生成流程负责目录；把精力放在说明文字、示例和漂移检查上。
• 契约变更后示例过时。 修改契约后，如果示例或代码样本没有随架构变更而更新，看起来能运行，实际上却无法运行。重新检查变更涉及的每个样本（步骤 7.3）。
• 混淆三种变更日志。 API 变更日志（API 表面有哪些变化）、文档自身的修订日志（本文档如何变化）和技能版本是三种不同的东西。修订日志和文档版本属于文档；API 变更日志属于 API。
• 悄然删除已移除的端点。 已移除／变更的操作应标记为弃用并提供迁移路径（Sunset/Deprecation，日落后返回 410），而不是在集成方毫无准备时直接删除。
• 混淆参考文档、线缆契约和终端用户指南。 api-spec 是工程契约（上游且完整）；api-reference 是基于它发布的使用方文档。user-guide/developer-guide 面向的是不同受众。请将本文档定位为开发者集成参考。
• 复述模板大纲。 在内容中（或本技能中）重新推导章节列表，会重复模板工具的工作并逐渐偏离；应结合判断来填写各章节。

对照示例——看似完整与可集成（用于自查）：

方面	看似完整（不合格）	可集成（可发布）
首次调用	“先进行身份验证，然后调用 API。”	可直接复制粘贴的 curl 快速入门：从仪表板获取密钥，使用 Authorization 标头调用 GET /v1/widgets，并展示预期的完整 200 响应正文。
身份验证	“使用 OAuth。”	“Client-Credentials 流程；请求作用域 widgets:read；POST /oauth/token → 获取有效期为 1h 的 Bearer 令牌；遇到 401 时刷新。”——包含流程、作用域、生命周期和失败处理。
端点覆盖范围	“已记录主要端点。”	api-spec 中的每个操作（和事件）都有对应章节；索引与契约一一对应。
参数	“接受 widget 字段。”	“name（字符串，必填，最长 255），status（字符串，可选，取值为 active／archived，默认值为 active）。”——信息来自契约。
分页	“返回列表。”	“游标分页：limit（最大值 100，默认值 20）和 starting_after；has_more 和 next_cursor；先按 created 排序，再按 id 排序（用于打破平局）。”
错误	“失败时会返回错误。”	Problem-Details 结构 + 机器可读的 code + 各端点对应的行（400 invalid_request、404 not_found、409 conflict）+ 状态码表——涵盖契约中的所有代码。
弃用	（端点被悄然删除）	“GET /v1/charges/legacy——于 2026-06-14 弃用，日落日期为 2026-09-12，请迁移到 GET /v1/charges。”
一致性	（无追溯关系）	每个端点／字段／错误／事件都能追溯到 api-spec；文档中没有任何契约未声明的内容。

如果你填写的内容读起来像左栏——对任何 API 都适用，没有实际示例、没有错误场景，也无法追溯到契约——那就还没完成。

反模式

• “api-spec 内容很少，我来补上合理的端点和参数。” 绝不编造。应从契约中推导；将缺失内容列为假设或阻塞项。
• “我只写正常流程的规范，错误情况显而易见。” 并非如此——应记录每个端点的失败响应和状态码。
• “目录是自动生成的，我的工作就完成了。” 自动生成能提供目录，却无法提供入门叙述、优质示例或偏差检查——这些才是人工编写的价值所在。
• “这也是线级契约，所以我要把内部架构规范写得面面俱到。” 契约位于上游；参考文档是建立在契约之上的使用者文档。应引用契约，而不是重新推导。
• “这也是面向最终用户／开发者采用的指南。” 受众不同——这是开发者集成参考文档。
• “最佳实践要求这么做，所以我要添加 GraphQL／webhook 章节。” 附加内容应与需求相称——只有 API 涉及相应接口时才添加；不要让 REST 参考文档臃肿。
• “这个端点已经移除，我直接删掉对应部分就行。” 应标记为弃用并提供迁移路径；不要让集成者措手不及。
• “我自己来写大纲。” 这会重复模板工具的工作——应使用模板工具提供的结构。
• “跳过调研吧，我知道好的 API 文档是什么样。” 调研为此产品的入门指引、错误文档、分页和示例惯例提供依据——而非 API 文档理论。

输出

一份完整且已发布的 API 参考文档（或重新同步后的修订版），达到第 6 步的易用性＋契约一致性标准（可顺利发起首次调用；api-spec 中的每个操作／事件都记录其用途、带类型的参数、完整请求示例、完整响应示例及错误；错误作为一等内容呈现，包含一个符合 Problem Details 格式的错误示例和状态码表；记录速率限制；与契约保持一致——每个端点／字段／错误／事件均可追溯，无偏差、不编造内容；示例可运行且符合架构；适用时说明分页惯例；说明版本管理和弃用；共享类型只定义一次；内容详略得当；修订时重新同步并记录文档版本）。该产物为文本形式——包含端点章节以及带围栏的请求／响应示例和代码示例；方法和标准不依赖具体媒介（目前通过本地文档后端使用 Markdown；未来渲染出的文档站点只改变媒介——搜索、试用功能、无障碍和 i18n 由该站点负责，而非此技能）。抽象使用者是仅凭参考文档集成 API 的客户端开发者；运行时审查门也会验证同一标准。api-reference 依赖 api-spec（并在存在时引用 feature-spec／architecture-doc）作为输入。其结构来自模板工具；此技能负责提供内容质量。

相关内容

• 一个 api-reference 模板工具（content-template-gateway）——提供此技能要填写的章节结构。与其组合使用；切勿重复撰写其大纲。
• 一项深度调研能力（deep-research）——借鉴成熟的公开 API 文档实践，为入门叙述、示例和惯例提供依据。
• 一项 api-spec 编写技能（authoring-api-spec）——产出上游工程线级契约；本参考文档中的每个端点、字段、事件和错误都由其推导并与之保持一致。
• 一份 feature-spec 和一份 architecture-doc（如有）——上游背景信息：每个操作的使用场景，以及身份验证／版本管理背景。
• 一个审查门（reviewing-api-reference）——在运行时验证成品是否达到同一易用性＋契约一致性标准；作者和审查门共享同一标准（单一来源），避免出现偏差。
• 一项面向最终用户的产品指南／开发者采用指南技能（authoring-user-guide／authoring-developer-guide）——文档和受众都不同（产品的最终用户，或指向此参考文档的 SDK／CLI 采用指引）。

渐进式披露

• references/conventions-and-styles.md — 认证流程细节（API 密钥 / OAuth2 流程 / 作用域 / 令牌生命周期）、RFC 9457 问题详情错误模型、速率限制 / RateLimit-* / 幂等机制、分页约定（游标/偏移量、标准参数、元数据、带平局判定的排序），以及 API 风格覆盖项，包括 Webhook/事件文档编写方法。填写这些部分时加载。
• references/amend.md — 上游驱动的重新同步修订流程、弃用→日落生命周期（RFC 8594/9745）、三种变更日志的区别，以及修订示例。进行修订时加载。
• references/sources.md — 方法的研究来源和质量标准。仅在审核指导内容的来源时加载。

正文篇幅限制

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

更新日志

• 1.1.0（2026-06-14）— 生产级重构（增补式；与 reviewing-api-reference 的 11 项条件标准共用单一来源）。新增迭代/修订方法（第 7 步——上游驱动的重新同步）和 references/amend.md；深化认证流程、RFC 9457 问题详情错误模型、RateLimit-*/抖动/幂等性，以及弃用/日落（RFC 8594/9745）机制；新增分页/列表操作约定和 API 风格覆盖项，包括作为编写辅助的 Webhook/事件文档，以及 references/conventions-and-styles.md。第 6 步自检从 9 项增至 11 项。输入约定和媒介保持不变。
• 1.0.0（2026-06-05）— 首个经审核的版本。