Guide · Agent skill
How to use the Release Changelog Writer agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The release-changelog skill is a set of instructions that teaches an AI agent how the Paperclip project writes its stable release notes. Once it is installed, you can ask your agent to draft a stable changelog and it will follow a fixed process: find the last stable tag, identify the beta being promoted, gather commits, changesets and merged pull requests, flag likely breaking changes, and write a user-facing draft. This guide explains what the skill does, how to install it, how to ask for it, and what it needs to run.
Release Changelog Writerpaperclipai/paperclip · MIT Download the skill Quick start
- 1Download the ZIP. Download the release-changelog skill ZIP from this page.
- 2Unzip the skill. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside your project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 4Prepare the repository. Work in a checkout of paperclipai/paperclip with git, npm, the GitHub CLI and ripgrep available.
- 5Ask for the draft. Tell the agent which beta you are promoting and ask it to draft the stable changelog.
- 6Resolve any existing file. If a changelog already exists, choose whether to keep it, regenerate it, or update specific sections.
- 7Review before release. Check the version, commit range, breaking changes and attributions before the maintainers publish.
What the skill makes the agent do
The skill's source file is SKILL.md. It describes the stable release process for the Paperclip project, which uses calendar versioning and promotes a beta build that has already been tested. The agent works from the beta's source commit, not the tip of the main branch, so commits that land after the beta are kept out of the stable notes.
The agent gathers input from three places: git commits since the last stable tag, the .changeset/*.md files, and merged pull requests read through the GitHub CLI when it is available. It then searches for breaking changes such as destructive migrations, changed API routes and renamed config keys, and writes the draft into the required sections.
- Breaking Changes
- Highlights
- Improvements
- Fixes
- Upgrade Guide (when needed)
Install the release-changelog skill
Download the skill ZIP from this page and unzip it. You can install it in one of two ways. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ inside the repository
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Trigger the skill with a natural request
You do not need a special command. Ask the agent in plain language to draft the stable changelog for the beta you are promoting, and make sure it is running inside a checkout of the paperclipai/paperclip repository. Give the stable version or release date if you have them, because the skill needs a target version to title the notes.
Before writing anything, the agent checks whether a changelog already exists. If one does, it shows you the existing file and asks whether to keep it, regenerate it, or update specific sections. It will not overwrite a file silently.
- Draft the stable release notes for the current Paperclip beta.
- Write the changelog for the next stable release from the beta source commit.
- Check for breaking changes since the last stable tag and list them with upgrade steps.
- Regenerate only the Fixes section of the existing stable release notes draft.
Check requirements and safety before you run it
The skill needs git with access to the paperclipai/paperclip repository and its tags, and npm so the agent can read the beta dist-tag. The GitHub CLI (gh) is used to list merged pull requests when available, and ripgrep (rg) is used for the breaking-change search. The skill also refers to repository scripts such as ./scripts/draft-stable-notes.sh and ./scripts/release.sh.
The listing states that this skill runs scripts and uses the network. Review the scripts before the agent runs them, and read the draft before anything is committed or published. The skill only describes drafting steps; maintainers run the actual release. A wrong version or commit range could publish misleading notes, so check the version and range the agent reports.
- Requires git, npm, GitHub CLI (gh) and ripgrep (rg)
- Requires access to the paperclipai/paperclip repository, its tags and its scripts
- Runs scripts and uses the network
- The stable release itself is run by maintainers, not by the skill
Example workflow for a stable release draft
A typical run starts with the agent reading the beta dist-tag and fetching tags. It then resolves the beta source commit and lists commits between the last stable tag and that commit, excluding merges. Commits on the main branch after the beta are treated as input for the next release, not this one.
The agent writes the draft with entries that describe changes from the user's point of view. Where a bullet clearly maps to a merged pull request, it adds a link and the GitHub username of the author. If it cannot confirm the pull request or author, it leaves that attribution out.
- Agent resolves the beta source commit and the last stable tag
- Agent gathers commits, changesets and merged pull requests
- Agent flags breaking changes and drafts each section
- Maintainer reviews the draft and decides what to keep
git fetch origin --tags
npm view paperclipai dist-tags
git rev-parse 'beta/v{beta-version}^{commit}'Tips for getting a useful draft
The skill is strict about what goes in the notes, so good input makes a big difference. Make sure changesets are present for user-facing work, and tell the agent which beta you are promoting. If the previous stable notes exist, the agent reads them first so it describes only what changed in this release rather than repeating earlier features.
Keep the reviewer in the loop. The draft is a starting point for a human to check against the actual commits.
- Name the beta version explicitly so the right tag is used
- Keep changesets up to date for user-facing changes
- Ask the agent to rewrite a single section rather than the whole file when you only need small edits
- Review every breaking-change entry and its upgrade path before release
What people use it for
- Maintainers drafting the stable release notes from a soaked beta build.
- Release managers who need a consistent first draft to review before publishing.
- Checking a release range for breaking changes and writing their upgrade steps.
- Rewriting one section of an existing stable draft without losing the rest of the file.
Frequently asked questions
Is the release-changelog skill free to use?
The skill is listed under the MIT licence. Check the licence file in the repository for the full terms before you reuse or modify it.
What do I need to install the release-changelog skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, Capabilities, Skills.
Can I use this skill for my own project?
Not as it is. The skill hard-codes the Paperclip repository paths, tags, scripts and branch conventions, so it only fits that project. You could use its structure as a model for your own project's release process.
What tools does the release-changelog skill require?
It requires git with access to the paperclipai/paperclip repository and its tags, and npm to read the beta dist-tag. It uses the GitHub CLI (gh) for merged pull requests when available, and ripgrep (rg) for the breaking-change search.
Does the agent publish the release automatically?
No. The skill only describes how to draft the changelog. Maintainers run the actual release, and the draft should be reviewed before it is committed or published.
What should I do if the agent finds an existing changelog?
The agent reads the existing file first and shows it to you. It then asks whether to keep it, regenerate it, or update specific sections, and it never overwrites the file silently.
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 maintain the Paperclip project or prepare its stable releases and want a consistent first draft of release notes to review. Pick something else if you work on a different project, because the skill only fits Paperclip's repository layout, scripts and conventions.
Download the skill