OpenClaw 技术文档技能：面向人与 AI Agent 的双轨文档治理方法论

OpenClaw 仓库中 .agents/skills/technical-documentation/ 目录定义了一个完整的“技术文档”技能（SKILL），它规定了如何构建和评审对人与 AI Agent 都清晰、可操作、可维护的技术文档，覆盖 docs/ 产品文档与 AGENTS.md/CONTRIBUTING.md 治理文档两大表面。读完本文，你将掌握该技能的完整工作流（构建/评审双模式 × 棕地/常青双语境）、其背后的文档原则规则集、Agent 指令文件（AGENTS/CLAUDE/别名文件）的规范与优先级策略、OpenClaw 仓库专属的文档覆盖层规则，以及用四个专职子 Agent 并行完成仓库级文档审计的多 Agent 编排方案。

技能定位：它解决什么问题

该技能定义在 SKILL.md 中，其目标（Purpose）是：

Produce and review technical documentation that is clear, actionable, and maintainable for both humans and agents, including contributor-governance files and agent instruction files.

关键定位点有两个：

1. 双受众：文档既要服务人类读者，也要能被 AI Agent（Codex、Claude、Cursor 等）可靠消费。技能文件由 openai.yaml 注册到平台，display_name 为 “Technical Documentation”，并声明 allow_implicit_invocation: true，即 Agent 可在合适场景隐式调用该技能。
2. 双表面：它不仅管产品文档（docs/、README、框架源文件），还管“治理文档”——即 Agent 指令文件（AGENTS.md 及各别名）和贡献者规范文件（CONTRIBUTING.md）。

技能的适用场景（When to use）清单直接写在 SKILL.md 中，可归纳为六类任务：

• 在既有产品/代码库中创建或大改文档（brownfield，棕地）；
• 构建旨在长期保持准确、可复用的常青（evergreen）文档；
• 评审文档 diff 的结构、清晰度与操作正确性；
• 执行全仓库文档审计——必须同时覆盖治理文件与产品文档表面（docs/、README*、.md/.mdx/.mdc，以及 Fern/Sphinx/Mintlify 风格的源文件）；
• 更新或评审 AGENTS.md / CONTRIBUTING.md，使 Agent 与贡献者工作流与当前仓库实践保持一致；
• 改进包含贡献流程、Issue 模板、PR 流程与评审门槛的仓库入门文档；
• 为存在别名指令文件（如 CLAUDE.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/）的仓库设计治理策略：AGENTS.md 存在时视为规范源（canonical），别名保持为兼容层；
• 诊断“Agent 文件漂移”（agent-file drift）——团队不得不反复提示才暴露缺失文件、失效命令或策略冲突的问题；
• 当仓库存在 OpenClaw 专属覆盖层时，应用其页面类型、文档信息架构（IA）、内容保留与验证规则。

总体工作流：从分类到交付的 15 步

SKILL.md 的 Workflow 部分是整个技能的操作主线，按 15 个编号步骤组织。下面按“分类 → 侦察 → 原则加载 → 分支执行 → 交付”的顺序展开。

第一步：任务分类

先将任务分类为 build（构建）或 review（评审）；再将语境分为 brownfield（在现有文档体系上做兼容式修改）或 evergreen（面向长期准确性的常青文档）。这个二维分类贯穿后续所有规则：棕地模式优先兼容现有文档 IA、工具链与发布状态；常青模式优先追求“不老化的措辞、更新策略和持久结构”。

第二步：尽早盘点全量文档范围

盘点必须同时覆盖治理与产品文档两个表面：

• 治理面：AGENTS.md / CONTRIBUTING.md 及所有别名文件（含嵌套作用域的文件）；
• 产品面：docs 目录、文档框架源文件、根目录/模块级 README。

agent-and-contributing.md 给出了具体的盘点命令，可直接复制使用：

rg --files -g 'AGENTS.md' -g 'CONTRIBUTING.md' -g 'CLAUDE.md' -g 'AGENT.md' \
  -g '.cursor/rules/*' -g '.cursorrules' -g '.agent/**' -g '.agents/**' -g '.pi/**' -g 'AGENTS.*.md'

注意 -g 'AGENTS.*.md' 这一条：它用于发现按目录/语言拆分的 AGENTS 变体文件。盘点完成后应形成一张“覆盖地图”（coverage map），确保治理面与产品面都被表示出来。

第三步：检测多语言范围

若 README/docs 存在多种语言版本，需要确定目标语言之间的 parity（对等）等级。技能的“多语言 parity 规则”（见 principles.md）要求：对任务关键内容（步骤、警告、前提条件、限制）跨 locale 对齐；若无法完全对齐，必须发布显式的 parity 状态与同步意图。

第四步：按顺序加载原则参考文件

SKILL.md 规定了明确的参考文件加载次序，这是该技能“规则分层”的体现：

1. 读 references/agent-and-contributing.md：Agent 指令与 CONTRIBUTING 工作流规则（盘点、规范/别名映射、双模式平衡、交付物标准、优先级与冲突处理）；
2. 读 references/principles.md：治理规则集（Matt Palmer 八条 + OpenAI cookbook）；
3. 若任务针对 OpenClaw 文档，先读 references/openclaw.md；
4. build 任务执行 references/build.md；
5. review 任务执行 references/review.md，并且要主动发现问题、不等反复提示；
6. 当平台/工具链选择影响建议时，查 references/tooling.md。

第五步：分支执行与主动修复

工作流后段的几条规则定义了执行纪律：

• 深度调查被显式授权：对复杂或高风险任务（无论 build 还是 review），允许运行更长时间、更深入、更穷尽的调查以换取置信度；
• 子 Agent 并行：可用时使用子 Agent 做有界并行发现/评审，再把输出合并为一份连贯的最终交付物（合并模型见后文“子 Agent 编排”一节）；
• 主动问题扫查：对治理面与文档内容面都做一次主动问题扫查（proactive issue sweep），除非用户明确要求 report-only 模式，否则在同一次通过中直接修复高置信度缺陷——“不要停留在只写警告性备注，低风险修复应当顺手完成”；
• 棕地优先兼容性：兼容现有文档 IA、工具与发布状态；常青优先持久性：不老化的措辞、更新策略、持久结构。

第六步：交付物清单

流程终点是返回交付物 + 验证备注 + parity 状态 + 剩余缺口。SKILL.md 的 Outputs 一节（见下文“输入与输出契约”）对交付物做了逐项约束。

核心原则规则集：principles.md

principles.md 是整个技能的“宪法”，整合了两套外部规则。

Matt Palmer 的 8 条文档规则

作为默认操作原则：

1. 为人写作，为 Agent 优化（Write for humans, optimize for agents）——本技能双轨思想的核心；
2. 以漏斗开场：what/why、quickstart、next steps；
3. 用 Diataxis 框架搭建内容（教程/操作指南/参考/解释四分法）；
4. 可以用 AI 写作，但结构必须为 Agent 设计；
5. 把例行文档运维下放给后台 Agent；
6. 用 CI 自动化质量检查；
7. 自动化脚手架与重复性工作流任务；
8. 让贡献容易且可见。

OpenAI cookbook 的质量约束

• 优先使用具体、准确的术语，而非小众行话；
• 示例保持自包含、最小化依赖；
• 优先覆盖高价值主题，而非穷尽边缘情况；
• 不教授不安全模式（例如暴露密钥的示例）；
• 以能帮助读者快速定位的上下文开场；
• 运用同理心，当僵化规则明显损害效果时可以覆盖规则。

冲突时的合并策略（Practical merge policy）

两套规则冲突时，按以下顺序取舍：

1. 先保住读者的任务成功（task success）；
2. 其次保住结构清晰度；
3. 再次保住长期可维护性；
4. 只有在不降低人类可读性的前提下，才叠加 Agent 优化。

此外还定义了执行策略：允许长时调查；允许子 Agent 做有界并行；所有子 Agent 输出必须归一化为一份一致的建议/修复集（Keep one merged outcome）。

多语言 parity 规则

若文档存在多语言版本，任务关键内容（步骤、警告、前提、限制）必须跨 locale 对齐；无法完全对齐时，发布显式的 parity 状态与同步意图。

Agent 指令与 CONTRIBUTING 治理：agent-and-contributing.md

agent-and-contributing.md 是治理面的权威规则源（source of truth），可拆成六个子主题。

硬性要求（You must）

1. 用上文 rg --files 命令发现仓库级与嵌套的指令文件；
2. 编辑前先读根目录与最近作用域的 AGENTS.md/CONTRIBUTING.md 对；
3. 若存在别名文件，归一化到一个规范源（AGENTS.md 存在时优先，否则取最近的别名），其余保留为兼容指针或显式 symlink 说明；
4. 记录相互冲突的指令与优先级决策。

GitHub + AGENTS 基线

五条默认操作原则：

1. 保持 CONTRIBUTING.md 可发现、可操作（放在 .github、根目录或 docs）；
2. Agent 指令要具体：真实命令、真实路径、清晰边界；
3. 用显式行为边界描述 Agent 权限：Always（总是做）、Ask first（先询问）、Never（永不）；
4. 贡献者与 Agent 规则必须与实际仓库工作流对齐；
5. 明确告知 Agent 何时、如何提 Issue 和 PR。

Canonical 与别名策略

这是该技能对“多 Agent 工具生态”的关键设计：

1. AGENTS.md 存在时即为规范源；
2. 不存在时，最近的别名文件为规范源；
3. 保持兼容表面显式存在：AGENTS.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/；
4. 使用别名时，必须文档化别名如何映射回规范策略（支持时用 symlink）；
5. 当仓库以 .agents/ 作为规范规则存储时，保持 .cursor -> .agents 兼容 symlink 以支持 Cursor 规则自动加载；
6. 策略保持 DRY：只存一份共享策略核心，通过别名/symlink 暴露，而不是复制规则文本。

按 Agent 平台的上下文感知

不同 Agent 平台的“上下文消费方式”不同，指令文件写法要随之调整：

• 对 Cursor / Claude 风格的 glob 消费者：规则文件要窄、有界；避免过度引用大范围路径集合（会膨胀 glob 型 Agent 的上下文）；
• 对 Codex 风格工作流：优先显式文件引用与确定性命令；
• 长 runbook 不要塞进顶层策略文件，链接到作用域明确的文档；
• 保证所有 Agent 都有 happy path——Codex、Claude 及其他编码 Agent 都能正常工作。

Symlink 与兼容操作（推荐布局与校验）

推荐的多人/多 Agent 兼容布局：

• 规范规则目录：.agents/
• Cursor 兼容路径：.cursor -> .agents symlink
• 规范策略文档：AGENTS.md，在相关处指向 .agents 路径

变更定稿前必须校验 symlink 状态，规则如下：

现状	动作
.agents/ 存在、.cursor 缺失	创建 .cursor -> .agents symlink
.cursor 是指向其他目标的 symlink	修正目标，或文档化为何必须不同
.cursor 是真实目录/文件	视为迁移冲突，替换前先询问

规则载荷通过规范目录验证：规则放 .agents/rules/*.mdc（带有效 frontmatter：description、globs、按需 allApply/alwaysApply）；命令路由放 .agents/commands/*.md；MCP 配置放 .agents/mcp.json。同时保持 Codex 行为显式：AGENTS.md 是 Codex 仓库指令的主文件，.cursor 兼容只服务于 Cursor 自动加载，不取代规范 AGENTS 策略。所有已应用的 symlink 修复与未解决的兼容缺口都要记入验证备注。

双模式与交付物标准、主动问题发现

“双模式”（dual-mode）指同一份策略核心要同时服务两种 Agent 消费风格：

1. 为所有 Agent 编写一份共享策略核心（相同命令、边界、优先级）；
2. 对 Cursor/Claude 风格 Agent，通过 glob 驱动、有界的文件暴露该核心（小而精的 AGENTS.md/规则面）；
3. 对 Codex，通过精确作用域的显式文件引用暴露同一核心；
4. 风格分叉时，取满足两者的最小公共结构，避免复制策略文本；
5. 在任务范围内把 AGENTS/CONTRIBUTING 视为一等交付物；
6. 保留既有文件的必要结构、约束与示例，措辞和命令与仓库现行指令对齐。

主动问题发现方面，技能把以下问题列为高优先级缺陷：被引用文件缺失、不存在的 setup 命令、命令作用域不匹配（例如模块级命令被写在根级）、分支/提交策略冲突。定稿前必须做一次跨 AGENTS/别名/CONTRIBUTING 及相关命令/规则文档的“冲突矩阵评审”。另外两条实用规则值得注意：

• 若缺失被依赖的规范入口文件（如某目录文档依赖的 README.md），应创建一个最小的可操作文件并更新引用，而不是只留警告；
• 从源码结构看，Agent 偏好简单的终端命令——“有定义良好的 make * 或 npm run * 最理想”，提供 shell completion 也能帮助 Agent 发现命令。

CONTRIBUTING 的规模与范围控制

1. 根 CONTRIBUTING.md 聚焦 setup、Issue 流程、PR 流程、测试、评审门槛；
2. 用 Issue/PR 模板链接代替内嵌全部流程细节；
3. 文件过大时按域拆分并从根文件链接；
4. 大内容移入文档站（如 Mintlify/Fern/Sphinx 工作流）；
5. 同时为 Agent/机器可读性优化。

规则文档还列出了一组“值得效仿的示例仓库”（OpenClaw、OpenAI Codex、p5.js、Vercel/agentsmd 规范、Rails/Kubernetes/Atom/GitHub Docs/React），用于不同项目规模下 AGENTS/CONTRIBUTING 的写作参照。

构建手册：build.md 的 13 步执行流

build.md 是 build 任务的执行手册，要求先读 principles.md 再按序执行。其步骤可归纳为：

1. 对齐 Agent 指令与治理指令：以 agent-and-contributing.md 为准；应用 symlink 兼容策略；写之前捕获既有约束（嵌套 Agent 规则、命令/测试要求、PR 工作流、风格检查）；提案中的代码片段必须使用与仓库相同的命令和验证预期。
2. 盘点产品文档表面（不止治理面）：仓库级构建必须覆盖 README*.md、docs/**、**/*.md/.mdx/.mdc/.rst/.rsc、Fern/Mintlify 配置、Sphinx conf.py；先建覆盖地图再动笔；范围模糊时先做更宽的发现，再有意收窄。
3. 框架配置与路径映射规则：先探测框架/配置；所有路径引用相对声明它的文件/配置解析，而非假设仓库根；文件系统路径与发布 URL 路由是两张独立的映射表，不能互相推断；双层验证（config → 磁盘文件存在；config/nav/routing → URL 路径一致可达）；把路径假设与不匹配记入交接（missing file / stale route / wrong base path）。
4. 定义意图与成功：受众、前提、job-to-be-done、读者完成后的直接结果、文档类型（tutorial/how-to/reference/explanation）、发布后必须为真的成功标准。
5. 先建结构再写正文：漏斗式（what/why → quickstart → next steps）；标题信息量充足、可扫读；每节以结论句开场；决策点给出具体分支指引；OpenClaw 文档必须先选定页面类型（见 OpenClaw 覆盖层一节）；任务关键配置内联，穷尽的默认值/枚举/schema/生成式参考/罕见调试流程则链接出去。
6. 有意构建 AGENTS.md 与 CONTRIBUTING.md：AGENTS.md 遵循 agents.md 生态模式——按仓库风格带 YAML frontmatter（name、description）、声明 persona 作用域与 Always/Ask first/Never 边界、包含具体命令与代表性代码示例；CONTRIBUTING.md 优先 Issue 分诊流、PR 预期、setup/测试命令、评审门槛；缺 Code of Conduct、Testing、Local checks、PR expectations 等必需节时补上；CONTRIBUTING 过大时按作用域拆分为链接文档，根文件保持简洁入口；跨文件链接（CONTRIBUTING ↔ AGENTS）必须准确且非循环；多个 AGENTS.md 并存时文档化目录级作用域并避免冲突建议。
7. 保持 Agent 上下文紧凑：“一次编写，两次暴露”（Author once, expose twice）——一份共享策略核心，通过有界的 glob 友好文件服务 Cursor/Claude，通过显式路径引用服务 Codex；Cursor/Claude 风格避免宽泛引用，用小 glob 和“一个文件只服务一个关注点”的窄规则文件；AGENTS 与别名文件保持短到中等长度，详细 runbook 移到链接文档；不为未来工具读取引入无关的历史/流程细节（防止 token/上下文漂移）。
8. 棕地构建模式：匹配现有术语、导航、组件模式；无文档化迁移计划时保留既有 IA；重写必须附旧→新路径迁移说明；优先“最小的安全变更集”。
9. 常青构建模式：偏好稳定概念而非绑定版本的叙述；易变细节隔离在明确标注的版本节下；包含维护信号（owner、刷新触发、stale 判定标准）与生命周期说明（废弃与替代路径）。
10. 写作约束：精确语言、短祈使句；代码示例可复制、自包含；包含常见失败模式与安全默认值；不写无法执行的占位指导。
11. Agent 与自动化就绪：关键事实留在文本里（不要只放在图片中）；选择重要时优先结构化列表/表格；提供允许确定性导航的链接与锚点；文档化哪些内容可在 CI 中自动检查。
12. 构建验证：尽可能验证命令与片段；验证变更部分的链接与引用；对引入的每个路径/命令做“引用存在性扫查”；范围内时验证文档框架一致性（Sphinx/Fern 配置与被引用文档路径）；OpenClaw 文档应用 openclaw.md 的验证清单。
13. 多语言 parity 模式：选定唯一事实源语言；定义 parity 目标（完全/分阶段/有意分叉）；跨 locale 保持结构对齐（标题、锚点、节序）；命令/代码正确性第一，解释性文本本地化第二；parity 不可行时加可见备注（缺失范围与预期同步窗口）；对变更部分跑 locale parity 检查。

评审手册：review.md 的 12 步清单

review.md 是 review 任务的清单，同样要求先读 principles.md。其十二个阶段及要点：

1. 范围与分类：确认文档类型与受众、棕地/常青意图、读者预期结果；全仓库评审必须显式包含治理面与产品文档面（docs/、README 树、.md/.mdx/.mdc、.rst/.rsc、框架文档配置）；OpenClaw 评审应用 openclaw.md。
2. 调查行为：主动找问题、不等反复提示；发现深层问题信号就继续第二遍调查；长时调查被允许；发现不了问题时要明确陈述并指出残余风险或验证缺口；默认 apply-fixes（除非用户要求 report-only）；任务覆盖文档面时不要止步于 AGENTS/CONTRIBUTING 检查。
3. 治理面评审：AGENTS.md 检查 persona 意图/作用域/命令与工具边界是否显式、frontmatter 风格、Always/Ask first/Never 边界、具体命令与仓库路径；CONTRIBUTING.md 检查 Issue/PR 工作流完整可操作、本地 setup/lint/测试命令准确、与嵌套 AGENTS 不冲突、超大文件拆分建议；Agent 平台感知检查——Cursor/Claude glob 行为下引用是否最小且有界、Codex 侧是否用显式文件引用、两个表面是否表达同一共享策略核心而非分叉指导；审计 .agents/.cursor 兼容行为（规范规则目录与 symlink 状态是否匹配仓库策略、symlink 目标完整性、AGENTS 策略在 .cursor 兼容存在时仍为 Codex 规范）；检查策略文本重复导致的上下文膨胀、规则/技能/Agent 指令间的冲突、Agent 指令与代码库不一致、引用文件缺失、setup/命令漂移。
4. 产品文档面评审：README 树与 docs/** 的 IA 覆盖；框架原生文档源（Fern/Mintlify/Sphinx/MkDocs）与事实源文件一致；.md/.mdx/.mdc/.rst/.rsc 中的过期命令、缺失前提、断链；确认被引用文档路径与锚点存在；标记应拆分/合并以提升可发现性与可维护性的文档；OpenClaw 文档检查 docs/docs.json、docs-list 路由提示、主路径与 Reference 放置、生成式参考的可见性；OpenClaw 重写/分页要求对重要声明、警告、示例、命令、字段、排障事实做源码支撑的 keep/drop/move/destination 覆盖。
5. 框架配置与路径映射检查：先探测并读框架配置；相对声明文件解析路径；文件系统路径与 URL 路由分开验证；显式标记路径映射漂移（missing file/stale route/wrong base path）。
6. 结构评审：漏斗检查（what/why、quickstart、next steps）；标题流与导航可发现性；标记被困在图片或深埋章节中的关键内容；Diataxis 对齐、拆分混合目的章节；OpenClaw 文档须匹配 openclaw.md 中的显式页面类型。
7. 写作质量评审：段落简洁可扫读；删除歧义代词与未定义术语；示例可执行且作用域正确；语气指令化、技术性、不空泛。
8. 棕地评审模式：验证与既有文档 IA/惯例兼容；锚点、重定向、跨文档链接有效；标记入门与任务完成路径上的回归；术语变更是否被有意传播。
9. 常青评审模式：标记带日期戳或无版本作用域的脆弱措辞；确认所有权与刷新信号存在；建议在产品例行演化后仍成立；标记缺失的废弃/迁移指导。
10. 工具链与平台评审：平台适配不确定时读 tooling.md；检查内容是否有效使用平台原语；标记“技术上正确但在所选平台上难以扫读”的文档；只在能降低认知负荷时推荐平台特定改进。
11. 多语言 parity 评审：确认声明的事实源语言与 parity 策略；跨 locale 对比变更章节的步骤/顺序/警告漂移；标记缺失的前提、版本说明、限制与安全指导更新；仅在有显式理由且用户影响低时允许有意分叉；locale parity 部分达成时必须给出读者可见的状态备注。
12. 输出格式：按三级组织——1. 阻塞性问题（文件 + 必须修复项）；2. 非阻塞改进；3. 验证备注（已完成 vs 待办）。

OpenClaw 覆盖层：openclaw.md 页面类型与验证命令

openclaw.md 是叠加在通用技能之上的 OpenClaw 专属规则，仅用于 OpenClaw 文档工作。其核心内容：

读者模型

• 以读者要完成的任务开场；
• 先给一条推荐路径，再给备选；
• 主文档聚焦常见路径；密集契约与罕见调试细节移到链接的参考/排障页；
• 在读者可能犯错的确切位置解释生产风险；
• 链接概念、指南、参考、CLI 页、SDK 文档、测试与排障，让读者无需重读即可继续。

页面类型（Page Types）

写或评之前先选页面类型：Overview（路由到正确产品区/集成路径）、Quickstart（最少安全步骤到达可用结果）、Topic page（端到端解释一个重要实体/表面）、Guide（从前提到生产就绪走通一个工作流）、API/SDK/CLI reference（定义范围内每个对象、方法、命令、选项、响应、错误、枚举、默认值与版本规则）、Testing guide（沙箱 setup、fixtures、模拟失败、live 模式差异）、Troubleshooting guide（可观察症状 → 检查 → 原因 → 修复）、Governance file（保持 Agent/贡献者策略具体、有作用域、与当前仓库行为一致）。

Topic Page 与 Guide 的固定形状

Topic Page（重要实体页）八段结构：

1. 以实体/表面命名的标题；
2. 无标题开场：说明它是什么、拥有什么、不拥有什么；
3. Requirements——仅在 setup 需要账号、版本、权限、插件、操作系统或凭证时；
4. Quickstart：推荐路径 + 最小可靠验证；
5. Configuration：任务关键选项内联，穷尽细节链到参考文档；
6. 主要子主题按读者意图组织，不要用泛化的 "Subtopics" 标题；
7. Troubleshooting：可观察失败 + 具体检查项；
8. Related links。

Guide（工作流页）九段结构：

1. 标题命名结果而非实现细节；
2. 开场说明读者能完成什么；
3. Before you begin：账号、密钥、权限、版本、工具、假设；
4. Choose a path——仅当读者必须做选择时；
5. 动词开头标题的步骤、命令、预期输出与检查；
6. 用最小可靠证明测试工作流有效；
7. Production readiness：安全、重试、限制、可观测性、迁移、清理；
8. 排障放在导致失败的工作流旁边；
9. See also 链接到概念、参考、SDK 文档与相邻指南。

文档 IA 与导航

• 导航变更前先读 docs/docs.json；
• 主读者路径上放 topic 页与常见工作流；穷尽契约、生成式参考、维护者专属细节放 Reference 或其他明确作用域的支撑页；
• 生成式 plugins/reference/* 子页与重定向页不进可见导航（除非显式需要）；
• 页面迁移时交接必须包含 keep/drop/move/destination 矩阵；
• 参与文档索引的页面要加 “Read when” 路由提示。

源码支撑的内容与示例规范

• CLI 文档必须与当前 flags、输出、错误、示例一致；
• API/SDK 文档必须含字段、默认值、枚举、约束、可空行为、生命周期状态、错误与恢复指导；
• 配置文档必须与导出的类型、schema/help 输出、元数据、基线及当前文档对齐；
• 依赖支撑的行为（默认值、时序、错误、API 行为）在写入文档前必须从上游文档、源码或类型验证；
• 区分“当前行为、已发布行为、计划行为、维护者意图”。

示例规范：优先完整可复制粘贴的命令与片段；使用现实的变量名与值；占位符用尖括号命名（如 <API_KEY>）；有帮助时展示预期成功输出；一个代码块一个概念单元、用语言特定 fence；不隐藏 setup/鉴权/错误处理/清理的示例；永不暴露真实密钥、生产配置、电话号码、私有视频或凭证。

保留性评审（Preservation Reviews）

重写或拆分时：改写前识别源单元（标题、段落、表格、示例、CLI/API 契约、警告、排障事实）；把每个保留单元映射到目标页/节；对密集源材料不用笼统的 “covered” 行充数，要求行级或声明级证据；被删除内容要说明它是过时、别处重复、不支持还是移到了参考/支撑页；使用文档审计产物时，验证它是带非空 mappings[] 的映射审计数据，而非只是清单或重排 JSON。

验证命令（narrowest-proof 原则）

覆盖层规定“选择能覆盖被触碰表面的最窄证明”。SKILL.md 中列出的验证命令在 OpenClaw 仓库中均有真实对应的 npm script（见 package.json），可直接执行：

命令	实现	用途
pnpm docs:list	node scripts/docs-list.js	文档清单/导航结构检查
pnpm docs:check-mdx	node scripts/check-docs-mdx.mjs docs README.md	MDX 语法检查（覆盖 docs/ 与根 README）
pnpm docs:check-links	node scripts/docs-link-audit.mjs	文档链接审计（对应 scripts/docs-link-audit.mjs）
pnpm docs:check-i18n-glossary	node --import ./scripts/tsx.mjs scripts/check-docs-i18n-glossary.mts	多语言术语一致性
pnpm format:docs:check / pnpm lint:docs	scripts/format-docs.mts --check / markdownlint-cli2（配置 config/markdownlint-cli2.jsonc）	文档格式化与 Markdown lint
git diff --check	git 原生	空白/冲突标记类问题
生成文档/清单检查	仓库相应脚本	生成式参考、插件目录、labeler 或文档脚本变更时
行为测试或命令探测	行为测试/CLI probe	文档声称运行时行为时

覆盖层最后一条规则值得强调：如果验证被阻塞，必须精确说明哪个命令没跑、为什么——这保证交付物的验证备注是可复核的。

文档工具选型：tooling.md 检查点

tooling.md 在“平台/工具链选择影响建议”时启用，给出六个选型检查点：

• 既有栈锁定：不为微小收益强制迁移；
• API 工作流深度：生成式参考、OpenAPI 支持、可测试性；
• 协作模型：docs-as-code、评审工作流、版本化；
• 运行时质量：搜索、导航、可复制的代码片段；
• AI 就绪度：结构化内容、稳定 URL、机器友好布局且人类可读；
• 人类就绪度：阅读复杂度、阅读 UX、导航深度、最小化行话。

两种语境下的应用差异：棕地模式优先兼容当前平台、先用现有组件与风格惯例再引入新模式、仅当当前约束阻塞关键结果时提议迁移；常青模式偏好让例行更新低摩擦的平台与模板、标准化章节模板减少漂移、记录所有权/更新节奏/陈旧内容检测规则。评审含义：检查内容是否正确使用平台原语（tabs、callouts、endpoint blocks）；标记“技术正确但在所选平台上难扫读”的文档；只在降低认知负荷时推荐平台特定改进。

子 Agent 编排：四个专职角色的并行审计

当仓库很大或变更集很广时，SKILL.md 要求默认使用子 Agent 做仓库级、多框架或高冲突工作。该技能在 agents/ 目录下定义了四个子 Agent 的完整规格（每个文件都带 YAML frontmatter，声明 model、tools、permissionMode: default 与 maxTurns），模型分层体现了“便宜模型做广度扫描、强模型做深推理与合成”的成本设计：

inventory-agent（快速/haiku，maxTurns 6）

工具：Read/Glob/Grep/LS。目标：快速发现仓库文档表面。任务：映射 AGENTS.md/CONTRIBUTING.md/别名与文档表面（docs/**、README 层级、.md/.mdx/.mdc/.rst/.rsc）、列出发现的框架配置文件（Fern/Sphinx/Mintlify 或等价物）、只报硬失败（exact file paths）。返回：覆盖地图、缺失/损坏路径列表、未解决的阻塞项。定义见 inventory-agent.md。

governance-agent（思考型/sonnet，maxTurns 10）

工具：Read/Glob/Grep。目标：验证 AGENTS/CONTRIBUTING/别名的一致性与优先级，识别策略漂移与指令冲突。任务：确定规范指令源与别名兼容映射、检测嵌套作用域文件与工具特定规则消费者之间的冲突、按治理预期验证命令示例。返回：优先级模型（precedence model）、带严重度的冲突列表、推荐低风险修复。定义见 governance-agent.md。

docs-framework-agent（思考型/sonnet，maxTurns 10）

工具：Read/Glob/Grep。目标：验证框架配置驱动的文档行为，防止源文件与发布路由之间的路径映射漂移。任务：先探测并读框架配置（Fern/Sphinx/Mintlify/自定义）、相对声明文件解析路径、双表验证（config → 文件存在；config/nav/routing → URL 路径有效一致）。返回：审查过的配置文件、所做路径假设、不匹配项（missing file/stale route/wrong base path）。定义见 docs-framework-agent.md。

synthesis-agent（长上下文/opus，maxTurns 12）

工具仅 Read。目标：把子 Agent 输出合并成一份连贯、无重复的行动计划。任务：阻塞项优先、其次非阻塞改进；把治理决策归一化为一个优先级模型；删除重复建议与相互矛盾的修复；保持最终输出简洁且可执行。返回：优先级修复计划、验证摘要（done vs pending）、显式剩余缺口/阻塞项。定义见 synthesis-agent.md。

SKILL.md 中给出的编排骨架为：inventory-agent -> governance-agent / docs-framework-agent -> synthesis-agent，即广度盘点先行，治理面与框架面并行深查，最后由长上下文合成 Agent 归并。这与 principles.md 的执行策略（“Keep one merged outcome: sub-agent outputs must be normalized into a single consistent recommendation/fix set”）相呼应，避免多 Agent 审计产生多份互相矛盾的报告。

输入与输出契约

SKILL.md 用 Inputs/Outputs 两节把技能的行为边界写成显式契约。

Inputs（调用方应提供）：

• 文档类型（tutorial/how-to/reference/explanation）与受众；
• 文件范围或 diff 范围；
• 文档框架/工具链约束（Fern、Mintlify、Sphinx 等）；
• build/review 模式与 brownfield/evergreen 意图；
• 目标 Agent 与人类的兼容意图；
• 范围内的文档框架表面（Fern、Sphinx、Mintlify、Markdown/MDX/MDC/RST/RSC 文件）;
• 期望调查深度/时间预算（快速过一遍 vs 穷尽评审）；
• 执行模式（可用时为 single-agent 或 sub-agent-assisted）；
• 修复模式（默认 apply-fixes，用户要求时 report-only）；
• 多语言范围：事实源语言、目标 locale、parity 预期；
• 仓库特定覆盖层约束（如有）。

Outputs（交付物）：

• 更新后的草稿或评审发现（含清晰下一步）；
• 验证备注（检查了什么、还剩什么）；
• 面向长期质量的导航/维护建议；
• 触碰 AGENTS/CONTRIBUTING 时的治理文档对齐摘要；
• Agent 指令表面地图（主文件、别名文件、Codex/Claude/Cursor 处理计划）；
• 文档表面覆盖地图（/docs、README 层级、框架源树的评审范围）;
• 自动检测问题列表 + 已应用修复（或显式的 report-only 发现）；
• 使用子 Agent 时的委托备注（委托了哪些范围、发现如何合并）;
• 多语言 parity 备注（已同步 / 部分并附理由 / 有意分叉）；
• 使用仓库覆盖层时的覆盖层备注。

小结：该技能的工程价值

OpenClaw 的这个 technical-documentation 技能把“写文档”从个人手艺变成了一个可审计的工程流程：入口是 SKILL.md 的 15 步工作流；规则分层为通用原则（principles.md）、治理规则（agent-and-contributing.md）、构建/评审手册（build.md / review.md）、工具选型（tooling.md）与仓库覆盖层（openclaw.md）；执行上支持四个专职子 Agent 的成本分层编排；验证上落到 OpenClaw 仓库中真实可运行的 pnpm docs:* / pnpm lint:docs 命令（脚本位于 scripts/ 目录，如 scripts/docs-link-audit.mjs、scripts/check-docs-mdx.mjs）。对希望在多 Agent 编码工具（Codex/Claude/Cursor）时代维护文档一致性的团队，这套“canonical + alias + 双模式暴露 + 子 Agent 审计 + 最窄验证”的完整闭环可以直接作为方法论蓝本参考。