UP

updating-changelog

Analyze PR changes to automatically generate and update migration notes and changelog documentation.

Install

mkdir -p .claude/skills/updating-changelog && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/3602" && unzip -o skill.zip -d .claude/skills/updating-changelog && rm skill.zip

Installs to .claude/skills/updating-changelog

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Updates changelog documentation for contract developers and node operators by analyzing branch changes relative to 'next'. Use when preparing a PR, updating migration notes, documenting breaking changes, or when asked to update changelog/release notes.
252 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

Key capabilities

  • →Analyze git diffs between development branches
  • →Categorize changes into breaking, features, and deprecations
  • →Draft release notes and migration entries
  • →Format documentation for contract developers and node operators

How it works

The skill compares the current branch against the next branch to identify code changes, then formats these findings into specific markdown files following established project conventions.

Inputs & outputs

You give it
Git branch diff
You get back
Markdown formatted changelog entry

When to use updating-changelog

  • →Draft release notes for a new PR
  • →Update migration notes for contract changes
  • →Document breaking API changes
  • →Create changelog entries for node operators

About this skill

Updating Changelog

The docs live in this repository's docs/, in two lines that each have their own copy of every developer and operator page (docs/CLAUDE.md, "Two dev lines: change both"). The code they describe is mostly aztec-node's: main's pages follow aztec-node main at the commit docs/aztec-node.json pins, and the v6 line's (docs/lines/v6/) follow aztec-node v6 at the commit docs/lines/v6/aztec-node.json pins. Each is read through its line's checkout, which node docs/scripts/aztec_node.mts fetch keeps (main's is $AZTEC_NODE_DIR, default docs/.aztec-node/tree; v6's is docs/lines/v6/.aztec-node/tree); versions and changes are read there, never in the labs/ submodule. This repository's own code (l1-contracts/, barretenberg/, …) is the rest.

aztec-node records operator-facing changes as they land, in CHANGELOG-OPERATORS.md at its root. It keeps one copy per release line, on that line's branch, so the checkout holds the copy for the line the pin names. Those entries are the operator changelog's source: this skill moves them here and re-heads them under the release, rather than reconstructing them from the diff. The diff is still read, as the check on what the file missed.

Steps

1. Determine Target Files

The version is the Labs release the line's pin names, read from its checkout. For main (for the v6 line, lineopt="--line v6"):

cd "$(git rev-parse --show-toplevel)"
lineopt=
node docs/scripts/aztec_node.mts $lineopt fetch && pin=$(node docs/scripts/aztec_node.mts $lineopt env) || exit 1
eval "$pin"
jq -r '."."' "$AZTEC_NODE_DIR/.version-manifest.json" 2>/dev/null ||
  jq -r '."."' "$AZTEC_NODE_DIR/.release-please-manifest.json"

6.0.0 → edit v6.md. aztec-node renamed its manifest, so read whichever name the pinned commit carries; both live in the checkout. It keeps one branch per release line — v6 ships the 6.x line, main the next major — and the pin names a commit on one of them, so the version this reports is the line being documented. The release-please manifest at this repository's root versions the Foundation tree instead, whose numbers are unrelated to Labs': never take the version from it.

Documenting one aztec-node PR (source 3 below) takes the major from the PR's line instead, since a pin can lag it: baseRefName main is the major main carries (v7 from 2026-11-04), v6 is v6.

Which lines get the entry. A v6.x entry goes into both lines, since v7 readers upgrade from the latest v6. A v7 entry goes into main only. Released entries are history in either line: never edit them.

Target files, in each line that gets the entry (main's paths below; the v6 line's are the same under docs/lines/v6/):

  • Aztec contract developers: docs/docs-developers/docs/resources/migration_notes.md
  • Node operators and Ethereum contract developers: docs/docs-operate/operators/reference/changelog/v{major}.md

When that file is new (the first entry of a major), two more files of the same line must be updated or the page ships unreachable:

  • docs/docs-operate/operators/reference/changelog/index.md: add a ### [<version>](./<page>.md) entry at the top of ## Version history. The heading is the release (v6.0.0, v5.2.0, v4.3.x); the link target is the page's actual filename, which is not derived from the heading. Page names vary by how many releases a major has needed: v6.md, v5.2.md, v4.3.md, v4.2.md, v4.md, v2.0.2.md all exist. Copy the filename you created; do not construct it from the version. docusaurus.config.js sets onBrokenMarkdownLinks: "throw", so a link to a page that does not exist fails the build.
  • docs/sidebars-operate.js: add "operators/reference/changelog/<page>" (the same filename, without .md) to the changelog list. The sidebar enumerates these pages explicitly; an unlisted page is published but has no nav entry.

Routing the Labs release notes (source 4 below, and the release skills). Route each entry by the section it sits in, into the target files above:

Section of the notesGoes to
Breaking changes: Aztec.nr, Aztec.js, Node API, CLI (wallet and dev commands), Protocolmigration notes
For wallet / PXE developersmigration notes, when a project on the previous version must change something
Breaking changes for node operators, When to switch on Mainnet, Node operators under Breaking changes, For node operators (Publishers and L1, BLS keys and staking, Provers, Operations)operator changelog
Where things liveby the entry's tag: [npm] and [Aztec.nr] to the migration notes, [Docker] to the operator changelog
Security & correctnessoperator changelog, only when an operator must act
New in this releaseoperator changelog (its new-features shape) when operators see it; never the migration notes
Protocol constantsneither: /release-docs Step 9 checks them against the chain
Summary, Referenceneither

These are v6.0.0's headings. Route a section the table does not name by who must act on each entry, and ask when that is unclear. The migration notes take what a project on the previous version must change, plus deprecations that still work; pure new features stay out. The operator changelog takes breaking changes, new features and changed defaults.

2. Analyze Branch Changes

The base is origin/next (git fetch origin next first). Four sources, each read where it lives:

  1. This repository's own changes (Foundation code, and the docs already written; the labs gitlink is the Foundation's build input, not the docs' pin):

    cd "$(git rev-parse --show-toplevel)"
    git diff origin/next...HEAD --stat -- . ':!labs'
    git diff origin/next...HEAD -- . ':!labs'
    
  2. Labs code, when this branch moves a line's pin (docs/aztec-node.json or docs/lines/<line>/aztec-node.json, moved with node docs/scripts/aztec_node.mts [--line <line>] pin <tag>). Read the range in that line's checkout; both commits must be in it, and a two-commit diff needs no history between them. For main:

    cd "$(git rev-parse --show-toplevel)"
    pinfile=docs/aztec-node.json lineopt=   # the v6 line's: pinfile=docs/lines/v6/aztec-node.json lineopt="--line v6"
    old=$(git show "$(git merge-base origin/next HEAD):$pinfile" | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).commit')
    new=$(node -p "require('./$pinfile').commit")
    node docs/scripts/aztec_node.mts $lineopt fetch && pin=$(node docs/scripts/aztec_node.mts $lineopt env) || exit 1
    eval "$pin"
    git -C "$AZTEC_NODE_DIR" fetch --depth 1 --no-tags origin "$old" "$new"
    git -C "$AZTEC_NODE_DIR" diff "$old" "$new" -- CHANGELOG-OPERATORS.md
    git -C "$AZTEC_NODE_DIR" diff --stat "$old" "$new"
    git -C "$AZTEC_NODE_DIR" diff "$old" "$new" -- yarn-project/ noir-projects/ <other paths>
    gh api "repos/aztec-labs-eng/aztec-node/compare/$old...$new" \
      --jq '.total_commits, (.commits[].commit.message | split("\n")[0])'
    gh api "repos/aztec-labs-eng/aztec-node/compare/$old...$new" \
      --jq '.commits[].commit.message | select(test("!:"))'
    

    The lines that diff adds to CHANGELOG-OPERATORS.md are the operator entries for this pin move, written by whoever made each change. Take them as they stand: the author knew what breaks. A pin whose $old predates the file has nothing to diff, so read the section whole instead:

    git -C "$AZTEC_NODE_DIR" show "$new:CHANGELOG-OPERATORS.md"
    

    Both commands come back empty for a pin either side of which predates the file; the commit scan is then the only source, as it was before.

    Everything below is the check on what that file missed. The entry is a convention rather than something CI enforces, so a PR that renamed a flag without writing one still has to be documented. When the diff turns up such a change, say so: the entry is missing in aztec-node too, and the next person to read that file will not know the change happened.

    aztec-node marks breaking changes only with the conventional-commit ! (feat!:, feat(txe)!:), never a BREAKING CHANGE: trailer. The second command prints every message containing !:, bodies included: port commits (chore: port … from monorepo) list the breaking commits they carry only in their body. The compare API lists at most 250 commits; when total_commits is larger, list the PRs merged between the two commits' dates instead, and keep only those the diff confirms:

    from=$(git -C "$AZTEC_NODE_DIR" log -1 --format=%cs "$old") to=$(git -C "$AZTEC_NODE_DIR" log -1 --format=%cs "$new")
    gh pr list --repo aztec-labs-eng/aztec-node --state merged --limit 1000 \
      --search "merged:$from..$to" --json number,title --jq '.[] | "\(.number) \(.title)"'
    
  3. One aztec-node PR, when asked to document a change that has not reached the pin yet:

    gh pr view <PR_NUMBER> --repo aztec-labs-eng/aztec-node --json title,body,baseRefName,files,url
    gh pr diff <PR_NUMBER> --repo aztec-labs-eng/aztec-node
    

    When the PR touches CHANGELOG-OPERATORS.md, that entry is what to document, and the branch the PR targets names the release line it belongs to. When it changes something operators configure and carries no entry, the entry is missing there: say so, so it can be added before the pin moves and the change has to be reconstructed from the diff alone.

  4. The Labs release notes, when this branch moves a line's pin to a release or rc tag of v6.1.0 or later (v6.1.0-rc.1 counts). They index what changed; docs/CLAUDE.md ("Labs release notes") says how to treat them. The range starts at the newest released version in the line's migration notes, not at the old pin, which can be a nightly. For main:

    cd "$(git rev-parse --show-tople
    

Content truncated.

When not to use it

  • →When changes are not relative to the next branch

Prerequisites

git

Limitations

  • →Requires manual review of draft entries before file updates
  • →Dependent on consistent use of component tags

How it compares

It automates the categorization and formatting of release notes based on project-specific documentation standards rather than manual drafting.

Compared to similar skills

updating-changelog side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
updating-changelog (this skill)19moReviewIntermediate
releasenotes15moNo flagsBeginner
bd-to-br-migration110moReviewIntermediate
readme-sync05moReviewBeginner

Try saying

Example prompts that trigger this skill in your AI assistant.

Search skills

Search the agent skills registry