Guide · Agent skill

How to use the REA changelog update agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The rea-changelog-update skill is an instruction package that teaches an AI agent how to prepare the public release notes for the REA project. It covers collecting Git history and pull request data since the last published release, rewriting the newest changelog section in user-focused language, and crediting contributors in a verified way. This guide explains what the skill does, how to install it, how to trigger it, and what safety limits to respect before you use it on a live release.

REA changelog updatemorluto/rea · MIT Download the skill

Quick start

1Download and unzip. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
2Confirm prerequisites. Check that you have a Git clone with full history and tags, Node.js, GitHub CLI (gh), and access to morluto/rea with rights to read PRs and edit release PR labels and bodies.
3Ask for release-note preparation. Make a plain request naming the new version and the previous baseline tag, for example asking the agent to prepare the changelog for a REA release.
4Review the inventory. Check the generated inventory and summary record, which cover side-branch commits, associated PRs, co-authors and closing-issue reporters.
5Check the rewritten section. Read the new changelog section for accuracy, correct grouping, and single credit per contribution.
6Finalize only with authorization. Apply the label, save the provenance file, update the PR body, and run check --pr-body only after you have approval to change the live release PR.

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill's description. This one is named rea-changelog-update and is written for the REA project's release process.

Once active, the skill has the agent collect the Git history and pull request data since the last published release, then rewrite the newest section of CHANGELOG.md in plain language. It also credits contributors, and keeps the release notes in sync with the Release Please release pull request. The skill states that it only prepares notes and does not authorize merging, tagging, or publishing.

Install the rea-changelog-update skill

Download the ZIP from the skill's page in this directory and unzip it. There are two places to put the skill folder, depending on how you want to use it.

For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

Personal: ~/.claude/skills/
Project only: .claude/skills/ inside the project
Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. Ask for release-note work in plain terms that match the skill's description, such as preparing or rewriting release changelogs or GitHub release notes, or updating contributor thanks. The agent should load the skill when the request matches.

Name the release version and the previous published baseline in your request so the agent can select the right inputs. The skill expects REA's tag format, rea-agents-VERSION.

Prepare the inventory and provenance record

The skill's first step is to fetch complete history and tags, then read the baseline tag from .release-please-manifest.json on the release PR's base branch. It pins that branch's exact SHA as the editorial target and runs scripts/release-notes.mjs to create an inventory and a summary record.

The agent is instructed to read the inventory itself, not just the existing bot draft. The inventory covers side-branch commits, associated pull requests, commit authors and co-authors, and confirmed closing issues with their reporters. Unknown identities are kept as names or emails with no guessed GitHub handle.

Output files are new files; existing output is never overwritten.
Network errors stop generation. Rerun into a new output file after recovery.
Inventory is a reviewed metadata snapshot, not independent proof of who wrote a patch.

node scripts/release-notes.mjs inventory \
  --repository morluto/rea --base rea-agents-PREVIOUS \
  --target FULL_BASE_BRANCH_SHA --version VERSION \
  --manifest /tmp/rea-VERSION.contributions.json
node scripts/release-notes.mjs record \
  --manifest /tmp/rea-VERSION.contributions.json \
  --summary \
  --output /tmp/rea-VERSION.record.md

Write user-focused release notes

The agent rewrites only the newest ## [VERSION] section of CHANGELOG.md and keeps its version, date and link heading. Entries are single-line Markdown list items under Highlights, Changes, Fixes and, when applicable, BREAKING CHANGES.

Each represented contribution is credited once in the public notes, with its link and a Thanks line for the verified human author, known co-authors and confirmed issue reporters. Internal cleanup, tests, CI and routine documentation usually belong only in the provenance file. Omitting @morluto self-thanks is a maintainer request in the source, not a general rule.

Highlights: a few release-defining outcomes; no minimum for small releases.
Changes: capabilities and meaningful behavior changes.
Fixes: reliability, correctness, compatibility and safety fixes.
Agent bots and known agent accounts are excluded from thanks.

Finalize with Release Please and review carefully

Finalization changes a live release pull request, so the skill requires authorization before that step. Local preparation and validation can proceed without it. The skill adds the rea:release-notes-finalized label before editing the PR branch or body, which freezes bot refreshes on that PR.

The agent saves the reviewed inventory as docs/releases/VERSION.contributions.json, runs the check and render commands, updates the PR body with a body file, and then re-fetches the body to run check --pr-body. Review the complete diff and wait for current CI before publication.

Inline PR bodies are checked up to GitHub's 65,536-character limit; larger notes fail rather than being truncated.
New product changes after the inventory target require refreshing the notes.
Never retag or republish a package just to correct release prose.

node scripts/release-notes.mjs check \
  --manifest docs/releases/VERSION.contributions.json
node scripts/release-notes.mjs render \
  --manifest docs/releases/VERSION.contributions.json \
  --output /tmp/rea-VERSION.notes.md

Safety notes: scripts and network access

This skill runs scripts and uses the network. The scripts are scripts/release-notes.mjs, which needs Node.js, and the GitHub CLI (gh) for editing pull request bodies. It needs GitHub access to morluto/rea with rights to read PRs and edit release PR labels and bodies.

The finalization steps change live pull requests. Run the skill with a human reviewing the output, and do not let it merge, tag or publish. The skill itself says it does not authorize those actions, and the path guard does not prove that dependency or script edits in release metadata files are version-only, so review those diffs yourself.

Requires Git with full history and tags.
Requires Node.js and GitHub CLI (gh).
Avoid editing the PR body while publishing is underway.

What people use it for

Preparing the newest REA changelog section from a fresh inventory of commits and pull requests since the last tag.
Checking that every contributor in a release has correct, verified thanks in the notes.
Syncing a hand-edited changelog section into the Release Please release pull request body.
Refreshing the notes after new product changes land after the inventory target.

Frequently asked questions

How do I install the rea-changelog-update skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

What do I need to run this skill?

You need Git with full history and tags, Node.js to run scripts/release-notes.mjs, and the GitHub CLI (gh). You also need GitHub access to morluto/rea with rights to read PRs and edit release PR labels and bodies.

Is the rea-changelog-update skill free and what is its licence?

The source project is listed under the MIT licence. The skill text does not mention pricing, so check the project's licence file for the terms that apply.

Can I use this skill on a project other than REA?

No. The skill hardcodes REA's repository, tag format and scripts, so it would target the wrong repository and produce wrong output for another project.

Will the skill publish or merge my release automatically?

No. The skill states that it prepares notes and does not authorize merging, tagging, or publishing. The finalization steps do change live pull request bodies and labels, so review them before running.

What should I do if the skill fails with a network error?

The skill stops on network errors. Rerun the inventory into a new output file after the connection recovers, because existing output files are never overwritten.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a maintainer or release manager working on the REA project and need accurate, credited release notes prepared from Git and pull request history. Pick something else if you work on a different project, or if you want release notes merged or published automatically, since the skill deliberately does not do that.

Download the skill