docs-writing

文档编写

• 适用： 为文档站点、API 参考、文档站教程、操作指南和现有 README 编写和审核技术文档质量（Diataxis 文档类型、语气、结构、清晰度、可运行代码、格式、导航、内容卫生、便于 Agent 阅读的文档）。
• 不适用： 编辑博客教程或文章（使用外部 ghostwriter 技能，并将平台设为 blog）；从零编写 README 或重写整篇 README（使用 readme-creator；需要原地修正文案的 README 仍适用此技能）；AGENTS.md 或 CLAUDE.md 指令（使用 agents-md）；营销文案和落地页文案（使用 copywriting）；公开的 Agent 就绪度评分卡（使用 agent-ready）；Next.js llms.txt/Markdown 路由（使用 seo）；产品自身的错误字符串和 CLI 输出（使用 dx-audit；此技能涵盖描述这些内容的文档）。

模式分流

• 审核文档？→ 审核工作流。
• 编写或重写页面？→ 编写工作流。
• “改进”或“修正文档”？→ 先审核，再自行应用修复。

首先进行分类

文档类型决定适用哪些规则，因此首先要对每个文件进行分类。使用 Diataxis 指南针：页面服务于行动（执行）还是认知（理解），读者是在学习一项技能还是在应用一项技能？

	学习（习得）	工作（应用）
行动	教程	操作指南
认知	说明	参考

如果页面的不同部分对应不同答案，则属于混合类型；由 structure-diataxis 处理拆分。根据读者的任务而非文件名进行分类。README 可以用于引导或参考；入门页面可以是教程，也可以是目标导向的操作指南。

审核工作流

跟踪此检查清单：

Docs audit progress:
- [ ] Step 1: Scope to changed files unless a full sweep was requested
- [ ] Step 2: Classify each doc with the compass; name the audience
- [ ] Step 3: Run CRITICAL categories (voice-, structure-), skipping rules the type-gating table excludes
- [ ] Step 4: Run HIGH categories (clarity-, code-)
- [ ] Step 5: Run remaining in-scope categories (format-, nav-, scan-, hygiene-, review-)
- [ ] Step 6: Report per the output contract, by severity

按类别前缀加载规则文件（先加载 rules/voice-*.md，再加载 rules/structure-*.md，依此类推），但仅加载适用类别的文件。应用修复后，在最终定稿前重新运行产生问题的规则。

编写工作流

跟踪此检查清单：

Docs writing progress:
- [ ] Step 1: Pick one Diataxis type per file with the compass; name the audience and what they can do afterwards
- [ ] Step 2: Read the defaults bundles (voice-defaults, clarity-defaults, scan-defaults) plus the structure- and code- rules the type-gating table keeps
- [ ] Step 3: Draft: bottom line up front, quick start for getting-started docs, runnable example per concept, next steps for tutorials and how-tos
- [ ] Step 4: Apply the type-relevant rules to concrete weaknesses in the draft
- [ ] Step 5: Verify: run every example, resolve every link, confirm parameter names and defaults against the implementation; quote the command output

第 5 步是完成标准：示例通过运行验证、链接可以正常访问，文档才算发布，而不是因为“读起来不错”。篇幅应由读者需要完成的任务决定，而非模板；页面不需要的章节应直接删去，而不是勉强填充。

类型适用规则表

这些规则仅适用于列出的类型。在其他类型的文档中指出这些问题，等于要求作者违背 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 中对签名块的许可。

按优先级排列的规则类别

优先级	类别	影响	前缀	规则数
1	语气与风格	严重	voice-	4
2	结构与组织	严重	structure-	9
3	清晰度与语言	高	clarity-	5
4	代码示例	高	code-	8
5	格式与语法	中高	format-	7
6	导航与链接	中高	nav-	7
7	可扫描性与可读性	中	scan-	2
8	内容卫生	中	hygiene-	6
9	审核与测试	低至中	review-	3

如需查看各类别的完整规则列表，请阅读 rules/_sections.md。*-defaults.md 文件（语气、清晰度、可扫描性、审核）包含多项检查，每个文件有 2–5 项基线检查。

输出约定（审计模式）

## Documentation Audit Findings

### path/to/file.md
- [CRITICAL] `voice-defaults`: Passive voice obscures who performs the action.
  - Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."

### path/to/clean-file.md
- ✓ pass

• 按文件分组；每个文件内按严重程度排序。
• 有行号时使用 file:line。
• 每条问题都要注明规则、说明问题并提出修复方案。没有修复方案，就不应报告。
• 将通过检查的文件列为 ✓ pass，让作者知道这些文件已检查。

注意事项

• 文档类型误分类是最常见的误报来源。解释型页面缺少快速入门，或要求参考页面包含“后续步骤”部分，都是违反 Diataxis 的问题，而不是遵循 Diataxis 的问题。报告前先检查类型判定表。
• 在 *-defaults.md 规则包中引用具体的失败检查（如“voice-defaults：被动语态”），而不只是文件名，否则作者无法定位问题。
• 仅加载适用范围内类别的规则文件，按前缀筛选。范围尚未确定就加载整个文件夹，会占满上下文，并让 MEDIUM 问题掩盖 CRITICAL 问题。
• “Should”不是 bug。Google 当前的用词表用“should”表示建议，用“must”表示要求；只有句子将“should”用于陈述要求时才标记。把每个“should”都标出来，会造成大量误报。
• 看起来像真实密钥的示例密钥（如 sk_live_...）可能会被粘贴进实际代码，并触发密钥扫描器。示例凭据应使用提供商的测试前缀（sk_test_...）或有说明的占位符（YOUR_API_KEY）；参见 code-placeholders。
• 手动填写的“Last updated: 2024-03-01”如果无人维护，会让页面显得“已弃用”，还不如不写日期。只有日期可以由构建或 VCS 自动生成时，才建议采用 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（如已安装）：编辑型教程、操作指南、思想领导力文章和长篇文章，基于 blog 平台配置撰写。
• 可选外部技能 blodemd（如已安装）：搭建/部署 MDX 文档站点；本技能负责站点内容质量。

仅用于维护：evals/evals.json 包含此技能更改的回归场景；用户任务期间不会加载。