dev.document_skill

Overview

This skill documents changes made to a codebase by updating all relevant documentation files. It ensures documentation stays synchronized with code and captures rationale, usage, and migration notes. The result is clearer context for reviewers and future maintainers.

How this skill works

The skill scans the project for common documentation files (README.md, DESIGN.md, CLAUDE.md, AGENTS.md, NEXT_STEPS.md) and updates them with summaries of the changes you performed. It generates concise change notes, updates usage examples or API snippets if required, and inserts migration or rollout instructions. It also flags missing documentation files and suggests targeted edits to keep docs complete and consistent.

When to use it

• After implementing feature changes or bug fixes
• When refactoring code or changing public APIs
• Prior to opening a pull request or requesting a review
• When preparing a release or publishing packages
• When onboarding new contributors or updating design decisions

Best practices

• Write concise, action-oriented change summaries that explain why, not just what
• Update README.md with new installation, usage, and API highlights when interfaces change
• Record design trade-offs and alternatives in DESIGN.md for future reference
• Keep CLAUDE.md and AGENTS.md aligned with agent behavior and configuration changes
• Use NEXT_STEPS.md to capture follow-up tasks, migration steps, and rollout considerations

Example use cases

• You renamed a public function: update README examples, note migration steps, and add a short rationale in DESIGN.md.
• You refactored internal architecture: document the new approach in DESIGN.md and list follow-up tasks in NEXT_STEPS.md.
• You added an automated agent or bot: update AGENTS.md with configuration, capabilities, and safety notes.
• You changed contributor or legal process: add or edit CLAUDE.md to reflect updated CLA or contribution steps.
• You prepared a release: consolidate user-facing changes in README.md and list post-release monitoring actions in NEXT_STEPS.md.