diff --git a/skills/technical-documentation/SKILL.md b/skills/technical-documentation/SKILL.md index 9caccfa..afcd40e 100644 --- a/skills/technical-documentation/SKILL.md +++ b/skills/technical-documentation/SKILL.md @@ -1,50 +1,107 @@ --- name: technical-documentation -description: Build and review high-quality technical docs as well as agent instruction files in your repository. +description: Build and review OpenClaw documentation, docs IA, source-backed docs diffs, and repo governance docs. license: AGPL-3.0-only metadata: source: "https://github.com/vincentkoc/dotskills" --- -# Technical Documentation +# OpenClaw Technical Documentation ## Purpose -Produce and review technical documentation that is clear, actionable, and maintainable for both humans and agents, including contributor-governance files and agent instruction files. +Produce and review OpenClaw documentation that is accurate, helpful, concise, +maintainable, and source-backed. Use this skill for product docs, docs IA, +docs preservation audits, OpenClaw governance docs, and docs-as-code +validation. ## When to use -- Creating or overhauling docs in an existing product/codebase (brownfield). -- Building evergreen docs meant to stay accurate and reusable over time. -- Reviewing doc diffs for structure, clarity, and operational correctness. -- Updating or reviewing AGENTS.md and/or CONTRIBUTING.md to keep agent and contributor workflows aligned with current repo practices. -- Improving repository onboarding/docs that include contribution instructions, issue templates, PR flow, and review gates. -- Designing governance documentation strategy for repos with alias instruction files (for example `CLAUDE.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`) where `CLAUDE.md` is treated as a canonical policy source and `AGENTS.md` should be kept as compatibility alias if present. +- Writing or reviewing OpenClaw docs under `docs/**`, including plugin, + provider, channel, CLI, SDK, Gateway, migration, setup, troubleshooting, and + reference pages. +- Reviewing docs navigation and routing in `docs/docs.json`, redirects, + generated references, and published docs URLs. +- Refactoring docs while preserving source coverage from older pages, PRs, + code comments, specs, or current implementation. +- Reviewing docs diffs for the OpenClaw rubric: accurate, helpful, concise, + complete within scope, maintainable, and findable. +- Updating OpenClaw repository governance docs such as root or scoped + `AGENTS.md`, `CONTRIBUTING.md`, `CODEOWNERS`, docs-related + `.github/labeler.yml`, or docs-facing changelog entries. +- Aligning docs with current behavior, shipped behavior, tests, source + contracts, or upstream dependency docs. +- Producing a report-only docs review, or applying high-confidence + documentation fixes when the user asks for implementation. ## Workflow -1. Classify task: `build` or `review`; context: `brownfield` or `evergreen`. -2. Read `references/agent-and-contributing.md` for agent instruction and `CONTRIBUTING.md` workflow rules (inventory, canonical/alias mapping, dual-mode balance, deliverable standards, and precedence/conflict handling). -3. Read `references/principles.md` for the governing ruleset (Matt Palmer & OpenAI). -4. For build tasks, follow `references/build.md`. -5. For review tasks, follow `references/review.md`. -6. Use `references/tooling.md` when platform/tooling choices affect recommendations. -7. In brownfield mode, prioritize compatibility with current docs IA, tooling, and release state. -8. In evergreen mode, prioritize timeless wording, update strategy, and durable structure. -9. Return deliverables plus validation notes and remaining gaps. +1. Classify the task: `write`, `review`, `refactor`, `ia`, `audit`, or + `governance`. +2. Read scoped OpenClaw instructions before subtree work. For docs/user-visible + work, run `pnpm docs:list`, then read only the relevant docs and source + surfaces. +3. Identify the reader and page type before writing: overview, quickstart, topic + page, guide, API/SDK/CLI reference, testing guide, troubleshooting page, + maintainer note, or governance file. +4. Read `references/principles.md` for OpenClaw docs principles and page-type + rules. +5. For build/refactor/IA tasks, follow `references/build.md`. +6. For review tasks, follow `references/review.md`. +7. For AGENTS/CONTRIBUTING/governance work, follow + `references/agent-and-contributing.md`. +8. Use `references/tooling.md` when docs platform, Mintlify routing, generated + references, or validation commands affect the outcome. +9. Verify claims against source, tests, current behavior, shipped behavior, or + upstream dependency contracts. Accuracy is a hard gate. +10. For moved or rewritten docs, run a preservation-minded audit: identify + source units, destination ownership, moved sections, dropped sections, and + any missing coverage. +11. Apply high-confidence fixes only when the user asked for implementation. For + report-only requests, return findings and validation gaps without editing. +12. Return the changed draft or review findings with exact validation notes and + any relevant `https://docs.openclaw.ai/...` URL(s). + +## Sub-agent orchestration guidance + +Use sub-agents only when explicitly available and the docs task is broad enough +to benefit from parallel discovery. Merge all outputs into one OpenClaw-specific +recommendation or patch plan. + +- `inventory-agent` -> `agents/inventory-agent.md`: map OpenClaw docs files, + `docs/docs.json`, generated references, redirects, and missing paths. +- `governance-agent` -> `agents/governance-agent.md`: review OpenClaw + `AGENTS.md`, `CONTRIBUTING.md`, `CODEOWNERS`, labeler, changelog, and + scoped-instruction alignment. +- `docs-framework-agent` -> `agents/docs-framework-agent.md`: verify + Mintlify/file/URL routing, main-reader-path versus `Reference` placement, and + generated-doc visibility. +- `synthesis-agent` -> `agents/synthesis-agent.md`: merge findings into one + prioritized OpenClaw docs fix plan. ## Inputs -- Doc type (tutorial, how-to, reference, explanation) and audience. +- Task class and desired mode (`apply-fixes` or `report-only`). +- OpenClaw reader: user, operator, plugin author, contributor, maintainer, or + release owner. +- Page type and docs surface (`docs/**`, `docs/docs.json`, README, generated + reference, AGENTS, CONTRIBUTING, labeler, changelog). - File scope or diff scope. -- Docs framework/tooling constraints (Fern, Mintlify, Sphinx, etc.). -- Build/review mode and brownfield/evergreen intent. -- Target agent and human compatibility intent. +- Source-of-truth contracts: code path, command output, tests, shipped behavior, + upstream docs/types, spec, or prior page. +- Validation expectations: docs-list, MDX, links, glossary, formatting, + diff check, generated-doc checks, or behavior tests. +- Preservation requirements for rewrites: source ref, destination pages, + keep/drop/move matrix, and audit depth. ## Outputs -- Updated draft or review findings with clear next actions. -- Validation notes (what was checked, what remains). -- Navigation/maintenance recommendations for long-term quality. -- Governance-doc alignment summary when AGENTS/CONTRIBUTING were touched. -- Agent instruction-surface map (primary file, alias files, Codex/Claude/Cursor handling plan). +- Updated OpenClaw draft or source-backed review findings. +- For reviews: blocking findings first, then non-blocking improvements, then + validation notes. +- For docs IA/refactors: page-type classification plus + keep/drop/move/destination matrix. +- For preservation audits: source coverage summary, mapped destinations, gaps, + and any unsupported drops. +- For governance work: scoped-instruction and contributor-flow alignment summary. +- Validation notes with exact commands run, commands not run, and why. diff --git a/skills/technical-documentation/agents/openai.yaml b/skills/technical-documentation/agents/openai.yaml index 903f204..3ec80a8 100644 --- a/skills/technical-documentation/agents/openai.yaml +++ b/skills/technical-documentation/agents/openai.yaml @@ -1,10 +1,10 @@ interface: - display_name: "Technical Documentation" - short_description: "Build and review technical documentation for brownfield and evergreen systems." + display_name: "OpenClaw Documentation" + short_description: "Build and review OpenClaw docs, docs IA, source-backed diffs, and governance docs." icon_small: "./assets/icon.jpg" icon_large: "./assets/icon.jpg" brand_color: "#111827" - default_prompt: "Build or review technical documentation with a clear, maintainable, and production-ready workflow." + default_prompt: "Build or review OpenClaw docs with source-backed accuracy and docs-as-code validation." policy: allow_implicit_invocation: true diff --git a/skills/technical-documentation/references/agent-and-contributing.md b/skills/technical-documentation/references/agent-and-contributing.md index 1f4b294..c6ec375 100644 --- a/skills/technical-documentation/references/agent-and-contributing.md +++ b/skills/technical-documentation/references/agent-and-contributing.md @@ -1,111 +1,86 @@ -# AGENT and CONTRIBUTING Principles - -This reference consolidates the core rules for agent-policy and contributor-governance docs. - -You must: -1. Discover repo-level and nested instruction files with: - `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'` -2. Read the root and nearest-scope `AGENTS.md`/`CONTRIBUTING.md` pair before editing. -3. If alias files exist, normalize to one canonical source (`AGENTS.md` preferred when present; otherwise nearest alias), plus compatibility pointers or explicit symlink notes. -4. Document conflicting instructions and precedence decisions. - -## GitHub + AGENTS baseline - -Source: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors -Source: https://agents.md/ -Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/ -Source: https://cobusgreyling.substack.com/p/what-is-agentsmd -Source: https://www.infoq.com/news/2025/08/agents-md/ - -Use these as default operating principles: - -1. Keep `CONTRIBUTING.md` discoverable and actionable (`.github`, root, or `docs`). -2. Keep agent instructions concrete: real commands, real paths, clear boundaries. -3. Use explicit behavior boundaries for agents: `Always`, `Ask first`, `Never`. -4. Keep contributor and agent rules aligned with actual repository workflows. -5. Ensure clear guidance is provided to agents on if, when and how to raise issues and pull requests. - -## Canonical and alias policy - -Source: https://agents.md/ -Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/ - -1. Treat `AGENTS.md` as canonical when present. -2. If `AGENTS.md` is absent, treat the nearest alias file as canonical. -3. Keep compatibility surfaces explicit: `AGENTS.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`. -4. If aliases are used, document how they map back to canonical policy (or symlink when supported). - -## Context-awareness by agent platform - -Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -Source: https://github.com/openai/codex/blob/main/AGENTS.md - -1. For Cursor and Claude-style glob consumers, keep rule files narrow and bounded. -2. Avoid over-referencing large path sets that inflate context for glob-based agents. -3. For Codex-style workflows, prefer explicit file references and deterministic commands. -4. Keep long runbooks outside top-level policy files; link to scoped docs. -5. Ensure all agents have a happy path regardless so ensuring everything works across Codex, Claude and other coding agents. - -## Dual-mode and deliverable standards - -Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/ -Source: https://agents.md/ -Source: https://github.com/openai/codex/blob/main/AGENTS.md -Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md - -1. Author one shared policy core (same commands, boundaries, and precedence) for all agents. -2. For Cursor/Claude-style agents, expose that core through glob-driven and bounded files (small `AGENTS.md`/rule surface). -3. For Codex, expose that same core through explicit file references with precise scope. -4. Where styles diverge, prefer the smallest common structure that satisfies both and avoid duplicating policy text. -5. Treat AGENTS/CONTRIBUTING as first-class deliverables when in scope. -6. Preserve required structure, constraints, and examples from existing files. -7. Align wording and commands with active repository instructions. - -## Discovery - -1. Agents prefer simple terminal commands so having a well defined `make *` or `npm run *` is ideal -2. Agents can discover terminal commands through shell completion so providing shell completion helps - -## CONTRIBUTING size and scope control - -Source: https://contributing.md/how-to-build-contributing-md/ -Source: https://blog.codacy.com/best-practices-to-manage-an-open-source-project -Source: https://mozillascience.github.io/working-open-workshop/contributing/ -Source: https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md - -1. Keep root `CONTRIBUTING.md` focused on setup, issue flow, PR flow, testing, and review gates. -2. Use issue/PR template links instead of embedding every process detail inline. -3. When the file grows too large, split by domain and link from root. -4. Move any large content into docs if avalible (for example Mintlify/Fern/Sphinx workflows) to avoid large contributor guide. -5. Optimize for agent/machine readability as well as humans. - -## Example repos to emulate - -Source: https://github.com/openclaw/openclaw/blob/main/AGENTS.md -Source: https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md -Source: https://github.com/openclaw/openclaw/blob/main/VISION.md -Source: https://github.com/openai/codex/blob/main/AGENTS.md -Source: https://github.com/processing/p5.js/blob/main/AGENTS.md -Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md -Source: https://github.com/agentsmd/agents.md/blob/main/AGENTS.md -Source: https://github.com/rails/rails/blob/main/CONTRIBUTING.md -Source: https://github.com/kubernetes/kubernetes/blob/master/CONTRIBUTING.md -Source: https://github.com/atom/atom/blob/master/CONTRIBUTING.md -Source: https://github.com/github/docs/blob/main/CONTRIBUTING.md -Source: https://github.com/facebook/react/blob/main/CONTRIBUTING.md - -1. OpenClaw: strong real-world alias policy and AGENTS/CONTRIBUTING/VISION cohesion. -2. OpenAI Codex: strict command discipline and explicit scope control. -3. p5.js: explicit AI-policy guardrails in agent instructions. -4. Vercel + agentsmd spec: compact, context-efficient AGENTS patterns. -5. Rails/Kubernetes/Atom/GitHub Docs/React: contributor guidance patterns at different project scales. - -## Practical merge policy - -When these rules conflict: - -1. Preserve contributor and reader task success first. -2. Preserve instruction clarity and unambiguous boundaries second. -3. Preserve long-term maintainability and context-efficiency third. -4. Add extra agent optimization only if it does not reduce human clarity or there is explict need. -5. Use your judgement as the expert. +# OpenClaw Agent and Contributor Docs + +Use this reference for OpenClaw `AGENTS.md`, `CONTRIBUTING.md`, CODEOWNERS, +labeler, changelog, and adjacent governance documentation. + +## Required discovery + +Before editing governance docs, discover the relevant instruction scope: + +```bash +rg --files -g 'AGENTS.md' -g 'CLAUDE.md' -g 'CONTRIBUTING.md' -g 'CODEOWNERS' -g '.github/labeler.yml' +``` + +Then read: + +1. root `AGENTS.md` +2. nearest scoped `AGENTS.md` for the files being edited +3. `CONTRIBUTING.md` when contributor workflow is affected +4. `CODEOWNERS`, labeler, changelog, or workflow docs when the change touches + ownership, labels, PR flow, releases, channels, plugins, apps, or docs + surfaces + +## OpenClaw source of truth + +- `AGENTS.md` is canonical for Codex repository instructions. +- Scoped `AGENTS.md` files narrow or add rules for their subtree. +- When creating a new `AGENTS.md`, add a sibling `CLAUDE.md` symlink and edit + `AGENTS.md` only. +- Do not treat `CLAUDE.md`, `.cursor`, `.cursorrules`, or other generic + agent-file conventions as canonical unless the active OpenClaw instructions + explicitly say so. +- Do not add `.cursor -> .agents` compatibility symlinks as a default OpenClaw + docs operation. + +## Governance writing rules + +- Telegraph style for root policy: short, concrete, repo-specific. +- Keep long runbooks out of root policy; route them to scoped repo docs or + dedicated bundled references. +- Include real commands and real repo paths. +- Prefer boundaries over broad advice: what is allowed, what needs owner review, + and what is never allowed. +- Keep product/docs/UI wording aligned with OpenClaw root policy: use + "plugin/plugins"; `extensions/` is internal except in file paths. +- Never print secrets, credentials, live config, real phone numbers, or private + artifacts. + +## Contributor workflow checks + +For `CONTRIBUTING.md` or contributor-facing guidance: + +- Verify setup, install, build, test, lint, docs, and PR commands match current + repo wrappers. +- Keep issue triage, PR expectations, review gates, and validation commands + actionable. +- Link to deeper docs instead of embedding every domain runbook in the root + contributor guide. +- Do not contradict scoped `AGENTS.md`, CODEOWNERS, or release/security policy. + +## Labeler, ownership, and changelog impact + +- New channel/plugin/app/doc surfaces may require `.github/labeler.yml` and + GitHub label updates. +- Larger behavior/product/security/ownership changes need owner review. +- Docs changes tied to behavior/API/CLI/config changes should align with the + changelog policy for that change. +- Contributor PR authors should not add OpenClaw changelog entries unless the + maintainer workflow explicitly asks for it. + +## Conflict handling + +When governance sources disagree: + +1. Prefer the active root `AGENTS.md`. +2. Apply nearest scoped `AGENTS.md` rules for files under that scope. +3. Prefer current repo commands and source behavior over stale prose. +4. If a rule would cause unsafe git mutation, credential exposure, broad cleanup, + or owner-boundary violations, stop and ask. +5. Record the conflict and the smallest proposed fix. + +## Deliverables + +- State which governance files were read. +- Summarize any policy conflicts and the selected precedence. +- For edits, include exact validation commands run or skipped. +- For report-only reviews, list blocking policy drift first, then cleanup items. diff --git a/skills/technical-documentation/references/build.md b/skills/technical-documentation/references/build.md index c21ad5b..a219151 100644 --- a/skills/technical-documentation/references/build.md +++ b/skills/technical-documentation/references/build.md @@ -1,80 +1,101 @@ -# Build Docs Playbook - -Read `principles.md` first, then follow this execution flow. - -## 1. Detect and align agent instruction and governance instructions - -- Use `references/agent-and-contributing.md` as the source of truth for inventory, canonical/alias mapping, and precedence/conflict handling. -- Capture required constraints before writing: - - nested-agent rules, command/test requirements, PR workflow, and style checks. -- Use the same command and validation expectations in proposed snippets and examples. - -## 2. Define intent and success - -- Audience, prerequisites, and job-to-be-done. -- Expected reader outcome immediately after completion. -- Doc type: tutorial, how-to, reference, explanation. -- Success criteria: what must be true after publish. +# OpenClaw Docs Build Playbook + +Read `principles.md` first, then follow this execution flow for writing, +refactoring, or changing OpenClaw docs IA. + +## 1. Establish scope and source of truth + +- Classify the task: new page, page edit, docs refactor, nav/IA change, + generated-reference change, troubleshooting addition, maintainer note, or + governance update. +- For docs/user-visible work, run `pnpm docs:list` before drafting and use it + to find current docs surfaces. +- Read only the relevant current docs, source files, tests, command output, + upstream docs/types, specs, or prior pages needed to support the change. +- If the request is a maintainer/internal flow, keep it in scoped repo docs or a + bundled reference only when it belongs in this skill. Do not reference private + local-only paths from repo-wide docs. + +## 2. Choose page type and reader + +- Reader: user, operator, plugin author, contributor, maintainer, or release + owner. +- Page type: overview, quickstart, topic page, guide, API/SDK/CLI reference, + testing guide, troubleshooting page, maintainer note, or governance file. +- Use topic pages for major product surfaces. Main docs should cover the 80/20 + path; reference/support pages carry exhaustive contracts and rare detail. +- State intentional scope limits up front when a page is partial. ## 3. Build structure before prose -- Follow the funnel: what/why, quickstart, next steps. -- Keep headings informative and scannable. -- Open each section with the takeaway sentence. -- Add decision points with concrete branch guidance. - -## 4. Build AGENTS.md and CONTRIBUTING.md intentionally - -- Keep AGENTS.md structure consistent with `agents.md` ecosystem patterns: - - include YAML frontmatter when present in repo style (`name`, `description`). - - state persona scope and explicit instruction boundaries: `Always`, `Ask first`, `Never`. - - include concrete commands and representative code examples. -- For CONTRIBUTING.md, prioritize issue triage flow, PR expectations, setup/test commands, and review gates. -- Add `Code of Conduct`, `Testing`, `Local checks`, and `PR expectations` sections when missing but required by the repo. -- If CONTRIBUTING.md is becoming too large, split by scope into linked docs (for example, framework/tool-specific setup and release workflows) and keep the root file as a concise entry point. -- Keep cross-file consistency: links from CONTRIBUTING.md to AGENTS.md (and vice versa) should be accurate and non-circular. -- If multiple AGENTS.md files exist, document the directory-level scope and avoid conflicting advice. - -## 5. Keep agent context tight - -- Author once, expose twice: - - keep one shared policy core and avoid duplicating guidance in separate agent-specific files. - - publish that core through bounded glob-friendly files for Cursor/Claude plus explicit path references for Codex. -- For Cursor and Claude-style agents, avoid broad references. Use minimal globbing and narrow rule files that each serve one concern (for example, repo-wide setup, test rules, security checks). -- Keep AGENTS and alias files short-to-medium; move detailed runbooks to linked docs. -- For Codex, prefer explicit file references and concrete paths for exact reuse. -- Avoid adding unrelated historical or process details to avoid token/context drift during future tool reads. - -## 6. Brownfield build mode - -- Match existing terminology, navigation, and component patterns. -- Preserve existing IA unless there is a documented migration plan. -- For rewrites, include a migration note from old to new paths. -- Prefer smallest safe change set that improves utility. - -## 7. Evergreen build mode - -- Prefer stable concepts over release-tied narrative. -- Isolate volatile details under clearly marked version sections. -- Include maintenance signals: owners, refresh triggers, stale criteria. -- Include lifecycle notes: deprecation and replacement paths. - -## 8. Writing constraints - -- Use precise language and short, imperative instructions. -- Keep code examples copy-ready and self-contained. -- Include common failure modes and safe defaults. -- Avoid placeholder guidance that cannot be executed. - -## 9. Agent and automation readiness - -- Keep key facts in text (not image-only). -- Prefer structured lists/tables when choices matter. -- Add links and anchors that allow deterministic navigation. -- Document what can be checked automatically in CI. - -## 10. Build validation - -- Validate commands and snippets where possible. -- Verify links and references in changed sections. -- Record unresolved checks explicitly in handoff. +- Put the first useful action early unless conceptual setup is required to pick + the right path. +- Use verb-led headings for guides and task-oriented headings for topic pages. +- Keep task-critical configuration inline; link exhaustive defaults, enums, + schemas, and generated references. +- Attach caveats and warnings to the step where they matter. +- Use "plugin/plugins" in user-facing docs and reserve `extensions/` for paths + or internal repository instructions. + +## 4. OpenClaw docs IA and navigation + +- Read `docs/docs.json` before nav changes. +- Classify by page type before placement: + - topic pages and 80/20 workflows stay on the main reader path. + - reference/support pages belong under `Reference`. + - generated `plugins/reference/*` children and redirect-only pages stay out of + visible nav unless explicitly required. +- For plugin-docs IA, keep install/manage flows on the main reader path and move + SDK/API/maintainer/reference surfaces to `Reference`. +- For new channel/plugin/app/doc surfaces, check whether `.github/labeler.yml` + and GitHub labels also need updates. +- For moved pages, include a keep/drop/move/destination matrix in the handoff. + +## 5. Preserve source coverage during refactors + +- Identify source units before rewriting: headings, paragraphs, tables, + examples, CLI/API contracts, warnings, and troubleshooting facts. +- Map each retained unit to a destination page or section. +- Do not treat a broad "covered" row as proof for dense source material; use + line- or claim-level evidence when the source unit is dense. +- For dropped content, state whether it is obsolete, duplicated elsewhere, + unsupported, or moved to a reference/support page. +- When a docs-audit artifact is used, verify it is mapped audit data with + non-empty `mappings[]`, not only inventory or reindexed JSON. + +## 6. Source-backed content requirements + +- CLI docs must match current flags, output, errors, and examples. +- API/SDK docs must include fields, defaults, enum values, constraints, + nullable behavior, lifecycle states, errors, and recovery guidance. +- Config docs must align exported types, schema/help, metadata, baselines, and + current docs. +- Dependency-backed behavior must be verified from upstream docs, source, or + types before documenting defaults, timing, errors, or API behavior. +- Security-sensitive docs must avoid real secrets, live config, phone numbers, + private videos, or credentials. + +## 7. Governance docs + +- For root/scoped `AGENTS.md`, `CONTRIBUTING.md`, `CODEOWNERS`, labeler, or + changelog work, use `agent-and-contributing.md`. +- Keep root governance concise and route detailed runbooks to scoped repo docs + or dedicated bundled references where appropriate. +- Do not introduce generic agent-file conventions that conflict with OpenClaw + root policy. + +## 8. Validation + +Choose the narrowest validation that proves the touched surface: + +- `pnpm docs:list` +- `pnpm docs:check-mdx` +- `pnpm docs:check-links` +- `pnpm docs:check-i18n-glossary` +- `pnpm format:docs:check` or `pnpm lint:docs` +- `git diff --check` +- generated-doc or inventory checks when generated references, plugin catalogs, + labeler, or docs scripts changed +- behavior tests or command probes when docs claim runtime behavior + +If proof is blocked, say exactly which command was not run and why. diff --git a/skills/technical-documentation/references/principles.md b/skills/technical-documentation/references/principles.md index 88cb273..84cc9d3 100644 --- a/skills/technical-documentation/references/principles.md +++ b/skills/technical-documentation/references/principles.md @@ -1,42 +1,103 @@ -# Documentation Principles +# OpenClaw Documentation Principles -This reference consolidates the core rules used by this skill. +Use these rules as the governing model for OpenClaw docs work. -## Matt Palmer: 8 rules for better docs +## Reader model -Source: https://mattpalmer.io/posts/2025/10/8-rules-for-better-docs/ +1. Lead with the OpenClaw task the reader is trying to complete. +2. Give one recommended path before alternatives. +3. Keep main docs focused on the 80/20 scenario. +4. Move dense contracts, exhaustive fields, rare debugging paths, generated + material, and maintainer-only detail to linked reference/support pages. +5. Put production risks exactly where the reader can make the mistake. +6. Link concepts, guides, references, CLI pages, SDK docs, testing, and + troubleshooting so readers can continue without rereading. -Use these as default operating principles: +## Page types -1. Write for humans, optimize for agents. -2. Start with a funnel: what/why, quickstart, next steps. -3. Use Diataxis to scaffold content. -4. Write with AI, but structure for agents. -5. Offload routine docs operations to background agents. -6. Automate quality with CI. -7. Automate scaffolding and repetitive workflow tasks. -8. Make contribution easy and visible. +Choose a page type before writing: -## OpenAI cookbook: what makes documentation good +- Overview: route readers to the right product area, integration path, or guide. +- Quickstart: get a new user to a working result with the fewest safe steps. +- Topic page: explain a major OpenClaw entity or surface end to end. +- Guide: walk through one workflow from prerequisites to production readiness. +- API/SDK/CLI reference: define every object, method, command, option, response, + error, enum, default, and version rule in scope. +- Testing guide: show sandbox setup, fixtures, simulated failures, and live-mode + differences. +- Troubleshooting guide: map observable symptoms to checks, causes, and fixes. +- Maintainer note: capture repo-relevant internal flow, proof, rollout, or + release behavior in scoped repo docs or bundled references when it belongs in + this skill. Do not route repo-wide docs to personal or local-only paths. +- Governance file: keep agent/contributor policy concrete, scoped, and aligned + with current OpenClaw repo behavior. -Source: https://cookbook.openai.com/articles/what_makes_documentation_good +## Topic page default -Key quality constraints: +Use this shape for major-entity pages: -- Prefer specific and accurate terminology over niche jargon. -- Keep examples self-contained and minimize dependencies. -- Prioritize high-value topics over edge-case depth. -- Do not teach unsafe patterns (for example, exposed secrets). -- Open with context that helps readers orient quickly. -- Apply empathy and override rigid rules when it clearly improves outcomes. +1. Title naming the entity or surface. +2. Unheaded opening that says what it is, what it owns, and what it does not + own. +3. Requirements, only when setup needs accounts, versions, permissions, plugins, + operating systems, or credentials. +4. Quickstart with the recommended path and smallest reliable verification. +5. Configuration with task-critical options inline and exhaustive details linked + to reference docs. +6. Major subtopics organized by reader intent, not under a generic + "Subtopics" heading. +7. Troubleshooting with observable failures and concrete checks. +8. Related links to guides, references, commands, concepts, and adjacent topics. -## Practical merge policy +## OpenClaw terminology -When these rules conflict: +- Use **OpenClaw** for the product and `openclaw` for CLI/package/path/config. +- Use **plugin/plugins** in product docs and user-facing text. +- Treat `extensions/` as an internal repository layout term; use it only when + a file path or internal contributor instruction requires it. +- Prefer concrete OpenClaw nouns: agent profile, Gateway webhook, plugin + manifest, channel, provider, session state, capability, migration plan. +- Define OpenClaw-specific jargon before first use. -1. Preserve reader task success first. -2. Preserve structural clarity second. -3. Preserve long-term maintainability third. -4. Add agent optimization only if it does not reduce human clarity. +## Writing style -For agent-instructions and contributor-governance specifics (AGENTS/aliases/CONTRIBUTING), use `references/agent-and-contributing.md` as the detailed additional source of truth. +- Use present tense, active voice, and direct instructions. +- Address the reader as "you" for procedural steps. +- Use short paragraphs and scannable lists. +- Use sentence case headings unless a product name, command, or identifier + requires capitalization. +- Use descriptive link text; avoid "this page" and "click here." +- Avoid marketing language, hype, generic benefits, and vague claims. +- Avoid culturally specific idioms, jokes, and image/color-only instructions. +- Use "must" for requirements, "can" for optional capability, "recommended" for + the default path, and "avoid" for known footguns. +- Explain "why" only when it changes a developer decision. + +## Examples + +- Prefer complete copy-pasteable commands and snippets. +- Use realistic variable names and values. +- Mark placeholders with angle-bracket names such as `` or + ``. +- Show expected success output after commands when it helps verification. +- Keep one conceptual unit per code block and use language-specific fences. +- Avoid examples that hide setup, auth, error handling, or cleanup. + +## Review rubric + +Use this rubric for every docs review: + +- `accurate`: source, tests, current behavior, shipped behavior, and dependency + contracts support the statement. +- `helpful`: the page answers the reader's task without making them infer key + steps. +- `concise`: the main path is not buried under rare details or repeated prose. +- `complete within scope`: the page covers what it claims and names intentional + limits. +- `maintainable`: source of truth, generated content, ownership, and refresh + triggers are clear. +- `findable`: title, headings, docs-list hints, nav placement, and related links + match likely reader intent. + +Accuracy is a hard gate. A concise page that is wrong or unverified is not +acceptable. diff --git a/skills/technical-documentation/references/review.md b/skills/technical-documentation/references/review.md index 68939b5..5dd6989 100644 --- a/skills/technical-documentation/references/review.md +++ b/skills/technical-documentation/references/review.md @@ -1,77 +1,107 @@ -# Review Docs Playbook +# OpenClaw Docs Review Playbook -Read `principles.md` first, then apply this checklist. +Read `principles.md` first, then use this checklist for OpenClaw docs reviews. ## 1. Scope and classification -- Identify doc type and target audience. -- Confirm brownfield vs evergreen intent. -- Confirm expected outcome for the reader. - -## 2. Governance surface review - -- Use `references/agent-and-contributing.md` as the source of truth for inventory, canonical/alias mapping, and precedence/conflict handling. -For AGENTS.md: - -- confirm persona intent, scope, and command/tool boundaries are explicit. -- check frontmatter style matches repo conventions when present. -- ensure `Always`, `Ask first`, and `Never` boundaries are present when expected. -- require concrete command examples and repo-specific paths to avoid ambiguity. - -For CONTRIBUTING.md: - -- verify issue/PR workflow is complete and actionable. -- ensure local setup, lint/test commands, and review criteria are accurate. -- ensure governance does not conflict with nested AGENTS instructions. -- flag oversized files that should be split into linked section docs (for example tool-specific setup and release docs). - -For agent-platform awareness: - -- confirm references are minimal and scoped for Cursor/Claude glob behavior. -- confirm Codex-facing guidance uses explicit file references. -- confirm both surfaces represent the same shared policy core (commands, boundaries, and precedence), not divergent guidance. -- check for context bloat from duplicated policy statements across agent and contributor files. -- check for conflicting rules, skills and agent instructions -- check for conflicting information in agent instructions vs codebase - -## 3. Structural review - -- Funnel check: what/why, quickstart, next steps. -- Validate heading flow and navigation discoverability. -- Flag critical content trapped in images or buried sections. -- Check Diataxis alignment and split mixed-purpose sections. - -## 4. Writing quality review - -- Check for concise, scannable paragraphs. -- Remove ambiguous pronouns and undefined terms. -- Verify examples are executable and scoped correctly. -- Verify tone is directive, technical, and non-hand-wavy. - -## 5. Brownfield review mode - -- Verify compatibility with existing docs IA and conventions. -- Verify anchors, redirects, and cross-doc links remain valid. -- Flag regressions in onboarding and task completion paths. -- Ensure changed terminology is intentionally propagated. - -## 6. Evergreen review mode - -- Flag date-stamped or brittle wording without version scope. -- Check ownership and refresh signals are present. -- Ensure recommendations remain valid after routine product evolution. -- Flag missing deprecation/migration guidance. - -## 7. Tooling and platform review - -Read `tooling.md` if platform fit is uncertain. - -- Check whether content uses platform primitives effectively. -- Flag structure that fights the chosen docs platform. -- Recommend targeted platform-aware improvements. - -## 7. Output format - -1. Blocking issues (file + required fix) +- Identify task mode: report-only review or apply-fixes. +- Identify page type and reader. +- Identify touched surfaces: `docs/**`, `docs/docs.json`, README, generated + reference, AGENTS, CONTRIBUTING, CODEOWNERS, labeler, changelog, or scripts. +- For docs/user-visible work, run `pnpm docs:list`, then read relevant docs and + source only. + +## 2. Findings standard + +Lead with bugs, behavioral inaccuracies, regressions, missing proof, and docs IA +failures. Each finding must include: + +- failed rubric criterion: accurate, helpful, concise, complete within scope, + maintainable, or findable +- affected file/path/section +- why it fails, backed by source, tests, current behavior, shipped behavior, or + dependency contract evidence +- smallest fix + +Accuracy is blocking. Do not downgrade inaccurate behavior, commands, flags, +config, or API contracts to a style nit. + +## 3. Source-backed accuracy checks + +- Verify CLI commands, flags, outputs, errors, and examples against source, + tests, or executable probes. +- Verify API/SDK/config contracts against exported types, schemas, help output, + generated docs, or upstream docs/types. +- Verify screenshots, UI labels, nav labels, file paths, and published URLs when + they are part of the docs claim. +- For dependency-backed behavior, read upstream docs/source/types before making + statements about defaults, timing, errors, or API behavior. +- Separate current behavior, shipped behavior, planned behavior, and maintainer + intent. + +## 4. Structure and page-type review + +- Confirm the page type is correct for the content. +- Topic pages should follow: opening, requirements when needed, quickstart, + configuration, major subtopics, troubleshooting, related. +- Guides should name the outcome, include prerequisites, steps, proof, + production readiness, troubleshooting, and see-also links. +- References should be exhaustive for their stated surface. +- Troubleshooting should start from observable symptoms, not internal causes. +- Flag dense contracts or rare debugging detail that should move to reference or + support pages. + +## 5. Docs IA and findability review + +- Read `docs/docs.json` for nav-related changes. +- Verify topic pages remain on the main reader path and support/reference pages + belong under `Reference`. +- Verify generated references and redirect-only pages are not accidentally added + to visible nav. +- Confirm titles, headings, docs-list hints, anchors, and related links match + likely reader intent. +- For moved pages, require a keep/drop/move/destination matrix. + +## 6. Preservation review for rewrites + +- Identify the source material being replaced or split. +- Require destination evidence for every important claim, warning, example, + field, command, and troubleshooting fact. +- Treat dense source sections as needing line- or claim-level mapping. +- Verify dropped sections are obsolete, duplicated, unsupported, or moved. +- If using audit artifacts, confirm the artifact is a mapped audit with non-empty + `mappings[]`. + +## 7. Governance review + +Use `agent-and-contributing.md` for AGENTS/CONTRIBUTING/CODEOWNERS/labeler work. + +- Confirm root policy and scoped instructions do not conflict. +- Confirm commands and PR/review gates match current repo behavior. +- Confirm user-facing docs say "plugin/plugins" and do not expose internal + `extensions/` terminology except as paths. +- Confirm new channel/plugin/app/doc surfaces include labeler/GitHub label impact + when required. + +## 8. Validation notes + +Record what was checked and what remains: + +- docs-list +- MDX check +- link check +- i18n glossary check +- docs format/lint +- `git diff --check` +- generated-doc checks +- behavior tests or command probes + +If a validation command is not feasible, say why and name the residual risk. + +## 9. Output format + +1. Blocking issues 2. Non-blocking improvements -3. Validation notes (done vs pending) +3. Validation notes + +If no issues are found, say so clearly and still list residual validation gaps. diff --git a/skills/technical-documentation/references/tooling.md b/skills/technical-documentation/references/tooling.md index a3a8705..2d392e1 100644 --- a/skills/technical-documentation/references/tooling.md +++ b/skills/technical-documentation/references/tooling.md @@ -1,32 +1,49 @@ -# Documentation Tooling Guide - -Source: https://www.mintlify.com/blog/top-7-api-documentation-tools-of-2025 - -Use this file when deciding build/review expectations for doc platforms. - -## Tool-selection checkpoints - -- Existing stack lock-in: do not force migration for minor gains. -- API workflow depth: generated references, OpenAPI support, testability. -- Collaboration model: docs-as-code, review workflow, versioning. -- Runtime quality: search, navigation, and copy-ready code snippets. -- AI readiness: structured content, stable URLs, machine-friendly layout yet human readable. -- Human readiness: reading complexity, reading UX, navigation depth, minimize jargon. - -## Apply in brownfield mode - -- Prioritize compatibility with the current platform. -- Use available components and style conventions before introducing new patterns. -- Propose migration only when current constraints block critical outcomes. - -## Apply in evergreen mode - -- Favor platforms and templates that make routine updates low-friction. -- Standardize section templates to reduce drift. -- Capture ownership, update cadence, and stale-content detection rules. - -## Review implications - -- Check whether content uses platform primitives correctly (tabs, callouts, endpoint blocks). -- Flag docs that are technically correct but hard to scan in the chosen platform. -- Recommend platform-specific improvements only when they reduce cognitive load. +# OpenClaw Docs Tooling Guide + +Use this file when platform, routing, generated docs, or validation choices +matter. + +## OpenClaw docs stack + +- Public docs source lives under `docs/**`. +- Navigation and page grouping live in `docs/docs.json`. +- Use `pnpm docs:list` to discover indexed docs and docs-list routing hints. +- Treat filesystem paths, Mintlify routes, redirects, and published + `https://docs.openclaw.ai/...` URLs as separate maps. +- Generated references, redirect-only pages, and hidden support pages should not + be added to visible nav without an explicit reason. + +## Path and route checks + +- Resolve docs paths relative to the config or source that declares them. +- Verify `docs/docs.json` entries point to existing files or intentional routes. +- Verify moved docs keep addressability through redirects or stable related + links when needed. +- When reporting published docs, include the relevant full + `https://docs.openclaw.ai/...` URL. + +## Validation commands + +Use the narrowest commands that prove the touched surface: + +```bash +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 +``` + +Generated docs, plugin inventories, labeler changes, or scripts may require +their own inventory/generated checks. Behavior claims may require source-backed +tests or command probes beyond docs checks. + +## Platform-fit review + +- Prefer existing OpenClaw/Mintlify components and navigation patterns. +- Do not propose a docs-platform migration for ordinary content problems. +- Keep key facts in text, not image-only screenshots. +- Prefer stable anchors, descriptive headings, and structured tables only when + they reduce lookup effort.