docs-sync_skill

Overview

This skill audits the repository's main-branch implementation and configuration to find missing, incorrect, or outdated English documentation under docs/src/content/docs/**. It compares code and config against the docs, produces a prioritized Docs Sync Report with evidence and proposed edits, and asks for approval before making any changes. It never touches translated docs (ja, ko, zh) or the docs/src/content/docs/openai directory.

How this skill works

The skill builds a feature inventory from the selected scope (full main branch or diff vs main) by scanning public exports, config options, env vars, CLI commands, and runtime behavior. It performs a doc-first pass across docs/src/content/docs, then a code-first pass mapping uncovered features to appropriate pages. Findings are compiled into a structured Docs Sync Report with evidence, suggested locations, and concise edit summaries. If you approve, the skill applies edits only to English docs and verifies snippet builds before handoff.

When to use it

• Audit documentation coverage after a release or major feature merge to main
• Sync docs with in-flight branch changes by analyzing diffs vs main
• Identify and fix incorrect defaults, names, or behaviors documented in docs
• Propose structural documentation changes to improve discoverability
• Prepare a focused list of doc edits before opening a documentation PR

Best practices

• Confirm analysis scope (current branch vs main) before starting
• Treat source code as the source of truth; cite file paths and symbols as evidence
• Limit edits to English docs under docs/src/content/docs/** and exclude openai and translated folders
• Place example code under examples/docs/<doc-filename>/ to mirror existing patterns
• Run pnpm -F docs-code build-check to validate doc snippet builds before committing

Example use cases

• A new TypeScript package export was added but lacks a docs page — produce a report and suggested page placement
• Configuration option names or defaults changed in main — list outdated doc lines and proposed fixes
• A feature was added on a feature branch — provide a diff-focused doc checklist to sync only relevant pages
• Detect overloaded pages that should be split and propose a new docs structure with rationale
• Validate that environment variables and CLI flags referenced in docs match the codebase