Skills in Drafting and Reviewing Technical and Governance Documentation

Software Development Engineer
389542 80199 Updated: 2026-07-12 22:48:39

"Technical Documentation" is a skill dedicated to creating and reviewing high-quality technical documentation and agent instruction files—ranging from contributor governance documents (e.g., AGENTS.md, CONTRIBUTING.md) to product documentation (e.g., docs/, README, framework source files). Applicable to both "brownfield" scenarios (existing products or codebases) and "evergreen" contexts (ensuring long-term accuracy and reusability), this skill employs systematic inventory checks, multi-language scope analysis, sub-agent orchestration, and proactive issue scanning to ensure documentation remains clear, actionable, and maintainable for both humans and agents.

Install
npx skills add https://github.com/openclaw/openclaw --skill technical-documentation
Run in AstronClaw
Skill Details readonly

I. Skill Overview

This skill creates or overhauls documentation within an existing product/codebase (brownfield mode), or builds long-term accurate, reusable evergreen documentation (evergreen mode). It covers both governance files (AGENTS.md, CONTRIBUTING.md and their aliases) and product documentation surfaces (the docs/ directory, README files, .md/.mdx/.mdc source files, plus Fern/Sphinx/Mintlify-style source content), and can perform full repository-wide documentation audits.
Core Positioning: This skill acts as the universal foundational layer for the OpenClaw documentation system. It is not hardcoded to the OpenClaw project itself; instead, it delivers a reusable documentation engineering methodology. If the repository contains OpenClaw-specific page types, information architecture (IA), retention rules, and validation rules, the skill loads these override constraints automatically.

II. Core Functional Capabilities

1. Task Classification & Scope Inventory

The skill first classifies the target task as either build or review, and identifies the working context as brownfield or evergreen:
  • Brownfield Mode: Prioritize compatibility with the existing documentation information architecture, toolchain, and release status.
  • Evergreen Mode: Prioritize timeless phrasing, long-term update strategies, and persistent structural design.
It then executes a full documentation scope inventory:
  1. Governance files: AGENTS.md, CONTRIBUTING.md, and their aliases (CLAUDE.md, AGENT.md, .cursorrules, etc.)
  2. Product documentation: The docs/ directory, framework source files, root/module-level READMEs
  3. Detect multilingual coverage (multiple language variants of README/docs) and define required parity standards across translations.

2. Reference Rule Set Loading

Before starting any build or review workflow, the skill loads the following reference rule files:
Reference File Core Content
references/agent-and-contributing.md Agent instructions and CONTRIBUTING.md workflow rules: checklists, specification/alias mapping, dual-mode balancing, delivery standards, priority & conflict resolution logic
references/principles.md Core foundational rule set (authored by Matt Palmer & OpenAI)
references/openclaw.md OpenClaw-specific documentation coverage constraints
references/build.md Standard workflow for build-type documentation tasks
references/review.md Standard workflow for review-type documentation tasks
references/tooling.md Guidance for documentation platform & toolchain selection

3. Governance of Agent Instruction Files (AGENTS.md Ecosystem)

The skill enforces dedicated handling logic for agent instruction files:
  1. If AGENTS.md exists within the repository, treat it as the single canonical source of truth.
  2. Alias files (e.g. CLAUDE.md, AGENT.md, .cursorrules, .cursor/rules/*, .agent/, .agents/, .pi/) exist solely as backward-compatibility surfaces.
  3. Diagnose agent-file drift: scenarios where the team requires repeated manual prompting to spot missing files, broken command definitions, or conflicting policy rules.

4. Sub-agent Orchestration

For large repositories or extensive change sets, the skill leverages parallel sub-agents to split discovery and review workloads:
Sub-agent Name Core Responsibility LLM Model Allocation
inventory-agent File/config discovery, coverage mapping, missing path validation Claude Haiku (fast lightweight analysis)
governance-agent AGENTS.md/CONTRIBUTING.md alias priority resolution, conflict detection, policy drift auditing Claude Sonnet (deep reasoning)
docs-framework-agent Framework configuration auditing, relative path base validation, file path ↔ URL path mapping checks Claude Sonnet (deep reasoning)
synthesis-agent Merge all sub-agent outputs into a unified prioritized remediation roadmap and consolidated priority model Claude Opus (long context window for large text synthesis)

5. Proactive Issue Scanning & Automated Remediation

The skill runs proactive defect scans across both governance files and product documentation surfaces. It automatically applies high-confidence fixes within the same workflow iteration, unless the user explicitly enables report-only mode.

6. Accepted Input Parameters

The skill accepts the following configurable input arguments:
  • Documentation category (tutorial, how-to guide, reference, explanatory background) + target audience definition
  • Target file scope or git diff scope for limited processing
  • Documentation framework/toolchain constraints (Fern, Mintlify, Sphinx, etc.)
  • Execution mode: build / review; working intent: brownfield / evergreen
  • Compatibility requirements for AI agents and human readers
  • Supported documentation framework surfaces: Fern, Sphinx, Mintlify, Markdown/MDX/MDC/RST/RSC source files
  • Investigation depth & time budget (quick pass vs exhaustive full audit)
  • Execution runtime mode: single standalone agent, or sub-agent assisted parallel processing
  • Remediation mode: apply fixes by default, or generate issue reports only
  • Multilingual scope: source language, target translation environments, and required parity standards
  • Repository-specific custom coverage constraints

7. Standard Output Artifacts

The skill produces the following structured deliverables upon completion:
  1. Revised documentation drafts or formal review findings, paired with clear actionable next steps
  2. Validation summary: full list of completed checks + outstanding unresolved items
  3. Navigation & long-term maintenance recommendations for sustained documentation quality
  4. Governance document alignment summary (generated when edits touch AGENTS.md / CONTRIBUTING.md)
  5. Agent instruction surface map: canonical primary file, all alias files, execution plan for Codex/Claude/Cursor integrations
  6. Documentation surface coverage map: audited docs/ directories, README hierarchy levels, framework-specific source tree coverage
  7. Auto-detected defect inventory + list of applied automated fixes (or explicit report-only findings if enabled)
  8. Sub-agent delegation breakdown: scope assigned to each sub-agent + logic used to merge separate discovery results
  9. Multilingual parity report: fully synchronized translations, partially synchronized content with rationale, or intentional deliberate divergence between language variants
  10. Repository-specific custom coverage compliance summary (if custom constraints are loaded)

III. Primary Use Cases

  1. Create or overhaul existing product/codebase documentation
     
    Systematically restructure, refine, and improve the quality of legacy documentation in brownfield repository environments.
  2. Build evergreen long-lived documentation
     
    Generate documentation designed for permanent accuracy and reusability, decoupled from temporary release cycle states.
  3. Review documentation diff changes
     
    Audit modified documentation for structural consistency, readability clarity, and operational factual correctness.
  4. Full repository-wide documentation audit
     
    Complete end-to-end audit covering both governance files and all product documentation surfaces.
  5. Update AGENTS.md and CONTRIBUTING.md
     
    Align AI agent workflows and human contributor guidelines with the repository’s current operational practices.
  6. Improve repository onboarding experience
     
    Refine documentation covering contribution workflows, Issue templates, PR review pipelines, and quality gate requirements.
  7. Design governance documentation strategy
     
    Establish a standardized policy for repositories with multiple alias instruction files: designate AGENTS.md as the canonical source, with aliases maintained solely for backward compatibility.
  8. Diagnose agent-file drift
     
    Identify and resolve missing files, broken command definitions, and conflicting policy rules that require repeated manual prompting from the engineering team.

IV. Critical Governing Principles

  1. AGENTS.md Canonical Rule: If AGENTS.md exists in the repository, treat it as the authoritative source; all alias files exist only as backward-compatibility surfaces.
  2. Brownfield Compatibility Priority: When working on legacy codebases, prioritize alignment with existing documentation IA, toolchain, and release workflows.
  3. Evergreen Timelessness Priority: When building permanent evergreen documentation, prioritize timeless neutral phrasing, sustainable update cycles, and long-lived structural design.
  4. Remediation Default Behavior: Automatically apply high-confidence defect fixes by default; only skip automated edits when report-only mode is explicitly requested.
  5. Sub-agent Parallelization for Large Workloads: Repository-wide, multi-framework, or high-conflict documentation tasks default to sub-agent parallel discovery workflows.
  6. Multilingual Parity Enforcement: Detect multilingual content coverage and enforce defined translation parity standards.
  7. Deep Investigation Allowance for Complex Tasks: Complex or high-risk documentation workflows permit extended, exhaustive deep-dive audits to establish full factual confidence.

V. Summary

Technical Documentation is a universal skill for building and auditing both technical product documentation and repository governance documentation. It delivers systematic scope inventorying, standardized reference rule loading, distributed sub-agent orchestration, and proactive defect scanning to produce clear, actionable, maintainable content readable by both human engineers and AI agents. It covers contributor governance files (the AGENTS.md / CONTRIBUTING.md alias ecosystem) and all product documentation surfaces (the docs/ directory, READMEs, framework-specific source files), supporting both brownfield legacy overhaul and evergreen permanent documentation workflows. This skill forms the foundational layer of the OpenClaw documentation system, automatically loading and applying repository-specific OpenClaw coverage constraints when present.
Source
Skills in Drafting and Reviewing Technical and Governance Documentation Logo
openclaw
openclaw/openclaw
Open GitHub repo View author repos
Download
Download Zip Run in AstronClaw
Hot Skills SOC