I. Skill Overview
This skill activates when users provide target documentation pages and request rewriting, restructuring, reorganization, splitting, trimming, or content refinement. It builds on top of the
openclaw-docs skill — which handles style standards, page categorization, structural formatting, sample code readability, discoverability and validation — while adding dedicated refactoring workflows to prevent loss of accurate behavioral descriptions during large-scale documentation overhauls.II. Core Functional Capabilities
1. Page Type Classification
Before editing commences, the skill first identifies the intended page purpose. If the current document mixes multiple page types, it prioritizes the primary category and maps relocation destinations for all secondary content:
| Page Type | Core Responsibility Scope |
|---|---|
| Topic / Guide | Cover the 80/20 primary workflow paths, mandatory user decisions, security configurations, minimal reliable validation steps, common troubleshooting cases, and cross-relevant hyperlinks |
| Reference | Cover exhaustive field definitions, default values, enums, hard limits, priority logic, API contractual specs, internal implementation mechanics, and niche debugging details |
| Troubleshooting | Map observable user-facing symptoms to inspection checkpoints, root cause analysis, and step-by-step remediation workflows |
2. Behavioral Fact Audit Inventory
Prior to rewriting, the skill generates a working inventory extracted from the original page, capturing all actionable factual records:
- Configuration fields, feature flags, CLI arguments, slash commands, environment variables, default values, enums, nullable parameters and constraint rules
- Priority logic, fallback behavior, hard caps, usage limits, rate throttling, timeout thresholds, lifecycle state transitions, queue processing logic, and compatibility constraints
- Authentication flows, permission scopes, approval workflows, sandbox isolation, security controls, privacy policies, and destructive operation behaviors
- Setup prerequisites, supported runtime versions, dependency lists, operating system compatibility, credential and account requirements
- Error message templates, observable failure symptoms, diagnostic procedures, and recovery workflows
- Code examples, expected output samples, command routing lookup tables, and cross-document hyperlinks
For every factual entry, one final disposition is assigned:
- Retain the content within the refactored target page
- Move the entry to a specified existing separate document page
- Move the entry to a designated new document page
- Delete the entry (validated obsolete or out-of-scope per latest source code)
Critical Rule: Default values, permission policies, timeout logic, and security postures must never be inferred from naming or vague intent; all claims require authoritative source validation.
3. Authoritative Source Verification
All behavior-critical statements are cross-referenced against the latest official source material for validation:
| Content Category | Authoritative Validation Source |
|---|---|
| Configuration Fields | Public schemas, plugin manifests, auto-generated config documentation, exported type definitions |
| Commands & Flags | CLI implementation source, slash command handlers, built-in help text, command test suites |
| Lifecycle, Queue & Permission Logic | Production runtime source code and unit/integration tests |
| API & Plugin Surface Contracts | Protocol specifications, SDK facade implementations, contract test cases |
| Existing Written Docs | Secondary supporting evidence only, except for purely conceptual explanatory content |
Critical Rule: Any page designated as a reference document must align all data tables with schemas, manifests, CLI help output, auto-generated docs or exported type definitions. Missing public fields, default values, priority rules, hard limits or side effects count as factual correctness bugs.
4. Standard Refactoring Sequence
The skill executes rewrite workflows in fixed sequential order:
- Above-the-fold core value summary: Clarify what tasks the page enables for readers and its core purpose
- Prioritize recommended primary workflows before alternative secondary paths
- Streamline main workflows: Preserve only critical decision points and frequent user operations within primary content blocks
- Offload exhaustive tables and niche edge-case details to designated reference pages
- Retain routing lookup tables when they assist readers in selecting commands, config paths, harnesses, plugins, providers or reference materials
- Build symptom-first troubleshooting sections rooted in observable user issues, rather than internal implementation guesswork
- Insert hyperlinks to related concepts, guides, reference docs, diagnostic materials and adjacent tooling
Placeholder markers such as TODO, TBD or generic "see docs" links are strictly prohibited unless the user explicitly requests draft-mode output.
5. Automated Validation Checks
The skill runs the full suite of validation commands to audit modified documentation:
pnpm docs:list
git diff --check
pnpm exec oxfmt --check
pnpm docs:check-mdx
pnpm docs:check-links
# Execute when link text, navigation labels, tags or glossary entries are modified
pnpm docs:check-i18n-glossary
When schemas, auto-generated configuration docs, API specifications or generation baselines are altered, dedicated generated-document validation runs are triggered.
Critical Rule: Execute referenced CLI commands and embedded sample code snippets for live verification wherever possible. If a behavior-critical statement cannot be validated against authoritative sources, either remove the unsubstantiated claim, flag unresolved ambiguity in the final report, or prompt the user to supply missing source reference material.
III. Primary Use Cases
- Large-Scale Documentation Overhauls
Preserve all verified behavioral factual records during full-scale rewriting, reorganization or splitting of existing document pages.
- Standardized Document Typing & Segmentation
Split hybrid multi-purpose pages into dedicated, single-responsibility pages categorized as Topic/Guide, Reference or Troubleshooting.
- Source-Code Synchronized Documentation
Align written documentation with updated CLI logic, configuration schemas or API surfaces via comprehensive source audits to eliminate factual drift.
- Verbose Content Trimming & Readability Optimization
Relocate dense technical granularity to dedicated reference pages, keeping primary user-facing content focused on the 80/20 common workflows and reader decision points to improve readability.
- Structured Troubleshooting Authoring
Build systematic troubleshooting content based on observable end-user symptoms instead of internal implementation speculation.
IV. Mandatory Final Report Output
Upon completing all refactoring work, the skill must generate a structured summary report containing:
- Full list of modifications applied to the target document page
- Inventory of relocated details and their destination page paths
- All authoritative source audits used to validate behavior-critical statements
- All validation checks executed, plus any validation failures encountered
V. Core Governing Principles
- Inaccurate documentation poses greater harm than overly verbose documentation — all original content must be retained, validated, relocated or formally marked for removal during refactoring.
- Eliminate redundant factual duplication: If identical contractual logic appears across multiple documents, designate one canonical source page and cross-link to it from all other instances.
- Frontmatter Label Requirement: Append
doc-schema-version: 1to the frontmatter of every page that is newly created, migrated, or substantially rewritten. - Generated Page Handling Rule: If the refactored page is auto-generated content, update the document generator logic to persist the frontmatter label during regeneration; manual edits to auto-generated output are forbidden.
VI. Summary
OpenClaw Refactor Docs is a source-audit driven documentation refactoring skill. It enforces mandatory behavioral fact inventories, authoritative source validation, and standardized page-type segmentation to guarantee no verified behavioral descriptions are lost during major documentation restructuring. Built for OpenClaw projects requiring large-scale rewrite, reorganization, splitting or trimming of existing docs, it serves as a critical complementary extension to the base
openclaw-docs skill for heavy refactoring workloads.
