Guide · Agent skill
How to use the Draft Release Notes agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The draft-release-notes skill is an instruction file that teaches an AI agent how to write the public release-notes file for a Prisma release. It is written for Prisma maintainers and release engineers, and for contributors who want to see how the Prisma release-notes convention works. After reading this guide you will know what the skill does, how to install it, how to ask an agent to run it, and what it needs to run safely.
Draft Release Notesprisma/orm · Apache-2.0 Download the skill Quick start
- 1Check the requirements. Confirm that git can read the prisma/orm tags, that gh is authenticated, and that the Linear MCP connection is active.
- 2Download the ZIP. Download the draft-release-notes ZIP from the skill page on this site.
- 3Install the skill. Unzip it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project, or upload it under Settings, then Capabilities, then Skills in the Claude apps.
- 4Start a release cut. Work in the release worktree created by the publish-npm-version skill, with the target version known and upgrade guides committed.
- 5Ask in plain language. Request something like draft the release notes or summarize what shipped since the last release, then review the output file and its PR links.
What the skill makes the agent do
When a Prisma maintainer cuts a release, this skill tells the agent how to build the public release-notes file. The agent finds the previous release tag, lists the merged pull requests since then, looks up unclear internal ticket titles for context, decides which changes users would care about, and writes categorized notes with breaking changes first.
The notes are written in the agent's own public wording and must not copy internal ticket text. The resulting file, docs/releases/v<version>.md, becomes the GitHub Release body. The skill is for authoring notes, not for reading them. It is not meant for dev or beta builds, which create no GitHub Release.
What you need before you install it
The skill assumes a working setup. It is not a standalone tool. The source lists these requirements:
- git with access to the prisma/orm repository tags
- GitHub CLI (gh), authenticated so it can read pull requests
- A Linear MCP connection, so the agent can read referenced Linear issues for context
- Repository context from the publish-npm-version and record-upgrade-instructions skills
How to install the skill
Download the ZIP file from the skill's page on this site. Then choose one of the two install locations below.
For a personal install, unzip the file into ~/.claude/skills/. To limit the skill to one project, unzip it into the .claude/skills/ folder inside that project.
You can also upload the ZIP in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload it there.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your repository
- Claude apps: Settings → Capabilities → Skills
How to trigger the skill with natural requests
You do not need a special command. The skill is meant to run inside a release cut, from the release worktree that the publish-npm-version skill creates. Ask the agent in plain language. The skill's description lists these phrasings as triggers:
- draft the release notes
- write the changelog for this release
- author docs/releases/v<x>.md
- summarize what shipped since the last release
Walkthrough: how the agent builds the notes
First, the agent resolves the lower bound of the range, which is the most recent published release tag. Dev and beta tags are excluded, but release-candidate tags are not, so a release-candidate respin covers only what changed since the previous one. The source uses this command:
- Enumerate the commits with git log --first-parent, then resolve each to its pull request with gh.
- Read referenced Linear issues only for context. Write a fresh public sentence and cite the PR number, never the ticket.
- Triage each PR. Breaking changes and public-surface changes are always included. Internal refactors, CI changes, test-only PRs, and most dependency bumps are dropped silently.
- Group entries under fixed sections, starting with Breaking changes, then Features, then Fixes, then New contributors. Empty sections are omitted.
PREV_TAG=$(git describe --abbrev=0 --tags --match 'v[0-9]*' --exclude '*-dev.*' --exclude '*-beta.*')Safety notes: scripts and network access
The skill runs no scripts. It is prose-driven, so the agent performs the enumeration, lookup, triage, and writing itself, guided by the instructions. There is no codemod to execute.
The skill does use the network. It calls GitHub through the gh command and reads Linear issues through the Linear MCP connection. Check that these connections point at the accounts and repositories you intend before running it.
The skill also sets two hard rules. Linear content must never be copied into the notes, including customer names, internal rationale, and raw ticket prefixes. Every line must link its PR so a human reviewer can check it. Keep the human review step in place.
Tips for getting good output
Run the skill from the release worktree with the target version already known. The skill expects the upgrade guides to be reviewed and committed first.
Treat the draft as input to review, not a final product. The source says the human PR review is the backstop for triage and wording judgment calls.
Use the skill for stable and release-candidate cuts only. Do not use it to backfill notes for a release that has already shipped.
What people use it for
- Drafting docs/releases/v<version>.md for a stable release before the release PR is reviewed
- Writing a release-candidate notes file that covers only changes since the previous release candidate
- Summarizing merged pull requests into categorized notes with breaking changes listed first
- Studying how the Prisma release-notes convention is applied, as a contributor
Frequently asked questions
How do I install the draft-release-notes skill?
Download the ZIP from the skill page on this site. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.
Is the draft-release-notes skill free?
The source does not state pricing or licence terms beyond the listed licence, which is Apache-2.0. Check the repository licence file for the full terms.
What do I need to run the draft-release-notes skill?
You need git with access to the prisma/orm repository tags, the GitHub CLI (gh) authenticated to read pull requests, and a Linear MCP connection. It also relies on the publish-npm-version and record-upgrade-instructions skills for repository context.
Does the skill run scripts or access the network?
It runs no scripts and is prose-driven. It does use the network, through gh to read pull requests and through the Linear MCP connection to read referenced issues.
Can I use this skill for dev or beta builds?
No. The skill says not to use it for dev or beta builds, because those create no GitHub Release. It is intended for stable and release-candidate cuts.
Is this skill an alternative to GitHub's automatic release notes?
The source says the publish workflow ships this committed notes file with gh release create and does not use a generate-notes fallback. The file the agent authors is what consumers read. The source does not compare it with other tools beyond that.
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
This skill suits Prisma maintainers and release engineers who cut stable or release-candidate versions and want a consistent, reviewable notes draft. It is not for people who only read release notes, or for anyone publishing dev or beta builds. If you do not have the Prisma repository, gh, and a Linear connection set up, pick a simpler changelog approach instead.
Download the skill