{"kind":"Skill","metadata":{"namespace":"community","name":"openclaw-refactor-docs","version":"0.1.0"},"spec":{"description":"Refactor an existing OpenClaw docs page with source-audited preservation, restructuring, and verification.","files":{"SKILL.md":"---\nname: openclaw-refactor-docs\ndescription: Refactor an existing OpenClaw docs page with source-audited preservation, restructuring, and verification.\n---\n\n# OpenClaw Refactor Docs\n\n## Overview\n\nUse this skill when the user gives a target OpenClaw docs page and asks to\nrewrite, refactor, reorganize, split, shorten, or improve it.\n\nThis skill builds on `openclaw-docs`: use that skill for style, page types,\nstructure, examples, discoverability, and verification. This skill adds the\nrewrite workflow needed to avoid losing accurate behavior during a major docs\nrefactor.\n\n## Inputs\n\nRequired:\n\n- A target docs page path, such as `docs/plugins/codex-harness.md`.\n\nOptional:\n\n- Desired page type, such as topic page, guide, reference, or troubleshooting.\n- Specific goals, such as shorter main page, move details to reference pages, or\n  align with current CLI behavior.\n- Related source files, schemas, commands, tests, specs, or PRs.\n\nIf the target page is missing or ambiguous, ask one concise question before\nediting. Otherwise, proceed.\n\n## Working Contract\n\nRefactor the target page to be more useful, concise, and comprehensive within\nits stated scope.\n\nDo not treat a rewrite as permission to discard behavior facts. Preserve,\nverify, move, or explicitly retire existing material. Incorrect docs are worse\nthan verbose docs.\n\nPrefer this split:\n\n- Topic or guide pages cover the 80/20 path, decisions readers must make, safe\n  setup, smallest reliable verification, common failures, and links onward.\n- Reference pages cover exhaustive fields, defaults, enums, limits, precedence\n  rules, API contracts, narrow internals, and rare debugging details.\n- Troubleshooting pages start from observable symptoms and map to checks,\n  causes, and fixes.\n\n## Workflow\n\n### 1. Load the doc standard\n\nRead `../openclaw-docs/SKILL.md` first. Apply its page-type, style,\nexamples, navigation, and verification guidance throughout the refactor.\n\nRun `pnpm docs:list` when available, then read only the target page and the\nlikely entry points, references, or related pages needed for the refactor.\n\n### 2. Classify the page\n\nBefore editing, decide the intended page type from `openclaw-docs`.\n\nIf the current page mixes page types, choose the main page type and plan where\nthe other material belongs:\n\n- Move exhaustive contracts to an existing or new reference page.\n- Move symptom-driven material to an existing or new troubleshooting page.\n- Move narrow setup workflows to a guide when they interrupt the main path.\n- Keep concise routing, decision, and safety details in the main page when\n  readers need them to complete the workflow.\n\n### 3. Preserve and audit existing facts\n\nCreate a working inventory from the old page before rewriting. Include:\n\n- Config fields, flags, commands, slash commands, env vars, defaults, enums,\n  nullable values, and constraints.\n- Precedence rules, fallback behavior, caps, limits, rate limits, timeouts,\n  lifecycle states, queueing behavior, and compatibility rules.\n- Auth, permission, approval, sandbox, safety, privacy, and destructive-action\n  behavior.\n- Setup requirements, supported versions, dependencies, operating systems,\n  credentials, and account requirements.\n- Error messages, troubleshooting symptoms, diagnostics, and recovery steps.\n- Examples, expected output, command routing tables, and cross-links.\n\nFor each fact, choose one outcome:\n\n- Keep it in the refactored target page.\n- Move it to a specific existing page.\n- Move it to a specific new page.\n- Delete it because current source proves it is obsolete or out of scope.\n\nDo not infer defaults, permissions, policy, timeout behavior, or safety posture\nfrom names or intent. Verify them.\n\n### 4. Find source of truth\n\nUse the nearest authoritative source for each behavior-sensitive claim:\n\n- Public schema, plugin manifest, generated config docs, or exported types for\n  config fields.\n- CLI implementation, slash-command handlers, help text, and command tests for\n  commands and flags.\n- Runtime source and tests for lifecycle, queueing, permission, fallback,\n  timeout, and provider behavior.\n- Protocol docs, SDK facades, and contract tests for APIs and plugin surfaces.\n- Existing docs only as secondary evidence unless the target is purely\n  conceptual.\n\nIf a page promises a reference, compare its tables against the schema,\nmanifest, CLI help, generated docs, or exported types. Missing public fields,\ndefaults, precedence rules, caps, or side effects are correctness bugs.\n\n### 5. Plan moved material\n\nWhen moving detail out of the target page, record the destination before\nediting:\n\n- Existing page: name the page and section.\n- New page: choose the page type, slug, title, frontmatter summary,\n  `doc-schema-version: 1`, and `read_when` hints.\n- Target page: keep a short summary and link from the point where readers need\n  the deeper detail.\n\nAvoid duplicate truth. If the same contract appears in multiple places, choose\none canonical page and link to it.\n\n### 6. Rewrite\n\nRewrite in this order:\n\n1. Make the first screen answer what the reader can do and why this page exists.\n2. Put the recommended path before alternatives.\n3. Keep only decision-making and common operational detail in the main flow.\n4. Move exhaustive tables and rare details to the planned reference pages.\n5. Preserve concise routing tables when they help readers choose commands,\n   config paths, harnesses, plugins, providers, or references.\n6. Add troubleshooting from observable symptoms, not internal guesses.\n7. Link related concepts, guides, references, diagnostics, and adjacent tools.\n\nAdd `doc-schema-version: 1` to the YAML frontmatter of every docs page that the\nrefactor migrates, creates, or materially rewrites. Apply it only to docs page\nfiles, not `docs.json`, glossary JSON, or other non-page metadata. If a\nmigrated page is generated, update the generator so regeneration preserves the\nmarker instead of hand-editing generated output.\n\nDo not leave placeholders such as \"TODO\", \"TBD\", or \"see docs\" unless the user\nexplicitly asks for a draft.\n\n### 7. Compare old and new\n\nAfter editing, compare the old and new page:\n\n- Confirm all behavior-sensitive facts were kept, moved, or intentionally\n  deleted with source-backed reason.\n- Check that the main page still covers the 80/20 scenario end to end.\n- Check that reference pages remain exhaustive for the scope they claim.\n- Check that links from the target page reach moved details.\n- Check that headings are stable, searchable, and action-oriented.\n\nIf the refactor deliberately removes relevant material, say where it went or why\nit was removed in the final report.\n\n### 8. Verify\n\nRun the smallest reliable docs checks for the touched surface:\n\n- `pnpm docs:list`\n- `git diff --check -- \u003ctouched-files\u003e`\n- Targeted `pnpm exec oxfmt --check --threads=1 \u003ctouched-files\u003e`\n- `pnpm docs:check-mdx`\n- `pnpm docs:check-links`\n- `pnpm docs:check-i18n-glossary` when link text, navigation, labels, or glossary\n  surfaces changed\n- Generated-doc checks when schemas, generated config docs, API docs, or\n  generated baselines are touched\n\nRun commands and examples from the page whenever feasible. If you cannot verify\na behavior-sensitive claim, either remove the claim, mark the uncertainty in the\nwork-in-progress report, or ask for the missing source.\n\n## Final Report\n\nReport:\n\n- What changed in the target page.\n- What details moved and their destination pages.\n- What source-of-truth checks backed behavior-sensitive claims.\n- What validation ran and what failed for unrelated reasons.\n\nDo not include a long rewrite diary. Lead with remaining risks only if there are\nany.\n"},"import":{"commit_sha":"424c6d0a5f4665b803ad6768d08b0be7659deaf4","imported_at":"2026-05-18T20:13:36Z","license_text":"MIT License\n\nCopyright (c) 2025 Peter Steinberger\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","owner":"openclaw","repo":"openclaw/openclaw","source_url":"https://github.com/openclaw/openclaw/tree/424c6d0a5f4665b803ad6768d08b0be7659deaf4/.agents/skills/openclaw-refactor-docs"}},"content_hash":[63,181,94,159,106,107,121,99,119,99,144,186,6,18,44,74,214,145,57,106,11,224,252,232,212,231,118,56,249,144,202,129],"trust_level":"unsigned","yanked":false}