什么是 Docs Sync？

Docs Sync 是一款专门的自动化实用程序，旨在弥合源代码与技术文档之间的鸿沟。通过分析 git diff 和 Pull Request 元数据，这款 Openclaw Skills 工具可以精确确定代码更改后文档的哪些部分需要关注。从更新功能列表和架构图到管理静态网站生成器中的复杂导航结构，它都能处理。

无论您使用的是 MkDocs、Docusaurus 还是 VitePress，Docs Sync 都能确保您的文档始终是真实可靠的来源。它的工作原理是将特定的代码修改映射到文档角色，从而进行精准更新，在无需人工干预的情况下保持项目文档现有的风格和语调。

下载入口:https://github.com/openclaw/skills/tree/main/skills/chriscox/docs-sync

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Docs Sync 应用场景

• 在合并 Pull Request 后立即同步文档，确保用户获得最新信息。
• 使用 Keep a Changelog 等标准格式自动更新项目的 CHANGELOG.md。
• 在添加或移动新文件时，管理文档网站的侧边栏和导航配置。
• 审计文档以查找尽管底层代码已发生重大更改但尚未更新的陈旧文件。

1. 该技能执行仓库发现以定位根目录，并检测 MkDocs 或 Docusaurus 等文档框架。
2. 它通过分析 GitHub PR 文件或 git diff 范围来识别最近的更改，以了解更新范围。
3. 根据文件模式或配置，将更改映射到特定的文档角色，如功能、架构或规范。
4. 读取当前的文档文件，分析现有的风格、结构和内容密度。
5. 起草精准更新方案，仅修改文档中必要的章节，同时保留图表和格式。
6. 更新将直接应用于新分支、提交审阅或记录为 GitHub issue。

Docs Sync 配置指南

在使用前，请确保已安装 git 和 GitHub CLI 并完成身份验证。

# 使用 GitHub CLI 进行身份验证
gh auth login

# 该技能会自动发现您的文档，但您也可以添加配置文件
touch .docs-sync.yml

示例 .docs-sync.yml 配置：

docs:
  - path: docs/architecture.md
    role: architecture
site:
  engine: mkdocs
  auto_nav: true

Docs Sync 数据架构与分类体系

Docs Sync 通过为文件分配角色来组织文档，这些角色可以在配置文件中定义，也可以由 Openclaw Skills 引擎自动检测。

name: docs-sync
description: >
  Keep project documentation in sync with code changes. Identifies which docs need
  updating after a PR merges or code changes, drafts the updates, and manages doc site
  structure (mkdocs, docusaurus, vitepress). Use when: (1) a PR just merged and docs
  may need updating, (2) the user says "update the docs" or "sync docs", (3) a new
  doc was created and needs to be added to site navigation, (4) the user wants to audit
  which docs are stale. NOT for: writing docs from scratch for a new project (just write
  them), generating API reference docs from code comments (use typedoc/jazzy/etc.), or
  content that isn't developer documentation.

Docs Sync

Prerequisites

• git
• gh (GitHub CLI, authenticated via gh auth login)

Keep project documentation current with code changes. Three modes:

1. Content sync — update doc content after code changes
2. Site management — maintain doc site structure and navigation
3. Docs audit — identify stale docs that need attention

Repo Discovery

Before doing anything, discover the project's documentation setup:

1. Run git rev-parse --show-toplevel to find the repo root
2. Check for .docs-sync.yml at the repo root — if it exists, read it and use its values for all paths, roles, and site config
3. If no config file, auto-discover:
   • Doc site engine: look for mkdocs.yml, docusaurus.config.js, .vitepress/config.*
   • Doc directory: look for docs/, documentation/, wiki/
   • Known doc files: scan for common patterns (see Doc Roles below)
   • Convention files: CLAUDE.md, AGENTS.md, CONTRIBUTING.md
4. Run gh repo view --json name,owner to confirm the repo

Config File: .docs-sync.yml

Optional config file at repo root. All fields are optional — auto-discovery fills gaps. See docs-sync.yml in the skill directory for a starter.

# Map your doc files to roles so the skill knows what content belongs where
docs:
  - path: docs/features.md
    role: features

  - path: docs/architecture.md
    role: architecture

  - path: CHANGELOG.md
    role: changelog
    format: keep-a-changelog

  - path: CLAUDE.md
    role: conventions

  - path: README.md
    role: readme

# Doc site configuration (optional)
site:
  engine: mkdocs               # mkdocs | docusaurus | vitepress
  config: mkdocs.yml           # path to site config
  auto_nav: true               # update navigation when docs change

Doc Roles

Roles tell the skill what kind of content a file contains, so it knows how to update it.

Auto-Detection (No Config)

Without a config file, the skill detects roles by filename:

Files not matching any pattern are skipped unless listed in the config.

Workflow: Content Sync

When the user says docs need updating (or after a PR merge):

1. Identify what changed — determine the scope of code changes:

   • If a PR number is provided: gh pr view --json files,title,body
   • If a commit range: git diff --name-only
   • If unspecified: git diff --name-only HEAD~1 (last commit)
   • Read the actual diffs for changed files to understand what changed, not just which files

2. Map changes to affected docs — for each changed file, determine which doc roles are affected:

   • New UI component → features, architecture
   • Changed data model → architecture
   • New keyboard shortcut → features
   • Changed build command → conventions
   • Bug fix → changelog (if tracking fixes)
   • New API endpoint → api, readme (if it's a headline feature)

3. Read current docs — read each affected doc file to understand current content, structure, and style

4. Draft updates — write the specific changes needed for each doc:

   • Match the existing writing style and structure
   • Add to existing sections rather than creating new ones (unless clearly needed)
   • For changelog: add entry under the appropriate version/section
   • For features: add or update the feature entry, not rewrite the whole file
   • For architecture: update the affected section, preserve diagrams

5. Apply or propose — based on user preference:

   • Direct apply: edit the files, commit to a branch, report what changed
   • Review first: show the proposed changes and ask for approval
   • Issue: create a GitHub issue listing which docs need updating and why

Quality Checklist

Before committing doc updates:

• Each update matches the existing style of that doc file
• No content was removed that's still accurate
• New entries are placed in the correct section (not appended randomly)
• Cross-references between docs are consistent
• Changelog entries follow the file's existing format
• Feature descriptions are user-facing (not implementation details)

Workflow: Site Management

When docs are added, moved, or deleted — keep the site structure current.

mkdocs

1. Read mkdocs.yml and parse the nav: section
2. For new docs: determine the correct nav section based on the doc's role and path
3. Add the entry to nav: in the right position
4. For moved docs: update the nav path
5. For deleted docs: remove the nav entry

docusaurus

1. Check sidebars.js or sidebars.ts
2. For auto-generated sidebars: ensure the doc has correct frontmatter (sidebar_position, sidebar_label)
3. For manual sidebars: add/update/remove entries

vitepress

1. Check .vitepress/config.* for sidebar configuration
2. Add/update/remove sidebar entries as needed

General Rules

• Preserve existing organization — don't reorganize the nav, just maintain it
• Follow naming patterns — if existing entries use Title Case, match that
• Respect ordering — add new entries at logical positions, not always at the end
• Update indexes — if a section has an index.md with a list, update it too

Workflow: Docs Audit

When the user asks "which docs are stale?" or "audit my docs":

1. Discover all doc files (see Repo Discovery)
2. For each doc file, check git log -1 --format="%ar" -- for last modified
3. Compare with recent code changes in related areas
4. Report docs that may be stale:
   • Doc hasn't been updated in a long time but related code changed recently
   • Doc references files/functions/patterns that no longer exist
   • Doc describes behavior that the code no longer implements
5. Suggest specific updates needed for each stale doc

Important Rules

• Match existing style — read the doc before updating it. Don't impose a new format.
• Be surgical — update the specific section that changed, don't rewrite entire docs
• Features are user-facing — don't write "Added SyncSettingsView.swift", write "Added sync settings with enable/disable toggle, status indicator, and Sync Now button"
• Don't remove accurate content — only remove content that's now wrong
• Commit to a branch — never push directly to main
• One concern per update — if a PR changed both features and architecture, update both docs but keep the changes focused on what actually changed
• Respect repo conventions — if the repo has CLAUDE.md or CONTRIBUTING.md, read and follow its branch naming, commit message, and PR conventions