一、技能概述
该技能用于在现有产品/代码库中创建或大修文档（棕地模式），或构建旨在长期准确可复用的常青文档（常青模式）。它同时覆盖治理文件（AGENTS.md、CONTRIBUTING.md 及其别名）和产品文档表面（docs/、README、.md/.mdx/.mdc、Fern/Sphinx/Mintlify 风格源文件），并可执行全仓库文档审计。
核心定位：该技能是 OpenClaw 文档体系的通用基础层——它本身不绑定 OpenClaw 项目，而是一套可复用的文档工程方法论。当仓库存在 OpenClaw 特定的页面类型、文档 IA、保留和验证规则时，技能会加载这些覆盖约束。
二、核心功能
1. 任务分类与范围盘点
技能首先将任务分类为 构建（build）或 审查（review），并确定上下文是 棕地（brownfield） 还是 常青（evergreen）：
-
棕地模式：优先考虑与当前文档 IA、工具链和发布状态的兼容性
-
常青模式：优先考虑永恒措辞、更新策略和持久结构
然后执行完整的文档范围盘点：
-
治理文件：AGENTS.md、CONTRIBUTING.md 及其别名（CLAUDE.md、AGENT.md、.cursorrules 等）
-
产品文档：docs/ 目录、框架源文件、根/模块 README
-
检测多语言范围（README/docs 存在多种语言）并定义所需的同等性级别
2. 参考规则集加载
技能在开始构建或审查工作前，会加载以下参考规则：
| 参考文件 | 内容 |
|---|---|
references/agent-and-contributing.md |
代理指令和 CONTRIBUTING.md 工作流规则（清单、规范/别名映射、双模式平衡、交付标准、优先级/冲突处理） |
references/principles.md |
核心原则规则集（Matt Palmer & OpenAI） |
references/openclaw.md |
OpenClaw 特定的文档覆盖规则 |
references/build.md |
构建任务工作流 |
references/review.md |
审查任务工作流 |
references/tooling.md |
平台/工具链选择建议 |
3. 代理指令文件治理（AGENTS.md 生态）
技能对代理指令文件有专门的处理规则：
-
当存在
AGENTS.md时，将其视为规范（canonical）来源 -
别名文件（如
CLAUDE.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/）应保持为兼容性表面（compatibility surfaces） -
诊断代理文件漂移（agent-file drift）——团队需要反复提示才能发现缺失文件、损坏命令或策略冲突的情况
4. 子代理编排（Sub-agent Orchestration）
对于大型仓库或广泛的变更集，技能默认使用子代理进行并行发现/审查工作：
| 子代理 | 职责 | 模型 |
|---|---|---|
inventory-agent |
文件/配置发现、覆盖地图、缺失路径检查 | Claude Haiku（快速） |
governance-agent |
AGENTS/CONTRIBUTING/别名优先级、冲突、策略漂移 | Claude Sonnet（思考） |
docs-framework-agent |
框架配置、相对路径基础、文件路径 vs URL 路径映射检查 | Claude Sonnet（思考） |
synthesis-agent |
合并子代理输出为一个优先级修复计划和统一优先级模型 | Claude Opus（长文本） |
5. 主动问题扫描与修复
技能执行主动问题扫描，覆盖治理文件和文档内容表面，并在同一轮次中修复高置信度缺陷（除非明确要求仅报告模式）。
6. 输入参数
技能接受以下输入参数：
-
文档类型（教程、操作指南、参考、解释）和受众
-
文件范围或 diff 范围
-
文档框架/工具链约束（Fern、Mintlify、Sphinx 等）
-
构建/审查模式和棕地/常青意图
-
目标代理和人类兼容性意图
-
文档框架表面范围（Fern、Sphinx、Mintlify、Markdown/MDX/MDC/RST/RSC 文件）
-
调查深度/时间预算（快速通过 vs 详尽审查）
-
执行模式（单代理或子代理辅助）
-
修复模式（默认应用修复，或仅报告）
-
多语言范围：源语言、目标语言环境和同等性期望
-
仓库特定的覆盖约束
7. 输出交付物
技能输出以下内容：
-
更新的草稿或审查发现，附带明确的下一步行动
-
验证说明（检查了什么，还剩下什么）
-
导航/维护建议（长期质量保证）
-
治理文档对齐摘要（当 AGENTS/CONTRIBUTING 被触碰时）
-
代理指令表面地图（主文件、别名文件、Codex/Claude/Cursor 处理计划）
-
文档表面覆盖地图（审查了哪些 /docs、README 层级、框架特定源树）
-
自动检测的问题列表及应用的修复（或明确的仅报告发现）
-
子代理使用时的委托说明（委托范围和发现如何合并）
-
多语言同等性说明（同步、部分同步附理由、或有意分歧）
-
仓库特定覆盖说明（当使用时）
三、主要用途
-
创建或大修现有产品/代码库的文档
在棕地场景中，系统化地改进现有文档结构、内容和质量 -
构建常青文档
创建旨在长期准确可复用、不依赖特定发布状态的文档 -
审查文档 diff
检查结构、清晰度和操作正确性 -
全仓库文档审计
涵盖治理文件和产品文档表面的完整审计 -
更新 AGENTS.md 和 CONTRIBUTING.md
确保代理和贡献者工作流与当前仓库实践对齐 -
改善仓库入职体验
包含贡献说明、Issue 模板、PR 流程和审查门控的文档改进 -
设计治理文档策略
对于包含别名指令文件的仓库，建立 AGENTS.md 为规范、别名作为兼容性表面的策略 -
诊断代理文件漂移
发现并修复团队需要反复提示才能发现的缺失文件、损坏命令或策略冲突
四、重要原则
-
AGENTS.md 为规范：当存在 AGENTS.md 时，将其视为权威来源，别名文件仅作为兼容性表面
-
棕地优先兼容性：在现有代码库中工作时，优先考虑与当前文档 IA、工具链和发布状态的兼容性
-
常青优先永恒性：构建常青文档时，优先考虑永恒措辞、更新策略和持久结构
-
默认应用修复：除非明确要求仅报告模式，否则在发现高置信度缺陷时直接修复
-
大型任务使用子代理：对于仓库范围、多框架或高冲突的工作，默认使用子代理进行并行发现
-
多语言同等性：检测多语言范围并定义所需的同等性级别
-
复杂任务允许深度调查：对于复杂或高风险任务，允许运行更长、更深、更详尽的调查以建立信心
五、总结
Technical Documentation 是一个通用的技术文档与治理文档构建/审查技能，通过系统化的范围盘点、参考规则加载、子代理编排和主动问题扫描，确保文档对人和代理都清晰、可操作且可维护。它覆盖贡献者治理文件（AGENTS.md、CONTRIBUTING.md 及其别名生态）和产品文档表面（docs/、README、框架源文件），适用于棕地和常青两种场景。该技能是 OpenClaw 文档体系的基础层，当仓库存在 OpenClaw 特定覆盖规则时，技能会自动加载并应用这些约束。
