docs-sync

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.

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

Auto-Detection (No Config)

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

Pattern	Inferred role
*feature*, *capability*	features
*architect*, *design*, *structure*	architecture
CLAUDE.md, AGENTS.md, CONTRIBUTING.md, *convention*	conventions
CHANGELOG*, CHANGES*, HISTORY*	changelog
README*	readme
*api*, *reference*, *endpoint*	api
*guide*, *tutorial*, *howto*	guide

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 <N> --json files,title,body
   • If a commit range: git diff --name-only <range>
   • 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" -- <path> 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