Make Changelog
- 33 installs
- 269 repo stars
- Updated June 11, 2026
- gupsammy/claudest
make-changelog is an agent skill that lists git tag-to-tag commit ranges (and Unreleased) so you can generate structured changelog sections.
About
make-changelog is a Claude-oriented release helper built around a small Python utility that inspects git history and outputs structured version ranges. Instead of manually scrolling git log between tags, you run list_ranges.py to see how many commits belong in each section—from the oldest tagged release through HEAD as Unreleased. The skill uses that map to decide which changelog blocks the agent should draft next, including incremental fill when you already shipped notes up to a known tag. Solo builders maintaining open-source libraries, CLI tools, or SaaS repos benefit because consistent release notes build trust with users and speed up store or GitHub release pages. The workflow assumes a normal tagged semver-style history; it does not replace semantic commit discipline but makes the mechanical planning step reliable and machine-readable for your agent.
- list_ranges.py maps consecutive git tags to ranges plus an Unreleased bucket with commit counts
- Supports fill mode via --since-tag to append only newer sections after a partial changelog
- Emits text or JSON so the agent can batch-generate per-version changelog copy
- Documents exit codes 0/1/2 for usage, success, and git errors suitable for scripted workflows
- Defaults to current directory repo path with optional explicit repo_path argument
Make Changelog by the numbers
- 33 all-time installs (skills.sh)
- Ranked #150 of 248 Release Management skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/gupsammy/claudest --skill make-changelogAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 33 |
|---|---|
| repo stars | ★ 269 |
| Security audit | 3 / 3 scanners passed |
| Last updated | June 11, 2026 |
| Repository | gupsammy/claudest ↗ |
What it does
Plan git tag-to-tag version sections and commit counts so your agent can write an accurate changelog before you tag a release.
Who is it for?
maintainers who tag releases in git and want the agent to draft notes section-by-section instead of one giant unstructured log dump.
Skip if: Repos with no tags or no git history, or teams that only use continuous deployment with no versioned changelog at all.
When should I use this skill?
You are preparing a release and need tag-to-tag ranges with commit counts to drive changelog section generation.
What you get
You get a planned set of version ranges in text or JSON ready for the agent to turn into user-facing release notes before you tag and publish.
- Text or JSON list of version ranges with commit counts
- Planned changelog sections including Unreleased when applicable
By the numbers
- list_ranges.py defines three exit codes: 0 success, 1 usage error, 2 runtime git error
- Outputs commit counts per tag-to-tag range including Unreleased
Files
Changelog Generator
Create or update CHANGELOG.md from git history using Keep-a-Changelog format. Launch one haiku subagent per version range for parallel, token-efficient processing.
Step 1 — Assess Project State
Run the range-planning script to validate the repo and gather all version ranges:
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py --output json- Exit 2 = not a git repository, or repository has no commits. Stop and report the
error message from stderr to the user.
- Exit 0 = proceed. JSON output contains all ranges the skill would cover.
Also check for an existing changelog:
ls CHANGELOG.md CHANGELOG 2>/dev/nullIf CHANGELOG.md exists, read it to identify the last documented version (the most recent ## [x.y.z] heading).
Step 2 — Determine Scope
No tags exist: Script returns a single Unreleased range. Proceed in fresh mode.
Tags exist, no CHANGELOG.md: Fresh mode — process all ranges the script returned.
Tags exist, CHANGELOG.md exists: Fill mode — re-run the script with --since-tag to get only the uncovered ranges:
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py \
--since-tag <last_documented_tag> --output jsonIf the intent is ambiguous (user said "update changelog" but the file has extensive existing content), ask the user to choose:
- "Fill missing only" — add new versions/unreleased since last entry
- "Rebuild from scratch" — regenerate the full file from git history
- "Unreleased only" — refresh only the
[Unreleased]section
Step 3 — Plan Subagents
Inspect the JSON output from Step 1 or 2. Each range object has:
label— version string (1.2.0orUnreleased)from_ref— lower git ref (empty string = from initial commit)to_ref— upper git refdate— tag date or todaycommit_count— number of commits in range
Skip ranges where `commit_count == 0` — no subagent needed.
Cap at 12 subagents. If the non-empty range list exceeds 12, ask the user whether to limit to the most recent 12 or process all (noting it will take longer).
Step 4 — Launch Haiku Subagents
Spawn one Task per non-empty range in a single message (parallel). Use model: "haiku" for all subagents. Each subagent receives this self-contained prompt (substitute values from the range object):
You are generating one section of a CHANGELOG.md.
Version: [label]
Date: [date]
Git command: git log [from_ref]..[to_ref] --format="%s"
(If from_ref is empty, use: git log [to_ref] --format="%s")
Categorize by user-observable impact, not by commit prefix. The conventional
commit prefix (feat:, fix:, etc.) is a hint only — a commit labelled "feat:"
that clearly corrects a bug belongs in Fixed, not Added. Use the prefix as a
starting signal and override it when the commit subject contradicts it.
Sections and classification signals:
- Added: new capabilities users can invoke (add, introduce, implement, support)
- Changed: modified behavior of existing features (update, change, refactor, improve)
- Deprecated: features explicitly flagged for future removal
- Removed: capabilities or endpoints deleted (remove, drop, delete)
- Fixed: bugs corrected, regardless of prefix (fix, resolve, patch, correct, hotfix)
- Security: vulnerability patches (security, CVE, sanitize, escape)
Skip: merge commits, CI/CD configuration changes, version-bump commits,
formatting-only changes.
Use present tense, imperative mood: "Add X", not "Added X" or "adds X".
Omit empty sections. Omit internal variable names and implementation details.
Output ONLY the markdown block, no preamble:
## [VERSION] - DATE
### Added
- ...
### Fixed
- ...Collect all Task results before Step 5.
Step 5 — Assemble Changelog
Order version blocks newest-first. Full document structure:
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
[content from unreleased subagent, or omit section if empty]
## [1.2.0] - 2024-03-15
[content from subagent]Fill mode: Insert new version sections immediately after the # Changelog header block, before the first existing ## [ entry. Preserve all existing content exactly.
Fresh/rebuild mode: Write the complete file.
Step 6 — Write and Report
Fresh mode: Write CHANGELOG.md. Confirm overwrite with AskUserQuestion if the file already exists.
Fill mode: Use Edit to insert new sections at the correct position.
After writing, report:
- Mode used (fresh / fill / unreleased-only)
- Versions covered (label, date, commit count — from script output)
- Number of subagents used
- Any ranges that were empty (skipped)
- Any commits that could not be confidently categorized (flag for user review)
Scripts
scripts/list_ranges.py — queries git tags and computes version ranges. Invoked in Steps 1 and 2. Exit 2 = repo invalid or empty; exit 0 = success.
# All ranges (text preview)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py
# All ranges (JSON for skill use)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py --output json
# Fill mode: only ranges newer than a specific tag
python3 ${CLAUDE_PLUGIN_ROOT}/skills/make-changelog/scripts/list_ranges.py \
--since-tag v1.2.0 --output json#!/usr/bin/env python3
"""
List git version ranges for changelog generation.
Given a git repository, outputs tag-to-tag ranges (plus Unreleased) with commit
counts. Used by the make-changelog skill to plan which version sections to generate.
Usage:
list_ranges.py [repo-path] [--since-tag TAG] [--output text|json]
Exit codes:
0 success
1 usage error
2 runtime error (not a git repo, no commits, or --since-tag not found)
Examples:
list_ranges.py # all ranges in current directory
list_ranges.py /path/to/repo --output json # structured output for skill
list_ranges.py --since-tag v1.2.0 --output json # fill mode: only newer ranges
"""
from __future__ import annotations
import argparse
import json
import os
import subprocess
import sys
from datetime import date
def git(args: list[str], cwd: str) -> tuple[str, int]:
result = subprocess.run(
["git"] + args, capture_output=True, text=True, cwd=cwd
)
return result.stdout.strip(), result.returncode
def main() -> None:
parser = argparse.ArgumentParser(
description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument(
"repo_path", nargs="?", default=".",
help="Path to git repository (default: current directory)",
)
parser.add_argument(
"--since-tag", metavar="TAG",
help="Only include ranges newer than this tag (fill mode)",
)
parser.add_argument(
"--output", choices=["text", "json"], default="text",
help="Output format (default: text)",
)
args = parser.parse_args()
repo = os.path.abspath(args.repo_path)
# Validate: must be a git repo
_, rc = git(["rev-parse", "--git-dir"], repo)
if rc != 0:
print(f"Error: {repo} is not a git repository", file=sys.stderr)
sys.exit(2)
# Validate: must have at least one commit
count_out, rc = git(["rev-list", "--count", "HEAD"], repo)
if rc != 0 or not count_out.isdigit() or int(count_out) == 0:
print("Error: repository has no commits", file=sys.stderr)
sys.exit(2)
# Collect all tags, oldest to newest
tags_out, _ = git(
["tag", "--sort=version:refname",
"--format=%(refname:short)\t%(creatordate:short)"],
repo,
)
all_tags: list[dict] = []
if tags_out:
for line in tags_out.splitlines():
parts = line.split("\t", 1)
if len(parts) == 2 and parts[0]:
all_tags.append({"tag": parts[0], "date": parts[1]})
# Apply --since-tag: drop tags up to and including the anchor
if args.since_tag:
tag_names = [t["tag"] for t in all_tags]
if args.since_tag not in tag_names:
print(
f"Error: --since-tag '{args.since_tag}' not found in repository tags",
file=sys.stderr,
)
sys.exit(2)
idx = tag_names.index(args.since_tag)
all_tags = all_tags[idx + 1:]
# Build one range per tag (oldest-to-newest order, reversed at end)
ranges: list[dict] = []
for i, tag_info in enumerate(all_tags):
from_ref = all_tags[i - 1]["tag"] if i > 0 else ""
to_ref = tag_info["tag"]
if from_ref:
count_cmd = ["rev-list", "--count", f"{from_ref}..{to_ref}"]
else:
count_cmd = ["rev-list", "--count", to_ref]
c_out, _ = git(count_cmd, repo)
commit_count = int(c_out) if c_out.isdigit() else 0
ranges.append({
"label": tag_info["tag"].lstrip("v"),
"from_ref": from_ref,
"to_ref": to_ref,
"date": tag_info["date"],
"commit_count": commit_count,
})
# Unreleased section (commits after latest tag, or all commits if no tags)
if all_tags:
latest_tag = all_tags[-1]["tag"]
u_out, _ = git(["rev-list", "--count", f"{latest_tag}..HEAD"], repo)
unreleased_count = int(u_out) if u_out.isdigit() else 0
if unreleased_count > 0:
ranges.append({
"label": "Unreleased",
"from_ref": latest_tag,
"to_ref": "HEAD",
"date": str(date.today()),
"commit_count": unreleased_count,
})
else:
total_out, _ = git(["rev-list", "--count", "HEAD"], repo)
total = int(total_out) if total_out.isdigit() else 0
ranges.append({
"label": "Unreleased",
"from_ref": "",
"to_ref": "HEAD",
"date": str(date.today()),
"commit_count": total,
})
# Reverse to newest-first (standard changelog order)
ranges = list(reversed(ranges))
if args.output == "json":
print(json.dumps(ranges, indent=2))
else:
for r in ranges:
from_display = r["from_ref"] or "(initial)"
print(
f"[{r['label']}] {r['date']} "
f"{from_display}..{r['to_ref']} "
f"({r['commit_count']} commits)"
)
sys.exit(0)
if __name__ == "__main__":
main()
Related skills
Changelog AutomationAutomatically generate accurate, well-structured changelogs from commit history and Conventional Commits.11.2k38.5k
Msstore CliAutomate publishing, managing submissions, and handling CI/CD for Windows apps in the Microsoft Store.7k37.5k
Changelog GeneratorAutomatically turn git commit history into polished, customer-friendly release notes without manual rewriting.5.9k71.8k
Deploy ChecklistGenerate a complete pre-deployment verification checklist tailored to their service or release.4.6k23.3k
Opensource PipelineSafely strip secrets, sanitize code, and generate required open-source files before releasing a private project publicly.4.3k238k
Community PublishInstantly share running services with public URLs, list projects on a discoverable dashboard, or open-source code to a community GitHub repository.3.9k21How it compares
Structured tag-range planning with commit counts, not a substitute for conventional-changelog commit parsers or hosted release-note bots.
FAQ
Who is make-changelog for?
Developers and small teams using agentic coding tools who ship versioned software from git repositories and need repeatable changelog section planning.
When should I use make-changelog?
Use it in Ship right before cutting a release tag, refreshing GitHub Releases, or updating CHANGELOG.md after a sprint of merged PRs.
Is make-changelog safe to install?
It runs local git subprocesses against your repo path; review the Security Audits panel on this Prism page and avoid pointing it at untrusted directories.