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: