changelog-generator

Overview of changelog-generator skill

What changelog-generator does

changelog-generator is an engineering release-management skill for turning Conventional Commit history into consistent, auditable release notes. It helps an AI agent parse commit subjects, infer semantic version bumps, render Keep a Changelog-style sections, and connect the result to CI or hotfix workflows instead of producing loose prose from a generic prompt.

Best-fit users and release scenarios

This changelog-generator skill is best for maintainers, release engineers, DevOps teams, and technical writers who need repeatable CHANGELOG.md entries from real git history. It fits release cuts, PR commit checks, semantic version planning, monorepo package releases, and emergency hotfix notes where traceability matters.

It is especially useful as changelog-generator for Technical Writing when writers need user-facing notes from developer commit messages while preserving evidence: commit range, version, breaking changes, security fixes, and migration notes.

What makes it different from a normal prompt

A normal “write release notes” prompt often loses structure or invents impact. This skill includes dedicated scripts and references: scripts/generate_changelog.py, scripts/commit_linter.py, scripts/version_bumper.py, plus guidance for changelog formatting, CI integration, monorepos, and hotfix procedures. That makes it more suitable for automated or semi-automated release workflows.

Adoption constraints to check first

The skill assumes commits are close to Conventional Commits, such as feat(auth): add OAuth2 integration or fix(api): resolve race condition. If your repository uses vague messages like updates, misc fixes, or squash commits without useful subjects, output quality will drop unless you provide extra context. Teams using non-semver release policies should treat the version-bump output as advisory.

How to Use changelog-generator skill

changelog-generator install and repository setup

For Claude-style local skills, copy the skill folder into your skill directory. The repository README shows examples such as:

cp -R engineering/changelog-generator ~/.claude/skills/changelog-generator

Adapt the source path to the actual cloned repository location. Also review these files before relying on the skill in production:

• SKILL.md for the agent-facing workflow
• README.md for quick-start commands
• references/changelog-formatting-guide.md for output rules
• references/ci-integration.md for CI examples
• references/monorepo-strategy.md if you release packages independently
• references/hotfix-procedures.md for urgent release classification

Inputs the skill needs for reliable output

For strong changelog-generator usage, provide a concrete release boundary and enough policy context. Useful inputs include:

• previous tag and target tag, such as v1.2.0..v1.3.0
• target version or current version if the skill should compute the bump
• raw commit subjects from git log --oneline if the agent cannot access git
• whether breaking changes require migration notes
• package scope for monorepos, such as payments or auth
• preferred output: markdown for CHANGELOG.md, JSON for CI, or a release announcement draft

Weak prompt: “Generate a changelog.”

Stronger prompt: “Use changelog-generator to create a Keep a Changelog entry for v1.4.0 from commits between v1.3.0 and HEAD. Group by Security, Added, Changed, Deprecated, Removed, Fixed. Flag breaking changes, infer the semver bump, and produce a concise markdown entry suitable for CHANGELOG.md.”

Practical command patterns

The included tools can be used directly or referenced by the agent during a release workflow.

Generate markdown from a tag range:

python3 scripts/generate_changelog.py \
  --from-tag v1.2.0 \
  --to-tag v1.3.0 \
  --next-version v1.3.0 \
  --format markdown

Lint commit subjects before merge:

python3 scripts/commit_linter.py \
  --from-ref origin/main \
  --to-ref HEAD \
  --strict \
  --format text

Use JSON output when CI needs machine-readable results, and use markdown when a human will review or prepend to CHANGELOG.md.

Workflow for better release notes

Start by linting commits, then infer the version bump, then generate the changelog entry, then edit for user impact. The most important editorial step is converting implementation-heavy messages into user-visible changes without hiding important technical risks.

For example, fix(db): resolve deadlock issues in concurrent transactions should become a user-facing note such as “Fixed database deadlocks that could interrupt concurrent account updates,” not “Changed transaction locking logic.”

changelog-generator skill FAQ

Is changelog-generator only for fully automated releases?

No. The skill works well in both automated and editorial workflows. CI can enforce commit format or generate draft notes, while humans can refine wording, add migration details, and approve the final release entry.

Can beginners use this changelog-generator guide?

Yes, if the repository already uses tags and reasonably structured commits. Beginners should start with assets/sample_git_log.txt, run the scripts locally, and compare the output with references/changelog-formatting-guide.md. The hardest part is usually not the tool; it is learning to write commit messages that contain enough scope and intent.

When should I not use this skill?

Avoid it as the primary source of truth when commits are misleading, heavily squashed, or disconnected from shipped behavior. It is also a poor fit for marketing launch notes that need positioning, screenshots, customer quotes, or campaign messaging. In those cases, use this skill for factual release inventory, then write a separate announcement.

How does it handle monorepos and scoped commits?

The monorepo guidance favors scoped Conventional Commits such as feat(payments): add Stripe webhook handler. That enables package-level filtering and ownership. If your scopes do not match package or directory names, package changelogs may be incomplete or noisy, so align commit scopes before depending on automation.

How to Improve changelog-generator skill

Improve changelog-generator inputs before generation

The fastest way to improve changelog-generator results is to improve the commit stream. Use clear types, meaningful scopes, and user-relevant subjects:

• Good: fix(security): patch SQL injection vulnerability in reports
• Good: feat(admin)!: redesign admin panel with role-based permissions
• Weak: fix stuff
• Weak: updates after review

For breaking changes, include ! in the commit subject and provide migration context in the prompt if it is not in the commit body.

Prevent common failure modes

Common issues include missing security items, over-reporting internal chores, incorrect semver bumps, and changelog bullets that describe code changes instead of product impact. Counter these by asking the agent to:

• exclude pure chore, style, or test commits unless they affect users
• call out security, deprecated, remove, and breaking commits explicitly
• separate “recommended version bump” from “release manager decision”
• include migration notes for breaking changes

Iterate after the first output

Treat the first changelog as a structured draft. Ask follow-up questions such as:

• “Which bullets are not user-visible and should be removed?”
• “Which breaking changes need migration notes?”
• “Rewrite the Fixed section for customer-facing clarity.”
• “Return JSON with commit hash, category, scope, and final bullet for audit review.”

This preserves traceability while improving readability.

Extend the skill for your release policy

Teams can improve the skill by adding organization-specific release rules: allowed commit types, required scopes, severity labels, package ownership, or changelog templates. If you publish from CI, expand references/ci-integration.md with your actual GitHub Actions or GitLab CI job. If hotfixes are frequent, customize references/hotfix-procedures.md with your approval path, rollback triggers, and SLA language.