Changelog Writer

Changelog Writer

The definitive changelog and release notes skill. Transforms raw git history, commit messages, PR descriptions, and code diffs into polished, production-ready changelogs and release notes. Produces up to five output formats simultaneously: developer-facing CHANGELOG.md, human-facing GitHub release notes, internal Slack summary, customer-facing email/newsletter, and package registry release notes. Every output is ready to paste — zero editing required.

---

Workflow

Follow these phases in order. Do not skip phases. Do not produce output until Phase 5.

---

Phase 1 — Acquire Changes

Determine input type and acquire all material needed to generate the changelog.

| Input Type | Action | |---|---| | No input provided | Run git tag --sort=-v:refname to find the latest tag, then git log ..HEAD --oneline --no-merges to get unreleased commits. If no tags exist, use git log --oneline --no-merges -50 and ask the user for the version range. | | User says "generate changelog" / "what changed" with no specifics | Auto-detect: find latest two tags with git tag --sort=-v:refname, run git log .. --oneline --no-merges. If HEAD is ahead of the latest tag, use ..HEAD instead. | | User specifies version range (e.g., "v1.2.0 to v1.3.0") | Run git log v1.2.0..v1.3.0 --oneline --no-merges. | | Pasted git log | Parse directly. Detect conventional commit format automatically. | | PR titles / descriptions | Parse each PR as a change entry. Use PR labels for categorization if available. | | Diff or file list | Analyze the diff to understand what changed. Summarize by functional area. | | Free-form description | Parse natural language into structured change entries. | | Existing messy changelog | Parse, validate, clean up, and reformat to Keep a Changelog standard. | | Single commit message | Expand into a full, context-rich release note. | | GitHub PR URL or number | Use gh pr view --json title,body,labels,mergedAt,files to fetch PR details. Use gh pr diff for the code diff. | | Monorepo with path prefix | Filter commits by path: git log --oneline --no-merges -- . See Phase 1b. |

Git integration commands to run automatically (when in a git repository):

# Detect latest tags
git tag --sort=-v:refname | head -5

# Get repo remote URL (for comparison links)
git remote get-url origin 2>/dev/null

# Get current branch
git rev-parse --abbrev-ref HEAD

# Count commits since last tag
git rev-list --count $(git describe --tags --abbrev=0 2>/dev/null)..HEAD 2>/dev/null

If any git command fails (not a git repo, no tags), fall back gracefully to whatever input the user provides and note the limitation.

Phase 1b — Monorepo Detection and Handling

When the repository appears to be a monorepo (multiple package.json files, workspace configuration, packages/ or apps/ directory structure, Lerna/Nx/Turborepo config), or when the user specifies a package/workspace:

1. Detect workspace structure:

``bash # Check for monorepo indicators ls packages/ apps/ modules/ libs/ 2>/dev/null cat package.json | grep -c "workspaces" 2>/dev/null ls lerna.json nx.json turbo.json pnpm-workspace.yaml 2>/dev/null ``

1. Filter commits by path prefix:

``bash git log --oneline --no-merges -- packages// ``

1. Handle independent versioning:

• Each package may have its own version. Check packages//package.json or equivalent.
• If the user says "release @scope/package-name", filter to that package only.
• If the user says "release all packages", generate a changelog per package that has changes.

1. Cross-package changes:

• Commits touching multiple packages get listed in each affected package's changelog.
• Root-level changes (CI, tooling) go in a "Tooling" or "Infrastructure" section of a root changelog.

1. Output format for monorepo:

Present each package with changes as a separate section: ```markdown # Release Notes — 2026-03-14

## @myorg/core (1.5.0 → 1.6.0) ### Added

• ...

## @myorg/ui (2.1.0 → 2.1.1) ### Fixed

• ...

## @myorg/api (no changes) ```

---

Phase 2 — Detect Project Conventions

Before categorizing, detect the project's conventions to calibrate parsing:

Conventional commits detection:

# Sample recent commits to detect format
git log --oneline -20

| Pattern Detected | Behavior | |---|---| | Most commits use type: or type(scope): | Full conventional commit parsing. Use type for category, scope for grouping. | | Mixed — some conventional, some not | Parse conventional commits by type. Classify others by keyword analysis. | | No conventional commits | Classify entirely by keyword analysis and diff inspection. |

Existing CHANGELOG.md detection:

# Check for existing changelog
ls CHANGELOG.md CHANGELOG changelog.md HISTORY.md RELEASES.md NEWS.md 2>/dev/null

If an existing changelog file is found:

1. Read it to understand the project's changelog style and conventions.
2. Match the existing format exactly (heading levels, bullet style, date format, link format).
3. Validate it against Keep a Changelog format and note inconsistencies (see Phase 2b).
4. Determine the correct insertion point for the new entry.

Version format detection:

# Check existing tags for version format
git tag --sort=-v:refname | head -10

Detect and match the project's version format:

• v1.2.3 vs 1.2.3 (with or without v prefix)
• Calendar versioning: 2026.03, 2026.03.1
• Build numbers: build-1042
• Codenames: detect if tags or releases use codenames alongside semver

Phase 2b — Changelog Validation

When an existing CHANGELOG.md is found, validate it before inserting new content:

Validation checks:

| Check | Pass | Warn | Fail | |---|---|---|---| | Keep a Changelog format compliance | Follows standard headings | Minor deviations | Completely non-standard | | Version ordering | Newest first, monotonically decreasing | One entry out of order | Multiple entries out of order | | Date format | ISO 8601 (YYYY-MM-DD) consistently | Mixed formats | No dates at all | | Comparison links | All versions have diff links at bottom | Some missing | No links | | Duplicate versions | No duplicates | — | Same version appears twice | | Unreleased section | Present and correctly placed | Missing but otherwise OK | Unreleased below released entries | | Empty sections | No empty categories | One or two empty headings | Many empty headings |

Report validation results before proceeding:

Changelog validation:
  [PASS] Format follows Keep a Changelog standard
  [WARN] Missing comparison links for v1.1.0 and v1.0.0
  [PASS] Versions correctly ordered (newest first)
  [PASS] Dates in ISO 8601 format

If issues are found, offer to fix them: "I found 2 issues in the existing CHANGELOG.md. Want me to fix them while adding the new entry?"

---

Phase 3 — Parse, Categorize, and Group

Read all changes and categorize them. Apply intelligent grouping.

Category Rules

Categories follow Keep a Changelog standard:

| Category | Triggers | Priority | |---|---|---| | Breaking Changes | ! in conventional commit type, BREAKING CHANGE: in commit body or footer, "BREAKING", removes or renames a public API, changes return format, removes endpoints, changes required parameters, incompatible schema migration | 1 (always first) | | Security | security, CVE-, vulnerability, auth bypass, XSS, injection, CSRF, SSRF, exposure, advisory, patch security, commits touching auth/security files | 2 | | Added | feat:, feature, add, implement, introduce, support for, new, enable | 3 | | Changed | refactor:, change, update, modify, improve, enhance, rework, revamp, migrate | 4 | | Deprecated | deprecate, will be removed, legacy, sunset, end of life, EOL | 5 | | Removed | remove, drop support, delete, eliminate, strip, prune | 6 | | Fixed | fix:, fix, resolve, patch, correct, repair, handle, prevent, bug | 7 | | Performance | perf:, faster, optimize, reduce latency, cache, improve performance, speed up, benchmark | 8 | | Dependencies | deps:, chore(deps):, bump, upgrade, update [package-name], renovate, dependabot | 9 | | Documentation | docs:, readme, update docs, add documentation, JSDoc, docstring, API docs | 10 | | Internal | chore:, ci:, build:, test:, style:, refactor: (when purely internal) — include only when audience is contributors | 11 |

Grouping Rules

• Merge related commits into one bullet. Ten commits for one feature = 1 bullet, not 10.

Use the first feat: commit as the anchor and absorb subsequent fix:, refactor:, test: commits that share the same scope or touch the same files.

• Group dependency updates. "Updated React (17 → 18.3), TypeScript (4.9 → 5.4), and 12 other dependencies" not 14 separate bullets.
• Drop noise. Skip: wip, tmp, minor, fix typo, fix lint, update .gitignore,

merge branch, Merge pull request, commits that only touch test infrastructure or CI config — unless the audience is contributors.

• Preserve PR/issue references. Attach (#123) or (fixes #456) to the relevant bullet.
• Detect scope from conventional commits. feat(auth): add OAuth → the bullet goes under

"Added" with context that it is in the auth module.

Diff-Based Change Detection

When commit messages are poor quality (all say "fix", "update", "wip", or similar):

1. Analyze the actual diff:

``bash git diff --stat git diff -- (for key files) ``

1. Infer changes from code:

• New files → likely new features. Read the file to understand what it does.
• Deleted files → likely removed features. Check the file name/path for context.
• Modified files → examine the diff to understand what changed functionally.

1. Disclose the limitation:

Include a note: "Commit messages were minimal — these notes were inferred from code analysis and may be incomplete. Review the diff for full accuracy."

---

Phase 4 — Version Bump Recommendation

If the user has not specified a version number, calculate and recommend one.

Semver Rules

| Changes Detected | Bump | Rationale | |---|---|---| | Any breaking change | MAJOR | 1.x.x → 2.0.0 | | New features, no breaking changes | MINOR | 1.2.x → 1.3.0 | | Only bug fixes, patches, deps, docs | PATCH | 1.2.3 → 1.2.4 |

Pre-1.0 Special Rules

• Breaking changes in 0.x.y bump MINOR (not MAJOR): 0.3.0 → 0.4.0
• New features in 0.x.y bump MINOR: 0.3.0 → 0.4.0
• Bug fixes in 0.x.y bump PATCH: 0.3.1 → 0.3.2
• Note: "Pre-1.0 versioning — breaking changes are expected and do not require a major bump."

Calendar Versioning

If the project uses calver (detected from tags like 2025.03, 2026.01.2):

• Use YYYY.MM or YYYY.MM.PATCH based on existing convention.
• Increment PATCH within the same month. New month = reset PATCH.

Recommendation Format

Present clearly and ask for confirmation:

Version recommendation: MINOR release → v1.3.0
  Rationale: 3 new features, 5 bug fixes, no breaking changes.
  Previous version: v1.2.0 (released 2026-02-01, 41 days ago, 47 commits)

Use v1.3.0? Or specify a different version.

Release Cadence Awareness

When git history is available, calculate and report:

• Days since last release
• Number of commits since last release
• Average release cadence (from last 5 releases)

If the release is unusually large or overdue, note it:

Note: This release includes 127 commits over 89 days. Your average release cadence is
every 14 days with ~20 commits. Consider releasing more frequently to reduce risk per release.

---

Phase 5 — Release Readiness Check

Before generating the final changelog, perform a release readiness assessment. Run these checks automatically when in a git repository:

# Check for uncommitted changes
git status --porcelain

# Check for TODO/FIXME/HACK in recently changed files
git diff  --name-only | head -20
# Then search those files for TODO/FIXME/HACK

# Check for unreleased migrations
ls **/migrations/ db/migrate/ 2>/dev/null | head -5

# Check if tests pass (only suggest, don't run without permission)
ls package.json Makefile Cargo.toml pyproject.toml go.mod 2>/dev/null

Readiness report (include before the changelog outputs):

Release readiness check:
  [PASS] No uncommitted changes
  [WARN] 3 TODO comments found in changed files (auth.ts:45, cart.js:112, api.py:89)
  [PASS] No unreleased database migrations detected
  [INFO] Test suite detected (Jest) — run `npm test` before releasing
  [WARN] Branch is 2 commits behind origin/main — pull before releasing

If any checks fail critically (uncommitted changes that should be included, branch divergence), warn prominently before proceeding.

---

Phase 6 — Generate Contributor Acknowledgments

For open-source projects or when the user requests it, generate a contributors section.

# Get unique authors in the range
git log  --format='%aN ' --no-merges | sort -u

# Get co-authors from commit bodies
git log  --format='%b' | grep -i 'co-authored-by' | sort -u

# Get GitHub usernames (if remote is GitHub)
git log  --format='%aN' --no-merges | sort -u

Auto-detect if open source:

• Check for LICENSE file
• Check for CONTRIBUTING.md
• Check if the remote URL is a public GitHub repo

For open-source projects, always include the contributors section. For private/internal projects, include only if the user requests it.

Format:

### Contributors

Thanks to the following people who contributed to this release:

- @username1 — OAuth implementation (#218, #219)
- @username2 — Bug fixes (#227, #231)
- @username3 — Documentation updates (#220)
- @username4 (first-time contributor!) — Safari date picker fix (#219)

Rules:

• Map git author names to GitHub usernames when possible (check git log --format='%aN'

against gh api if available).

• Highlight first-time contributors (not found in git log before the range start).
• Group contributions by what they did, not just list names.
• Include co-authors from Co-authored-by: trailers.

---

Phase 7 — Produce Outputs

Always produce Output A (CHANGELOG.md format). Produce other outputs based on context:

| Output | When to Include | |---|---| | A: CHANGELOG.md | Always | | B: GitHub/GitLab Release Notes | Always (unless user specifies otherwise) | | C: Internal/Slack Summary | Always (unless user specifies otherwise) | | D: Email/Newsletter | When user requests it, or when the project appears to have end users (web app, mobile app, SaaS) | | E: Package Registry | When user requests it, or when package.json, Cargo.toml, pyproject.toml, setup.py, or *.gemspec is detected |

Separate each output with a clear header.

---

Output A: CHANGELOG.md (Keep a Changelog Format)

Follows keepachangelog.com exactly. Suitable for committing directly to the repository.

## [1.3.0] - 2026-03-14

### Breaking Changes
- **Renamed `/api/v1/users` to `/api/v2/users`** — update all API clients before upgrading. The v1 endpoint returns a deprecation warning in this release and will be removed in v2.0.0 (#234)

### Security
- Patched XSS vulnerability in user-generated content rendering (CVE-2026-XXXX) — upgrade immediately if you render user HTML (#233)

### Added
- OAuth2 login with Google and GitHub — click "Continue with Google" on the login page (#218)
- Dark mode support — respects system preference and includes manual toggle in Settings > Appearance (#225)
- Bulk export to CSV for all report types (#229)

### Fixed
- Cart total calculated incorrectly when multipl

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [alissonlinneker](https://github.com/alissonlinneker)
- **Source:** [alissonlinneker/claude-skills](https://github.com/alissonlinneker/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.