docs-writer 是一个用于起草或重写 Strands Agents 文档页面的技能。根据输入资料，它适用于撰写新的文档页面、重写未通过审核的页面，以及为现有页面起草章节。
用途
该技能的目标是帮助产出符合 Strands Agents 文档规范的页面内容。它针对不同的内容类型（教程、操作指南、参考、解释、博客）提供写作流程，并遵循所谓的五层语气栈。
输入
使用该技能时，需要提供以下输入：
- 内容类型：tutorial、howto、reference、explanation、blog（必填）
- 主题：该页面覆盖的内容（必填）
- 目标文件：该页面在 docs 仓库中的路径（如已知）
- 现有内容：要重写的当前页面（如为重写场景）
- 上下文（可选）：激发这项工作的社区信号、GitHub issue 或定位主题
处理流程
资料中描述了如下步骤：
-
加载语气上下文：在写作前阅读
../../references/voice-guide.md（完整语气栈）和../../references/terminology.md（规范术语）。如果是重写，阅读当前已发布的页面作为基线。 -
大纲：产出大纲，其中每一项是某个章节所回答的问题。教程为通向可运行结果的逐步旅程；操作指南为前置条件、步骤、预期结果；参考为 API 表面（类、方法、参数）；解释为问题、设计选择、权衡、影响。每个章节回答一个问题，不混用类型，并检查范围蔓延。
-
起草：按大纲撰写每个章节。每个章节的第一句话描述开发者的目标（faming layer）；使用适合该内容类型的语气（register layer）；代码示例需可运行，使用真实的 Strands import 和现实的值；对于智能体响应，按照 voice-guide.md 中“记录非确定性行为”的模式标注非确定性输出（典型输出作为代码下方注释；工具选择使用能力语言）；注释解释意图而非机制；每个代码块只讲一个概念；片段长度匹配所演示内容的复杂度，偏向简洁；片段必须可复制粘贴运行，包含 import、已定义变量，无缺失上下文；对于平凡的 API 表面，优先使用散文而非片段。
-
应用 MDX 格式：应用
../../references/mdx-authoring.md中的 MDX 格式模式，尤其是 Tabs/Tab 语法、片段包含和标注语法。超过几行的代码示例应放在与 MDX 页面同目录的可运行.ts/.py源文件中，通过--8<--include 语法引入。 -
约束：先检查 voice guide 中按类型区分的约束覆盖表，内容类型决定哪些规则严格、哪些放宽。然后对照硬约束自查：无禁用短语（AI 腔、夸张词）、无 em-dash、无 emoji、主动语态（参考类型按覆盖表例外）、对事实不模棱两可（解释类权衡讨论中可软化）、术语与锁定文件一致、代码示例上下文完整、代码示例使用正确的反引号格式、绝不在其自身的 tab 内命名语言。
-
验证代码准确性：遵循
../../references/code-verification.md中的验证流程，不可跳过。看似合理但错误的代码示例会更快侵蚀开发者信任。 -
真实性审校：打破结构雷同（变化章节开头、使用片段、变化长度）；加入可见的编辑判断（点名被拒绝的替代方案、陈述观点）；大幅删减（初稿总是太长）；把“你可以用 X 或 Y”替换为推荐。
-
元数据：按照
../../references/mdx-authoring.md的 Frontmatter Schema 添加 frontmatter。至少包含 title 和 description（140-160 字符的 SEO 描述）。仅在适用时添加可选字段（languages、community、experimental、integrationType、category、redirectFrom、tags、sourceLinks）。不要添加 schema 不验证的字段。 -
运行 docs-reviewer：在完成的草稿上运行 docs-reviewer 技能，在呈现草稿前处理所有发现。
输出
呈现完成的草稿，包括：完整页面内容；关于语气选择的简要说明（register、关键编辑决策）；供 PM 审阅的开放问题（术语、范围、准确性顾虑）。
Git 工作流
遵循仓库 AGENTS.md 和 CONTRIBUTING.md 中描述的 git 工作流。
限制
该技能不执行以下操作：未经人工审阅自动提交；从代码生成参考文档（单独的自动生成事项）；发布或部署文档。
注意事项
始终对照 SDK 源码验证代码。最常见的失败模式是看似合理但不存在的 import 或参数名错误。术语锁定很严格：“Hook”而非“callback”，“Plugin”而非“middleware”，“Tool”而非“function”，起草前先检查。约束覆盖表按内容类型放宽不同规则，不要把教程约束应用到参考页面。MDX 中的 Tabs 语法很挑剔，需匹配 mdx-authoring.md 中的确切模式，否则构建会失败。大幅删减，初稿总是长 30-50%，真实性环节是大部分质量的来源。