企业官网建设流程全解析

• 后端
• 前端
• AI 技能
• AI 插件
• 搜索引擎

本文是 ClawHub 开源仓库中.agents/skills/technical-documentation/SKILL.md及其完整参考资料体系的深度解读，覆盖从文档构建、审查到治理文件（AGENTS/CONTRIBUTING）规范化的完整方法论。读者将掌握 build/review 双模式工作流、brownfield/evergreen 语境判断、Matt Palmer 八原则与 OpenAI 质量约束的实际应用，并了解如何通过 inventory/governance/docs-framework/synthesis 四个子代理实现仓库级文档审计的并行化交付。

技能定位：为什么仓库需要一个专职的文档技能

ClawHub 是 OpenClaw 生态的 Skill 与 Plugin 注册中心，其仓库同时承载三种文档面：面向用户的docs/、面向贡献者的CONTRIBUTING.md、以及面向 AI 编码代理的AGENTS.md/CLAUDE.md等指令文件。这些文档的读者不再只有人类，还有各类编码代理（Codex、Claude、Cursor）。technical-documentation技能（.agents/skills/technical-documentation/SKILL.md）正是为这种"文档即代码、人机共读"的诉求而生。

技能声明的核心目的（Purpose）很直接：产出并审查清晰、可执行、可维护的技术文档，同时覆盖人类读者与 Agent 读者，包括贡献者治理文件与代理指令文件。

何时启用该技能

SKILL.md 列出了 15 类适用场景，可以归纳为四个族群：

• 既有代码库的文档新建或重构（brownfield）：在不破坏现有信息架构（IA）的前提下改造文档。
• 常青文档（evergreen）：编写跨版本保持准确、可长期复用的文档，而非绑定某一发布版本。
• 文档差异审查：针对文档 diff 检查结构、清晰度与操作正确性，并支持全仓库文档审计——审计范围必须同时包含治理文件与产品文档面（docs/、README*、.md/.mdx/.mdc，以及 Fern/Sphinx/Mintlify 风格的框架源）。
• 代理指令与贡献规范的治理：更新或审查AGENTS.md/CONTRIBUTING.md，保持代理工作流与贡献者工作流同仓库实际实践对齐；设计多别名指令文件的治理策略（CLAUDE.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/），以AGENTS.md为规范源，其余作为兼容层；诊断代理文件漂移（agent-file drift），如团队反复提示缺失文件、失效命令或策略冲突。

双模式工作流：build 与 review 的分类执行

SKILL.md 的核心工作流共 15 步，逻辑上是"先分类、再清点、后执行、终交付"的闭环：

1. 分类任务：判定build（构建）或review（审查）；判定语境brownfield（既有库改造）或evergreen（常青）。
2. 早期全面清点文档范围：治理文件（AGENTS/CONTRIBUTING/别名）+ 产品文档（docs 目录、框架源、根/模块 README）都要列入。
3. 检测多语言范围（README/文档多语言时），定义所需的一致性等级。
4. 读取references/agent-and-contributing.md，获取代理指令与 CONTRIBUTING 工作流规则（清点、canonical/alias 映射、双模式平衡、交付标准、优先级/冲突处理）。
5. 读取references/principles.md，掌握治理规则集（Matt Palmer 与 OpenAI）。
6. OpenClaw 文档工作前先读references/openclaw.md，再进入 build/review playbook。
7. build 任务遵循references/build.md；8. review 任务遵循references/review.md，并主动发现问题，无需等待重复提示。
8. 复杂或高风险任务（build 或 review）允许进行更长、更深、更彻底的调查以建立信心。
9. 可用时使用子代理做有边界的并行发现/审查，再把输出合并成一份连贯的最终交付物。
10. 平台/工具选择影响建议时，使用references/tooling.md。
11. 对治理面与文档内容面都做主动问题扫描，默认在同一轮中修复高置信缺陷（除非明确要求 report-only 模式）。
12. brownfield 模式优先兼容现有文档 IA、工具链与发布状态。
13. evergreen 模式优先永恒措辞、更新策略与持久结构。
14. 交付物附带验证说明、一致性状态与剩余缺口。

输入与输出契约

技能执行需要明确的输入约定（Inputs）：文档类型（教程/操作指南/参考资料/解释说明）与受众、文件范围或 diff 范围、文档框架约束（Fern/Mintlify/Sphinx 等）、build/review 模式与 brownfield/evergreen 意图、目标代理与人类兼容意图、调查深度/时间预算（快速通过 vs 详尽审查）、执行模式（单代理或子代理辅助）、修复模式（默认 apply-fixes 或 report-only）、多语言范围（源语言、目标区域、一致性期望）、仓库特定覆盖约束。

对应地，Outputs 要求产出：更新草稿或带明确下一步的审查发现、验证说明（检查了什么、还剩什么）、长期质量导航/维护建议、触及 AGENTS/CONTRIBUTING 时的治理文档对齐摘要、代理指令面地图（主文件、别名文件、Codex/Claude/Cursor 处理计划）、文档面覆盖地图（/docs下审查了什么、README 层级、框架源树）、自动检测的问题清单及已应用修复（或显式 report-only 发现）、使用子代理时的委派记录（委派范围与发现如何合并）、多语言一致性说明（同步/部分同步且给出理由/有意分歧）、仓库特定覆盖说明。

贯穿全局的文档原则：Matt Palmer 八规则与 OpenAI 约束

references/principles.md定义了技能的默认操作原则。

Matt Palmer 的八条规则

1. 为人写作，为代理优化（Write for humans, optimize for agents）。
2. 从漏斗开始：什么/为什么 → 快速上手 → 下一步。
3. 用 Diataxis 框架搭建内容（教程/操作指南/参考/解释四种形态）。
4. 与 AI 协作写作，但为代理结构化。
5. 将例行的文档操作下放给后台代理。
6. 用 CI 自动化质量检查。
7. 自动化脚手架与重复性工作流任务。
8. 让贡献变得容易且可见。

OpenAI 文档质量约束

• 优先使用具体、准确的术语，避免小众黑话。
• 示例保持自包含，最小化依赖。
• 优先高价值主题，而非边缘细节的深度。
• 不教授不安全模式（例如暴露密钥）。
• 开头提供语境，帮助读者快速定位。
• 保持同理心，在明显改善结果时可覆盖僵硬规则。

冲突时的合并策略

四条规则的优先级从高到低：先保住读者任务成功 → 再保结构清晰 → 再保长期可维护性 → 最后在"不降低人类清晰度"的前提下加入代理优化。对于代理指令与贡献者治理细节，以references/agent-and-contributing.md为补充真理源；当目标仓库与 OpenClaw 相关时，在通用规则之上叠加references/openclaw.md。

多语言一致性规则

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

治理文档：AGENTS 与 CONTRIBUTING 的规范化

references/agent-and-contributing.md是治理文件的详细真理源，ClawHub 仓库本身就是这套策略的活样本——根目录同时存在 AGENTS.md（canonical）与 CLAUDE.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'发现仓库级与嵌套级指令文件。
• 编辑前先读根级与最近作用域的AGENTS.md/CONTRIBUTING.md对。
• 若存在别名文件，归一化到单一 canonical 源（AGENTS.md优先；缺失时取最近别名），并保留兼容指针或显式符号链接说明。
• 记录冲突指令与优先级决策。

Canonical 与别名策略

1. AGENTS.md存在时作为 canonical；2. 缺失时取最近别名文件；3. 兼容面要显式化：AGENTS.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/；4. 别名需记录如何映射回 canonical 策略（或支持时用符号链接）；5. 当仓库以.agents/作为 canonical 规则存储时，保持.cursor作为指向.agents的兼容符号链接以便 Cursor 自动加载；6. 保持策略 DRY：单一共享策略核心，通过别名/符号链接暴露，而非复制规则文本。

ClawHub 的实际做法验证了"作者一次、多处暴露"：仓库将全部技能与规则集中在 .agents/ 目录（本技能即其中一员），根级 AGENTS.md 承载命令地图与编码规范，CLAUDE.md 与之一致，避免双文件漂移。

平台感知与上下文控制

• Cursor 与 Claude 风格（glob 消费型）代理：规则文件要窄而有界，避免过度引用大路径集导致上下文膨胀。
• Codex 风格工作流：偏好显式文件引用与确定性命令。
• 长 runbook 不要放进顶层策略文件，应链接到作用域文档。
• 无论 Codex、Claude 还是其他编码代理，都要保证存在一条 happy path。

推荐的兼容布局为：canonical 规则目录.agents/；Cursor 兼容路径.cursor -> .agents符号链接；canonical 策略文档AGENTS.md指向相关.agents路径。交付前验证符号链接状态：.agents/存在而.cursor缺失时创建链接；.cursor指向错误目标时修复或记录原因；.cursor是真实目录/文件时视为迁移冲突，先询问再替换。同时通过 canonical 目录验证规则载荷：.agents/rules/*.mdc（frontmatter 含description、globs、alwaysApply）、.agents/commands/*.md、.agents/mcp.json。注意.cursor兼容仅服务于 Cursor 自动加载，不替代 canonical 的 AGENTS 策略。

双模式交付标准与主动问题修复

双模式要求"一个共享策略核心、两种暴露方式"：对 Cursor/Claude 用 glob 驱动的有界小文件，对 Codex 用精确作用域的显式文件引用；风格分歧时取两者都能满足的最小公共结构，不复制策略文本。AGENTS/CONTRIBUTING 在作用域内时视为一等交付物，保留现有文件的结构、约束与示例。

主动发现与修复原则：定稿前对 AGENTS/别名/CONTRIBUTING 及相关命令/规则文档运行冲突矩阵审查；高优先级缺陷包括缺失的引用文件、不存在的安装命令、命令作用域不匹配、分支/提交策略冲突；对低风险修复不要只停在提示层面，应同一轮直接修复；若 canonical 入口文件缺失（如文档依赖的目录 README.md），创建最小可执行文件并更新引用。

CONTRIBUTING 大小与范围控制

根级CONTRIBUTING.md聚焦于：环境搭建、issue 流程、PR 流程、测试与审查门禁；用 issue/PR 模板链接替代内联全部流程细节；文件过大时按领域拆分并从根文件链接；大块内容移入 docs（Mintlify/Fern/Sphinx 工作流），避免贡献者指南臃肿；同时为人类与机器可读性优化。

构建 Playbook：结构先于文笔

references/build.md定义了 build 任务的 13 步执行流，其核心思想是"先把结构立起来，再填充文笔"。

1. 对齐代理指令与治理指令：以agent-and-contributing.md为真理源；作用域内应用符号链接兼容策略；先捕获约束（嵌套代理规则、命令/测试要求、PR 工作流、风格检查），并在示例中使用与仓库一致的命令与验证期望。
2. 清点产品文档面：不只治理文件，还包括README*.md、docs/**、**/*.md、**/*.mdx、**/*.mdc、**/*.rst、**/*.rsc及框架配置；起草前先建覆盖地图；作用域模糊时先扩大发现再有意收窄。
3. 框架配置与路径映射规则：先检测框架/配置（Fern config、Sphinxconf.py、Mintlify config 或等价物）；每个引用路径相对"声明它的文件/配置"解析，而非假设仓库根；文件系统路径与发布 URL 路由是两个独立映射，无配置证据不可互相推断；两层都验证：配置 → 文件存在于磁盘、配置/导航/路由 → URL 路径有效可达。
4. 定义意图与成功标准：受众、前置条件、要完成的工作、读者读完的预期结果、文档类型（教程/操作指南/参考/解释）、发布后必须成立的成功标准。
5. 先建结构再写散文：遵循漏斗（什么/为什么 → 快速上手 → 下一步）；标题信息量大且可扫描；每节以要点句开头；决策点给出具体分支指引。
6. 刻意构建 AGENTS.md 与 CONTRIBUTING.md：AGENTS.md 遵循 agents.md 生态模式——仓库风格要求时含 YAML frontmatter（name、description）、声明角色范围与显式边界（Always、Ask first、Never）、给出具体命令与代表性代码示例。CONTRIBUTING.md 优先 issue 分诊流程、PR 期望、搭建/测试命令与审查门禁，必要时补充 Code of Conduct、Testing、Local checks、PR expectations 章节；过大则按作用域拆分并保持链接准确、非循环。
7. 保持代理上下文紧凑：作者一次、暴露两次；Cursor/Claude 用有界 glob 文件，Codex 用显式路径引用；避免无关历史与流程细节造成的 token/上下文漂移。
8. brownfield 构建模式：匹配现有术语、导航与组件模式；无文档化迁移计划时保留现有 IA；重写时附旧路径到新路径的迁移说明；优先最小安全改动集。
9. evergreen 构建模式：稳定概念优先于绑定发布的叙事；易变细节隔离到明确标注的版本章节；包含维护信号（负责人、刷新触发、过期标准）与生命周期说明（弃用与替代路径）。
10. 写作约束：精确语言、短祈使句；代码示例可复制、自包含；包含常见失败模式与安全默认值；避免无法执行的占位指导。
11. 代理与自动化就绪：关键事实放文本而非图片；选择点用结构化列表/表格；链接与锚点支持确定性导航；文档化 CI 中可自动检查的内容。
12. 构建验证：尽量验证命令与片段；检查改动章节的链接与引用；对引入的每个路径/命令做引用存在性扫描；作用域内含框架一致性检查。
13. 多语言一致性模式（适用时）：选单一源语言保证技术准确与发布时序；定义一致性目标（完全/分阶段/按章节有意分歧）；可能时保持跨区域结构对齐（标题、锚点、章节顺序）；命令/代码正确性优先，说明性文字其次；无法达成时加可见说明并记录未解析检查。

审查 Playbook：系统化检查清单

references/review.md提供 12 个部分的审查清单，先读principles.md再应用：

1. 作用域与分类：识别文档类型与受众；确认 brownfield/evergreen 意图与读者预期结果；全仓库审查必须同时含治理面与产品文档面。
2. 调查行为：主动发现问题，不等待重复提示；有深层问题信号时继续深挖；可用子代理做有界并行发现后合并为单一问题集；无问题时显式说明并指出残余风险/验证缺口；默认 apply-fixes，除非用户要求 report-only；任务覆盖面广时不要停在 AGENTS/CONTRIBUTING，继续检查文档内容与框架面。
3. 治理面审查：AGENTS.md 确认角色意图、作用域与命令/工具边界显式；frontmatter 风格匹配仓库惯例；必要时有Always/Ask first/Never边界；命令示例具体且路径仓库相关。CONTRIBUTING.md 验证 issue/PR 工作流完整可执行、本地搭建/lint/test 命令与审查标准准确、不与嵌套 AGENTS 冲突、过大的文件应拆分为链接章节。平台感知方面确认 Cursor/Claude 引用最小化且有界、Codex 指引用显式文件引用、两个面代表同一共享策略核心、.agents/.cursor兼容行为与仓库策略一致、无跨文件策略复制造成的上下文膨胀、无冲突规则/技能/代理指令、代理指令与代码库无冲突信息、无缺失/损坏的引用文件、无搭建/命令漂移。
4. 产品文档面审查：验证根/模块README*与docs/**树的 IA 覆盖；审查框架原生文档源（Fern/Mintlify/Sphinx/MkDocs）且指引匹配真实源文件；检查.md/.mdx/.mdc/.rst/.rsc的过期命令、缺失前置条件与断裂交叉链接；确认引用的文档路径与锚点存在；标记应拆分/合并的文档。
5. 框架配置与路径映射检查：先读框架配置（Fern config、Sphinxconf.py、Mintlify config 等）；路径相对声明文件解析；文件系统路径与发布 URL 路由是两张独立映射，都验证；显式标记路径映射漂移（missing file / stale route / wrong base path）。
6. 结构审查：漏斗检查（什么/为什么、快速上手、下一步）；标题流与导航可发现性；关键内容被困在图片或埋藏章节中的问题；Diataxis 对齐与混合用途章节拆分。
7. 写作质量审查：段落简洁可扫读；删除模糊代词与未定义术语；示例可执行且作用域正确；语气指示性、技术性、不含糊。
8. brownfield 审查模式：兼容现有 IA 与惯例；锚点、重定向与跨文档链接保持有效；标记入参与任务完成路径的回归；术语变化有意传播。
9. evergreen 审查模式：标记无版本范围的日期戳或脆弱措辞；检查所有权与刷新信号；确认建议在常规产品演进后仍有效；标记缺失的弃用/迁移指引。
10. 工具与平台审查：检查内容是否有效使用平台原语；标记与文档平台对抗的结构；仅在降低认知负荷时推荐平台针对性改进。
11. 多语言一致性审查（适用时）：确认声明的源语言与一致性策略；对比跨区域改动章节的步骤/顺序/警告漂移；标记前置条件、版本说明、限制与安全指引的缺失更新；仅当理由显式且用户影响低时允许有意分歧；部分一致时要求读者可见的状态说明。
12. 输出格式：分三块——阻断性问题（文件 + 必需修复）、非阻断改进、验证说明（已完成 vs 待办）。

子代理编排：四个角色的并行分工

SKILL.md 的子代理编排建议：仓库大或改动面广时优先用子代理，仓库级、多框架或高冲突工作默认使用。四个代理各有明确分工，且已按模型强度分配任务（定义见 .agents/skills/technical-documentation/agents/ 目录）：

编排要求：只保留一个合并结果——子代理输出必须归一化为单一一致的推荐/修复集。synthesis-agent 的任务包括：阻断项优先于非阻断改进、为治理决策归一化为单一优先级模型、去重冗余推荐与矛盾修复、保持最终输出简洁且可执行。配套的 openai.yaml 声明了技能元数据（display_name、icon、brand_color、default_prompt）并设置allow_implicit_invocation: true，允许隐式调用。

工具与平台决策：brownfield 兼容优先

references/tooling.md提供了文档平台选择检查点：现有栈锁定（不为小收益强制迁移）、API 工作流深度（生成引用、OpenAPI 支持、可测试性）、协作模型（docs-as-code、审查工作流、版本化）、运行时质量（搜索、导航、可复制代码片段）、AI 就绪度（结构化内容、稳定 URL、机器友好布局但人类可读）、人类就绪度（阅读复杂度、阅读 UX、导航深度、黑话最小化）。

• brownfield 模式：优先兼容当前平台；先使用现有组件与风格惯例，再引入新模式；仅在当前约束阻碍关键结果时才提议迁移。
• evergreen 模式：偏好使常规更新低摩擦的平台与模板；标准化章节模板减少漂移；捕获所有权、更新节奏与过期内容检测规则。
• 审查影响：检查内容是否正确使用平台原语（tabs、callouts、endpoint blocks）；标记技术上正确但难扫读的文档；仅在降低认知负荷时推荐平台针对性改进。

OpenClaw 覆盖层：面向 OpenClaw 文档的专属规则

当目标文档属于 OpenClaw 生态（ClawHub 正是其一）时，references/openclaw.md在通用规则之上叠加专属层：

• 读者模型：以读者要完成的任务开头；给一条推荐路径再给备选；主文档聚焦常规路径，密集契约与罕见调试细节移入链接的参考/排障页；在读者可能犯错的确切位置解释生产风险；链接概念、指南、参考、CLI 页、SDK 文档、测试与排障，让读者无需重读即可继续。
• 页面类型：Overview（路由到正确产品区/集成路径）、Quickstart（最少安全步骤到达可用结果）、Topic page（端到端解释主要实体或面）、Guide（从前置条件到生产就绪的单一工作流）、API/SDK/CLI reference（定义每个对象/方法/命令/选项/响应/错误/枚举/默认值/版本规则）、Testing guide（沙箱搭建、fixtures、模拟失败、live 模式差异）、Troubleshooting guide（症状映射到检查/原因/修复）、Governance file（策略具体、有界、与当前仓库行为对齐）。
• Topic page 结构：标题命名实体或面 → 无标题开场说明它是什么、拥有什么、不拥有什么 → 仅当需要账号/版本/权限/插件/OS/凭证时的 Requirements → 推荐路径与最小可靠验证的 Quickstart → 任务关键配置内联、详尽细节链接到参考 → 按读者意图组织的主要子主题 → 带可观察失败与具体检查的 Troubleshooting → Related links。
• Guide 结构：标题命名结果而非实现细节 → 开场说明读者能完成什么 → Before you begin（账号、密钥、权限、版本、工具、假设）→ Choose a path（仅当必须决策时）→ 动词引导标题的步骤、命令、预期输出与检查 → 用最小可靠证据测试工作流 → 生产就绪（安全、重试、限制、可观测性、迁移、清理）→ 靠近故障源头的排障 → See also。
• 文档 IA 与导航：导航改动前先读docs/docs.json；主题页与常规工作流放主路径；详尽契约、生成引用、维护者专属细节放 Reference 或明确作用域的支持页；移动页面时在手记中包含 keep/drop/move/destination 矩阵；参与 docs 索引的页面增加 "Read when" 提示。
• 源码背书：CLI 文档必须匹配当前 flags/输出/错误/示例；API/SDK 文档必须含字段、默认值、枚举值、约束、可空行为、生命周期状态、错误与恢复指引；配置文档必须对齐导出类型、schema/help 输出、元数据、基线与当前文档；依赖背书的行为必须从上游文档/源码/类型验证后再写默认值、时序、错误或 API 行为；区分当前行为、已发布行为、计划行为与维护者意图。
• 示例规范：完整可复制的命令与片段；真实变量名与值；占位符用尖括号（如<API_KEY>）；有助于验证时展示预期成功输出；每代码块一个概念单元并使用语言特定围栏；避免隐藏搭建、认证、错误处理或清理的示例；永不暴露真实密钥、活配置、电话号码、私有视频或凭证。
• 保留审查：重写或拆分前识别源单元（标题、段落、表格、示例、CLI/API 契约、警告、排障事实）；将每个保留单元映射到目标页面/章节；密集源材料不允许用宽泛 "covered" 行代替，用行级/声明级证据；被丢弃内容需说明是过时、他处重复、不受支持还是移入参考/支持页。
• 验证命令：选择覆盖所触面的最窄证明：pnpm docs:list、pnpm docs:check-mdx、pnpm docs:check-links、pnpm docs:check-i18n-glossary、pnpm format:docs:check/pnpm lint:docs、git diff --check、生成文档或清单检查、行为测试或命令探针；证明被阻断时，说明哪个命令未运行及原因。

在 ClawHub 仓库中的落地实践

本技能并非纸上谈兵，ClawHub 仓库本身就是其方法论的全量实例，可直接对照学习。

治理面：AGENTS.md 为规范源，CLAUDE.md 为兼容别名

根级 AGENTS.md 是仓库的 canonical 代理指令，包含：项目结构地图（src/TanStack Start 前端、convex/Convex 后端、convex/_generated/生成代码、docs/可发布文档、specs/产品规范、public/静态资源）、Durable Intent 规则（安全敏感流程的行为意图写入specs/，用户/运营面向的内容写docs/）、完整命令地图（bun run dev、bunx convex dev --typecheck=disable、bunx convex codegen、bun run seed:dev、bun run ci:static、bun run ci:unit、bun run ci:types-build等 CI 门禁）、编码风格（TypeScript strict、ESM、2 空格单引号、Biome + oxlint、函数命名 verb-first）、测试规范（Vitest 4 + jsdom、80% 覆盖率门槛、测试位于src/**与convex/lib/**）。CLAUDE.md 与 AGENTS.md 内容一致，充当 Claude Code 的兼容入口——这正是"单一策略核心、别名暴露"的实践样板。

文档面：docs/ 与 specs/ 的职责切分

docs/README.md 明确定义了分工：docs/是可发布到docs.openclaw.ai的 ClawHub 标签页的用户面向源，包含产品、CLI、发布者、API、策略、安全与排障文档；而specs/承载仓库搭建、生产部署 runbook、实现计划、设计理由、回归说明与内部子系统意图——"告诉读者如何运行 ClawHub 项目本身的内容属于specs/，而非公开 OpenClaw 文档"。docs 索引给出了阅读顺序：docs/clawhub.md总览 →docs/quickstart.md→docs/how-it-works.md→docs/publishing.md→docs/cli.md→docs/skill-format.md→docs/claws.md→docs/auth.md→docs/telemetry.md→docs/namespace-claims.md→docs/troubleshooting.md，另列策略/API/信任文档（docs/acceptable-usage.md、docs/api.md等）。这与 principles.md 的"漏斗结构"和 openclaw.md 的"主路径 + Reference"导航模型一一对应。

工具链：docs:list 与 docs:run

仓库将文档自动化做成真实脚本（对应"用 CI 自动化质量检查"原则）：package.json 中声明"docs:list": "bun scripts/docs-list.ts"与"docs:run": "bun scripts/docs-run.ts"。查看 scripts/docs-list.ts 源码可见其设计：支持DOCS_DIR环境变量覆盖文档目录、排除archive/research目录、基于process.cwd()或脚本相对位置解析默认docs/目录——这正是 build.md 中"路径相对声明文件解析"与"路径映射假设记录"的工程化实现。docs:run则支持通过环境变量（如OPENCLAW_REPO_PATH）把文档同步到 OpenClaw 仓库，对应文档构建的"发布/集成"环节。

总结

ClawHub 的technical-documentation技能将"写文档"从散漫的写作活动提升为可分类、可审计、可并行、可自动化的工程流程：用 build/review 双模式覆盖全生命周期，用 brownfield/evergreen 双语境平衡兼容与前瞻，用原则层（principles）、治理层（agent-and-contributing）、执行层（build/review playbook）、平台层（tooling/openclaw overlay）四层参考体系支撑决策，再用四个子代理实现大规模仓库审计的并行化。对于任何希望让文档同时被人类与 AI 代理高效消费的仓库，这套体系都值得直接借鉴——ClawHub 仓库本身就是其最完整的参考实现。

• 后端
• 前端
• AI 技能
• AI 插件
• 搜索引擎