docs-sync_skill

Overview

This skill analyzes the main branch implementation and configuration to find missing, incorrect, or outdated English documentation under docs/. It compares code and config to the docs structure, produces a prioritized Docs Sync Report, and asks for approval before applying changes. It never edits translated docs under docs/ja, docs/ko, or docs/zh.

How this skill works

The skill inventories user-facing surface area (public exports, CLI, config options, env vars, defaults) from the selected branch or the diff vs main. It walks existing docs/pages, maps code features to the docs structure, and flags missing, incorrect, or misgrouped content with file-level evidence. After producing a report with suggested locations and edits, it requests approval before making English-only updates and verifies the docs build.

When to use it

• You need an audit of docs coverage vs current implementation on main or a feature branch.
• Preparing a release and want to ensure docs reflect new config options or CLI changes.
• Onboarding new contributors and ensuring docs match public APIs and examples.
• Proposing structural changes to improve docs discoverability and navigation.
• Validating that generated reference docs match docstrings in source code.

Best practices

• Analyze the current branch first; if not on main, scope work to the diff vs main.
• Capture evidence for each gap: code path, symbol, or config file and line where applicable.
• Propose doc edits tied to specific pages and insertion points, not vague suggestions.
• Prefer updating source docstrings for API/reference fixes so generated docs remain correct.
• Always ask for user approval before modifying English docs; never touch translated docs.

Example use cases

• Audit docs to find undocumented configuration flags introduced in a recent PR.
• Sync CLI help output and examples with the docs when command options changed.
• Detect and fix mismatched default values between code and docs prior to release.
• Suggest reorganizing docs/ref sections to improve discoverability of agent APIs.
• Produce a change-ready patch with mkdocs.yml updates and a build verification step.