Agent skill

changelog-rfc-29

RFC-29 compliant changelog management with Common Changelog format and Unreleased section extension. Validates changelog on commits, generates from git history, and ensures all merged PRs are documented. Use when setting up changelog workflows or retrofitting existing repositories.

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/changelog-rfc-29

Metadata

Additional technical details for this skill

tags: changelog rfc-29 documentation versioning
version: 1.1.0
targeting: { "include": [ { "repo": "bitsoex/ai-code-instructions" } ] }

SKILL.md

Changelog (RFC-29)

Enforce and validate changelogs following the Common Changelog specification with an Unreleased section extension for in-progress work.

When to Use This Skill

Setting up changelog workflow in a new repository
Retrofitting changelog from git history
Validating changelog format in pre-commit/pre-push hooks
Ensuring PR coverage in changelog during CI
Understanding Common Changelog format requirements

Skill Contents

Sections

When to Use This Skill (L25-L32)
Quick Start (L73-L106)
Format Specification (L107-L164)
Validation Rules (L165-L194)
Scripts (L195-L282)
Migration (L283-L315)
Integration (L316-L373)
Exclusions (L374-L399)
Related Skills (L400-L407)
Troubleshooting (L408-L445)

Available Resources

📚 references/ - Detailed documentation

common changelog spec
hallmark feature analysis
migration guide
unreleased extension

🔧 scripts/ - Automation scripts

check updated
constants
coverage
import releases
migrate
parse
retrofit
semver
validate

📦 assets/ - Templates and resources

changelog template
exclusion patterns

Quick Start

Creating a new CHANGELOG.md

Copy the template and customize:

bash

cp global/skills/changelog-rfc-29/assets/changelog-template.md CHANGELOG.md

Validating an existing changelog

bash

pnpm run skills:changelog
# or
node .scripts/skills-cli.ts changelog validate

Checking PR coverage

bash

pnpm run skills:changelog:coverage
# or
node .scripts/skills-cli.ts changelog coverage

Retrofitting from git history

bash

pnpm run skills:changelog:retrofit
# or
node .scripts/skills-cli.ts changelog retrofit

Format Specification

File Structure

markdown

# Changelog

> Optional description or note about the changelog format.

## [Unreleased]

### Added

- Add new feature ([#123](https://github.com/org/repo/pull/123))

## [2.0.0] - 2026-01-19

_Optional notice about this release._

### Changed

- **Breaking:** Major refactor ([#100](https://github.com/org/repo/pull/100))

### Added

- Add feature X ([#95](https://github.com/org/repo/pull/95))

### Fixed

- Fix bug Y ([#90](https://github.com/org/repo/pull/90))

[Unreleased]: https://github.com/org/repo/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/org/repo/releases/tag/v2.0.0

Category Order

Categories MUST appear in this order (only include those with changes):

Changed - modifications to existing functionality
Added - new features
Removed - removed features
Fixed - bug fixes

Change Format

Each change must:

Start with imperative verb (Add, Fix, Remove, Update, etc.)
Include at least one reference (PR number or commit hash)
Use **Breaking:** prefix for breaking changes

markdown

- Add user authentication ([#45](https://github.com/org/repo/pull/45))
- **Breaking:** Remove deprecated API ([#50](https://github.com/org/repo/pull/50))
- Fix memory leak in worker pool ([`abc1234`](https://github.com/org/repo/commit/abc1234))

Validation Rules

Format Validation

Rule	Description
File exists	CHANGELOG.md must exist
Header	Must start with `# Changelog`
Version format	Semver without 'v' prefix (e.g., `2.0.0`)
Date format	ISO 8601 (YYYY-MM-DD)
Category names	Only: Changed, Added, Removed, Fixed
Category order	Changed > Added > Removed > Fixed
References	Each change must have at least one

Pre-commit Check

When committing, the changelog check:

Gets list of staged files
Filters out excluded paths (tests, config, generated files)
If significant files are staged, requires CHANGELOG.md to also be staged

Coverage Validation

Ensures every merged PR is documented:

Extracts PR numbers from git history
Extracts PR numbers from CHANGELOG.md
Reports any PRs missing from changelog

Scripts

parse.js

Parse CHANGELOG.md into structured data:

javascript

import { parseChangelog, extractReferences, parseVersion } from './scripts/parse.ts';

const content = fs.readFileSync('CHANGELOG.md', 'utf-8');
const parsed = parseChangelog(content);

// parsed = {
//   title: 'Changelog',
//   releases: [
//     { version: 'Unreleased', date: null, groups: [...] },
//     { version: '2.0.0', date: '2026-01-19', notice: '...', groups: [...] }
//   ]
// }

validate.js

Validate changelog format:

javascript

import { validateChangelog } from './scripts/validate.ts';

const result = await validateChangelog('/path/to/repo');
// result = { passed: true/false, errors: [], warnings: [] }

check-updated.js

Pre-commit hook integration:

javascript

import { checkChangelogUpdated } from './scripts/check-updated.ts';

const result = await checkChangelogUpdated('/path/to/repo');
// result = { passed: true/false, message: '...', errors: [] }

retrofit.js

Generate changelog from git history:

javascript

import { retrofitChangelog } from './scripts/retrofit.ts';

const result = await retrofitChangelog({
  rootDir: '/path/to/repo',
  version: '2.0.0',
  date: '2026-01-19',
  repoUrl: 'https://github.com/org/repo'
});
// result = { markdown: '...', prCount: 106, categorized: {...} }

coverage.js

Validate PR coverage:

javascript

import { validateCoverage } from './scripts/coverage.ts';

const result = await validateCoverage('/path/to/repo');
// result = { passed: true/false, missingPRs: [], extraPRs: [] }

migrate.js

Convert existing changelogs to Common Changelog format:

bash

node global/skills/changelog-rfc-29/scripts/migrate.ts --input CHANGELOG.md --dry-run
node global/skills/changelog-rfc-29/scripts/migrate.ts --input CHANGELOG.md --output CHANGELOG.new.md

import-releases.js

Import GitHub releases as changelog entries:

bash

node global/skills/changelog-rfc-29/scripts/import-releases.ts --repo bitsoex/my-repo --dry-run
node global/skills/changelog-rfc-29/scripts/import-releases.ts --repo bitsoex/my-repo --output CHANGELOG.md

Migration

For repositories with existing changelogs or release history, see the Migration Guide.

Migration Scenarios

Current State	Approach
Keep a Changelog format	Use `migrate.js` to convert
GitHub releases	Use `import-releases.js` to import
Git tags only	Use `retrofit.js` to generate
No versioning	Copy template, start fresh

Converting from Keep a Changelog

bash

# Preview changes
node global/skills/changelog-rfc-29/scripts/migrate.ts --input CHANGELOG.md --dry-run

# Convert in place
node global/skills/changelog-rfc-29/scripts/migrate.ts --input CHANGELOG.md

Importing GitHub Releases

bash

# Preview import
node global/skills/changelog-rfc-29/scripts/import-releases.ts --repo bitsoex/my-repo --dry-run

# Generate changelog from releases
node global/skills/changelog-rfc-29/scripts/import-releases.ts --repo bitsoex/my-repo --output CHANGELOG.md

Integration

Pre-commit Hook

Add to .scripts/lib/validation.ts:

javascript

{
  name: 'Changelog updated',
  command: null,
  customCheck: 'checkChangelogUpdated',
  scope: 'pre-commit',
  blocking: true,
  required: true
}

Pre-push Hook

Add to .scripts/lib/validation.ts:

javascript

{
  name: 'Changelog format',
  command: ['node', '.scripts/skills-cli.ts', 'changelog', 'validate'],
  scope: 'pre-push',
  blocking: true,
  required: true
}

CI Workflow

Add to .github/workflows/ci.yaml:

yaml

- name: Validate Changelog Format
  if: github.event_name == 'pull_request'
  run: pnpm run skills:changelog

- name: Validate PR Coverage
  if: github.event_name == 'pull_request'
  run: pnpm run skills:changelog:coverage

Package.json Scripts

json

{
  "scripts": {
    "skills:changelog": "node .scripts/skills-cli.ts changelog validate",
    "skills:changelog:check": "node .scripts/skills-cli.ts changelog check-updated",
    "skills:changelog:coverage": "node .scripts/skills-cli.ts changelog coverage",
    "skills:changelog:retrofit": "node .scripts/skills-cli.ts changelog retrofit"
  }
}

Exclusions

Files matching these patterns do NOT require changelog updates.

See assets/exclusion-patterns.json for the full list.

Infrastructure

.github/ - CI/CD workflows
.gitignore, .nvmrc - config files
pnpm-lock.yaml - lock files

Tests

tests/ - test files only

Generated Content

.tmp/, coverage/, output/ - build outputs
.claude/skills/ - distributed content

Configuration

vitest.config.js, eslint.config.js - tooling config
.coderabbit.yaml, .doclinterrc.yml - linter config

Related Skills

Skill	Purpose
quality-checks	Orchestrates quality checks including changelog
git-hooks	Hook infrastructure for pre-commit/pre-push
pr-workflow	PR creation and management

Troubleshooting

"CHANGELOG.md must be updated"

Your commit includes significant files but CHANGELOG.md is not staged.

Fix: Add an entry to the [Unreleased] section:

markdown

## [Unreleased]

### Added

- Describe your change ([#YOUR_PR](https://github.com/org/repo/pull/YOUR_PR))

"Category X is out of order"

Categories must appear in order: Changed > Added > Removed > Fixed.

Fix: Reorder your categories to match the expected order.

"Change has no reference"

Every change must reference a PR or commit.

Fix: Add a reference in parentheses:

markdown

- Your change description ([#123](https://github.com/org/repo/pull/123))

"Invalid version format"

Version must be valid semver without 'v' prefix.

Good: ## [2.0.0] - 2026-01-19 Bad: ## [v2.0.0] - 2026-01-19

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/data/changelog-rfc-29
License: MIT License

Featured Tools

Join Our Newsletter

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

Metadata

SKILL.md

Changelog (RFC-29)

When to Use This Skill

Skill Contents

Sections

Available Resources

Quick Start

Creating a new CHANGELOG.md

Validating an existing changelog

Checking PR coverage

Retrofitting from git history

Format Specification

File Structure

Category Order

Change Format

Validation Rules

Format Validation

Pre-commit Check

Coverage Validation

Scripts

parse.js

validate.js

check-updated.js

retrofit.js

coverage.js

migrate.js

import-releases.js

Migration

Migration Scenarios

Converting from Keep a Changelog

Importing GitHub Releases

Integration

Pre-commit Hook

Pre-push Hook

CI Workflow

Package.json Scripts

Exclusions

Infrastructure

Tests

Generated Content

Configuration

Related Skills

Troubleshooting

"CHANGELOG.md must be updated"

"Category X is out of order"

"Change has no reference"

"Invalid version format"

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state