docs-sync

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.

Role	Content	Updated when...
features	User-facing feature descriptions, shortcuts, status	New feature added, feature behavior changes
architecture	App structure, data flow, patterns, diagrams	New components, changed patterns, refactors
conventions	Dev setup, coding rules, build commands	Build process changes, new conventions adopted
changelog	Version-based change history	Any significant change (follows format: keep-a-changelog, conventional, custom)
readme	Project overview, install instructions, quick start	Major features, install process changes
api	API reference, endpoints, function signatures	Public API changes
guide	Tutorials, how-tos, walkthroughs	Workflow changes, new capabilities
custom	Anything else — describe in the description field	Based on your description