documentation-automation_skill

Overview

This skill automates and maintains project documentation across CHANGELOG.md, README files, inline code comments, and cross-references. It proactively runs after feature work, bug fixes, API changes, or other significant code events to keep documentation accurate, discoverable, and consistent with conventional commit practices. It supports Rust doc comments, TypeScript JSDoc, and multi-level README organization.

How this skill works

The skill inspects recent git changes, detects new or modified public APIs, and checks for missing or outdated documentation. It generates conventional-commit-formatted entries under ## [Unreleased] in CHANGELOG.md, adds or updates relevant README sections, produces module/function-level inline docs (Rust /// and //! or TypeScript /** */), and repairs or adds cross-references and file links. It flags breaking changes, security fixes, and items that need manual review.

When to use it

• After implementing a new feature or user-facing API
• After fixing a bug that changes behavior or public contracts
• When making breaking changes or renaming public symbols
• Before committing significant work or opening a PR
• After completing a user story, refactor, or release prep

Best practices

• Run the skill proactively for any public API change to avoid undocumented regressions
• Use conventional commit prefixes (feat/fix/docs/refactor/test/chore) to categorize changelog entries
• Include file paths and brief migration notes for breaking changes
• Document all public modules, structs/enums, and exported functions with examples and safety notes
• Update the appropriate README in the subsystem hierarchy rather than creating duplicate sections

Example use cases

• Add a safety watchdog: update CHANGELOG Added, add command watchdog section to bvr/firmware/README.md, and add Rust module and function docs with examples
• Rename a public function: add a BREAKING note in CHANGELOG, provide a migration snippet in README and #[deprecated] inline docs
• Fix CAN frame parsing: add a Fixed entry referencing the file and line ranges, update inline comments and tests, and verify examples compile
• New TypeScript hook: generate JSDoc for the exported hook, add usage example to the console README, and ensure links resolve