doc-updater_skill

Overview

This skill detects code changes that require documentation updates and proposes or applies those updates automatically. It prevents documentation drift by scanning diffs for API, CLI, configuration, environment variable, and feature changes. Use it during pre-PR checks, on explicit request, or as part of CI quality gates. It can suggest edits and, with approval, stage document changes for commit.

How this skill works

The skill analyzes git diffs and code patterns to identify changes that impact docs (new CLI flags, API endpoints, config keys, environment vars, breaking changes, etc.). It locates likely documentation files (README, docs/, API.md, CHANGELOG.md) and generates concrete update suggestions or diffs. After user approval, it can edit target files, stage changes, and produce a Documentation Impact Report summarizing actions. It also flags errors like missing docs or write permission issues.

When to use it

• Before creating a pull request or during a pre-PR checklist
• When code changes may affect user-facing behavior (APIs, CLI, config)
• When adding or changing environment variables or configuration options
• On explicit request to audit recent commits for doc impact
• As part of CI/CD documentation quality gates

Best practices

• Run the checker alongside code changes to avoid doc debt
• Include concrete examples and usage snippets when updating docs
• Record notable changes in CHANGELOG for visibility
• Ask for human approval before committing doc edits to preserve tone and accuracy
• Link code locations to documentation sections to ease review

Example use cases

• Detect a new CLI flag and add a short entry in README and --help output
• Find an added environment variable and add setup instructions to docs/setup.md
• Identify an added API endpoint and update API.md with path, parameters, and example responses
• Spot a breaking change and prepare a migration note plus CHANGELOG entry
• Run automatically in CI to require documentation updates before merge