docs-writing 是一个用于撰写和审计技术文档的 AI 技能。其定位明确：IS 部分负责文档站点、API 参考、文档站点教程、操作指南文档以及现有 README 的写作与审计，关注 Diataxis 文档类型、语气、结构、清晰度、可运行代码、格式、导航、内容卫生和面向智能体可读的文档。IS NOT 部分划清边界：编辑类博客教程或文章应使用外部 ghostwriter 技能；从零创建 README 或整体重写 README 应使用 readme-creator；AGENTS.md 或 CLAUDE.md 指令文件使用 agents-md；营销和落地页文案使用 copywriting；公开的智能体就绪评分卡使用 agent-ready；Next.js 的 llms.txt/markdown 路由使用 seo；产品自身的错误字符串和 CLI 输出使用 dx-audit，本技能只覆盖描述这些内容的文档。
模式分派：审查文档时进入审计工作流；撰写或重写页面时进入写作工作流；被要求“改进”或“修复”文档时，先审计，再自行应用修复。
分类优先。文档类型决定哪些规则适用，因此必须先对每个文件分类。使用 Diataxis 指南针判断：页面服务于行动（做）还是认知（理解），读者是在获取技能还是应用技能。行动加获取对应教程，行动加应用对应操作指南，认知加获取对应解释，认知加应用对应参考。不同章节回答不同问题的页面属于混合类型，由 structure-diataxis 处理拆分。按读者的任务分类，而不是按文件名。README 可以是导览或参考，入门页面可以是教程或目标导向的操作指南。
审计工作流包含六个步骤：第一步，除明确要求全量扫描外，将范围限定为变更文件；第二步，用指南针分类每个文档并指明受众；第三步，运行 CRITICAL 类别（voice-、structure-），跳过类型门控表排除的规则；第四步，运行 HIGH 类别（clarity-、code-）；第五步，运行其余在范围内的类别（format-、nav-、scan-、hygiene-、review-）；第六步，按输出契约按严重程度报告。按类别前缀加载规则文件（rules/voice-.md，然后 rules/structure-.md 等），仅针对范围内的类别。应用修复后，在定稿前重新运行产生发现项的规则。
写作工作流包含五个步骤：第一步，用指南针为每个文件选定一种 Diataxis 类型，指明受众以及之后读者能做什么；第二步，阅读默认规则包（voice-defaults、clarity-defaults、scan-defaults）以及类型门控表保留的 structure- 和 code- 规则；第三步，起草：结论先行，入门文档提供快速开始，每个概念提供可运行示例，教程和操作指南提供后续步骤；第四步，将类型相关规则应用到草稿的具体薄弱点；第五步，验证：运行每个示例，解析每个链接，对照实现确认参数名和默认值，引用命令输出。第五步是退出标准：文档在示例运行过、链接解析通过时才算可交付，而不是“读起来不错”时。篇幅取决于读者要做什么，而不是模板：删除页面不需要的章节，而不是硬填。
类型门控表规定部分规则仅适用于列出的类型，在其他类型上标记这些规则等于告诉作者违反 Diataxis。具体包括：structure-quick-start 适用于入门页面和 README；structure-next-steps、structure-procedures 适用于教程和操作指南；code-multiple-languages 适用于多 SDK API 的参考和操作指南页面；scan-three-column-api 适用于 API 参考；hygiene-experimental-label、hygiene-planned-label 适用于不稳定或未发布功能的参考和操作指南页面；nav-agent-readable 适用于文档站点而非单个 README。其余规则适用于所有类型。教程额外获得 voice-defaults 中的 we 允许项，参考页面获得 structure-heading-overview 中的签名块允许项。
规则类别按优先级排列：第一级 CRITICAL 包括语气与语调（voice-，4 条）和结构与组织（structure-，9 条）；第二级 HIGH 包括清晰度与语言（clarity-，5 条）和代码示例（code-，8 条）；第三级 MEDIUM-HIGH 包括格式与语法（format-，7 条）和导航与链接（nav-，7 条）；第四级 MEDIUM 包括可扫读性与可读性（scan-，2 条）和内容卫生（hygiene-，6 条）；第五级 LOW-MEDIUM 为审查与测试（review-，3 条）。每类的完整规则列表见 rules/_sections.md。*-defaults.md 文件（voice、clarity、scan、review）是多重检查包，每个包含 2 至 5 项基线检查。
审计模式的输出契约规定：按文件分组，每个文件内按严重程度排序；可用时使用 file:line；每条发现须指明规则、说明问题、提出修复方案，没有修复方案的不报告；干净文件标记为 ✓ pass，让作者知道已检查过。示例格式包括以 [CRITICAL] voice-defaults 标注被动语态问题并给出改写建议。
已知注意事项包括：文档类型误分类是首要的误报来源，在解释页要求快速开始或在参考页要求“后续步骤”章节，是针对 Diataxis 的错误发现，报告前应检查类型门控表；引用 *-defaults.md 包中具体失败的检查项，而不仅是文件名；仅按前缀加载范围内类别的规则文件，在范围未知前加载整个文件夹会淹没上下文，把 CRITICAL 发现埋在 MEDIUM 之下；“should”不是缺陷，Google 当前词表用 should 表示建议、must 表示要求，只在句子陈述要求时标记 should；看起来像真实密钥的示例键（sk_live_...）会被粘贴到真实代码并被密钥扫描器拦截，示例凭据应使用提供商的测试前缀（sk_test_...）或说明性占位符（YOUR_API_KEY）；手工输入且无人维护的“Last updated: 2024-03-01”读起来像“已废弃”，比没有日期更糟，仅当日期可来自构建或版本控制时才建议 hygiene-update-metadata；在文档站点每一页都写“本指南是 X 系列的一部分”会与站点已渲染的侧边栏和面包屑重复，nav-breadcrumb-context 适用于仓库中的纯 Markdown 和有读者必须满足的前置条件的页面。此外，不要重写被要求审查的内容，除非用户说“改进”或“修复”，否则只报告并提出修复；除明确要求全量扫描外，不要审计未变更的文件。
相关技能方面：readme-creator 负责从零创建或整体重写 README，本技能就地审计和修复现有 README；agents-md 处理 AGENTS.md/CLAUDE.md 指令文件（执行优先，非面向读者的文档）；copywriting 处理营销、落地页和产品文案；dx-audit 处理产品自身的错误消息、CLI 输出和 API 人体工学，本技能覆盖描述这些内容的文档；agent-ready 处理 Mintlify/AFDocs、Is Agentic 和 Is It Agent Ready 契约，nav-agent-readable 是其内容规则；seo 处理爬虫策略、站点地图、排名以及 nav-agent-readable 所需的 Next.js llms.txt/markdown 路由；可选外部 ghostwriter（若安装）负责编辑类教程、操作指南文章、思想领导力和长文，基于博客平台配置起草；可选外部 blodemd（若安装）用于脚手架/部署 MDX 文档站点，本技能管理其中的内容质量。另有仅用于维护的说明：evals/evals.json 包含此技能变更的回归场景，在用户任务期间不会加载。