documentation-updates
Use after modifying library skills, library commands, or agents to ensure CHANGELOG, README, and docs are updated
When & Why to Use This Skill
This Claude skill automates the essential task of maintaining project documentation, ensuring that CHANGELOGs, README files, and technical documentation stay perfectly synchronized with code changes. It streamlines the developer workflow by enforcing documentation standards, updating file counts, and verifying link integrity after modifications to library skills, commands, or agents.
Use Cases
- Automatically updating the CHANGELOG with 'Added', 'Changed', or 'Removed' entries after modifying library components to maintain a clear version history.
- Synchronizing the README.md file by updating skill counts and table rows to reflect the current state of the repository.
- Triggering documentation generators after code changes to ensure external-facing docs remain fresh and accurate.
- Performing a pre-PR verification check to ensure all documentation invariants are met and link references are correctly formatted.
| name | documentation-updates |
|---|---|
| description | "Use after modifying library skills, library commands, or agents to ensure CHANGELOG, README, and docs are updated" |
Documentation Updates
Identify: What library content changed? Scope: library skills (`skills/`), commands (`commands/`), agents (`agents/`). Exclude: Repo skills (`.claude/skills/`) are internal tooling, no external docs needed.Invariant Principles
- Library changes require documentation trail - Every modification to installed content must be traceable through CHANGELOG
- Counts must match reality - README totals reflect actual files, never stale
- Generated docs stay fresh - Run generator after any library content change
- Repo skills are invisible - Internal tooling never touches external docs
Required Updates Matrix
| Change | CHANGELOG | README | Docs Generator |
|---|---|---|---|
| Add library skill | "Added" section | count++, add table row, add link ref | Run |
| Modify library skill | "Changed" section | Only if description changed | Run |
| Remove library skill | "Removed" section | count--, remove row/link | Run |
| Add/modify command | Appropriate section | Update if count/description affected | Run |
Verification Checklist
Before PR completion, evidence required for each:- CHANGELOG.md has entry under
## [Unreleased] - README.md counts match
ls skills/*/SKILL.md | wc -landls commands/*.md | wc -l - New items have table rows AND link references
-
python3 scripts/generate_docs.pyexecuted - Pre-commit hooks committed generated files
CHANGELOG Entry Format
## [Unreleased]
### Added
- **skill-name skill** - one-line description
- Notable feature bullet
### Changed
- **skill-name skill** - what changed and why
### Removed
- **skill-name skill** - removal rationale
README Link Reference Pattern
[skill-name]: https://axiomantic.github.io/spellbook/latest/skills/skill-name/