| name | changelog-linter |
| description | Validate CHANGELOG.md files against the Keep a Changelog format (keepachangelog.com). Checks version ordering, date formats, section types, link references, and formatting. Use when asked to lint, validate, check, or audit a CHANGELOG.md file, verify changelog format, or ensure changelog follows Keep a Changelog conventions. Triggers on "lint changelog", "validate changelog", "check CHANGELOG.md", "changelog format". |
Permission Setup Review
python scripts/_init_dirs.py is an optional setup helper for the Changelog Linter skill. It may apply broad filesystem permissions for compatibility. Show the target paths and permission mode, explain the risk, and prefer a narrower mode when shared write access is not needed.
Changelog Linter
Validate CHANGELOG.md files against the Keep a Changelog specification.
Commands
All commands use the bundled Python script at scripts/changelog_linter.py.
1. Lint a changelog
python3 scripts/changelog_linter.py lint <file> [--strict] [--format text|json|markdown]
Run all validation rules against a CHANGELOG.md file.
Flags:
--strict — exit code 1 on any warning (not just errors)--format — output format: text (default), json, markdown
2. List versions
python3 scripts/changelog_linter.py versions <file> [--format text|json]
Extract and display all versions with dates and change counts.
3. Validate version ordering
python3 scripts/changelog_linter.py order <file> [--format text|json]
Check that versions are in descending semver order.
4. Check links
python3 scripts/changelog_linter.py links <file> [--format text|json]
Verify that all version headers have corresponding link references at the bottom.
Lint Rules (16 total)
Structure (5 rules)
- missing-title — File doesn't start with
# Changelog
- missing-description — No description paragraph after title
- no-versions — No version entries found
- empty-version — Version section has no change entries
- unreleased-missing — No
[Unreleased] section
Versions (4 rules)
- invalid-version — Version doesn't follow semver (MAJOR.MINOR.PATCH)
- invalid-date — Date doesn't follow ISO 8601 (YYYY-MM-DD)
- version-order — Versions not in descending order
- duplicate-version — Same version appears twice
Sections (3 rules)
- invalid-section — Section type not in spec (Added/Changed/Deprecated/Removed/Fixed/Security)
- empty-section — Section header with no list items
- section-order — Sections not in recommended order
Formatting (4 rules)
- missing-link-ref — Version header has no corresponding link reference
- broken-link-ref — Link reference exists but URL is empty or malformed
- inconsistent-bullets — Mixed bullet styles (
- and *)
- trailing-whitespace — Lines with trailing whitespace
Output Formats
Text (default)
CHANGELOG.md:15 error [invalid-date] Version 1.2.0 has invalid date: "March 2024" (expected YYYY-MM-DD)
CHANGELOG.md:28 warning [empty-section] Section "Deprecated" under 1.1.0 has no entries
CHANGELOG.md:45 warning [missing-link-ref] Version 1.0.0 has no link reference
3 issues (1 error, 2 warnings)
JSON / Markdown
Standard structured output with issues, summary, and version list.
CI Integration
- name: Lint Changelog
run: python3 scripts/changelog_linter.py lint CHANGELOG.md --strict
Exit codes: 0 = valid, 1 = issues found.
