Skill: chriscox/docs-sync (version 1.0.3)

--- 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. ```yaml # 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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)