documentation-updates

axiomantic/documentation-updates

Writing

About

SKILL.md

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 -l and ls commands/*.md | wc -l
New items have table rows AND link references
python3 scripts/generate_docs.py executed
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/

Library content (`skills/`, `commands/`, `agents/`) triggers this skill. Repo content (`.claude/skills/`) does NOT.