Docs Sync

Prerequisites

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

Keep project documentation current with code changes. Three modes:

1. 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. 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

1. 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

1. 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.

CODEBLOCK0

Doc Roles

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

Role	Content	Updated when...
INLINECODE15	User-facing feature descriptions, shortcuts, status	New feature added, feature behavior changes
INLINECODE16

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
INLINECODE24, INLINECODE25	INLINECODE26
INLINECODE27, *design*, INLINECODE29

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. 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

1. 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)

1. 3. Read current docs — read each affected doc file to understand current content,

structure, and style

1. 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

1. 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. 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. 1. Check sidebars.js or INLINECODE68
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. 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. 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

1. 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