Guide · Agent skill
How to use the record-upgrade-instructions agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
record-upgrade-instructions is an agent skill for people contributing breaking changes to the Prisma codebase. It tells an AI agent how to write small, independent upgrade-instruction fragments for a pull request, so the published upgrade guides can be assembled from them later. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what it needs before you rely on it.
Record upgrade instructionsprisma/orm · Apache-2.0 Download the skill Quick start
- 1Confirm you are in the Prisma monorepo. The skill needs a Prisma monorepo checkout with git and the upgrade-instructions lifecycle files. It is not useful in unrelated repositories.
- 2Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or the project's .claude/skills/, or upload it under Settings → Capabilities → Skills.
- 3Ask for upgrade instructions. Describe the breaking change and the red tests in examples/ or packages/3-extensions/, and ask the agent to record upgrade instructions for the PR.
- 4Write and test the fragment. Add instructions.md for each affected audience under upgrade-instructions/pending/, with precise detection patterns and tested scripts where needed.
- 5Commit and run the coverage check. Commit the fragment and updated example or extension code, then run pnpm check:upgrade-coverage in PR mode against your base and head commits.
What does the record-upgrade-instructions skill make the agent do?
When a Prisma 8 framework change breaks tests in examples/, packages/3-extensions/ or a target facade, the fix is often a matching change to example or extension code. The skill makes the agent record that translation as an upgrade-instruction fragment instead of editing shared migration guides or picking a release number.
Each fragment is a markdown file with YAML frontmatter, optionally with scripts. The agent places it in a pending folder, and release tooling later combines fragments into the published app and extension guides. The skill also covers writing precise detection patterns and declaring explicitly when a PR has no consumer-facing change.
- Feature PRs do not edit shared transition guides.
- Each PR adds its own fragment; inherited fragments from a stack do not cover a new PR.
- Consumer-invisible changes get changes: [] with no prose.
How do you install the record-upgrade-instructions skill?
Download the ZIP from this skill's page. The skill package contains a single file, SKILL.md. Unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill limited to one repository.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with a natural request?
You do not need to name the skill. The skill is designed to load when your task matches its description. Requests that fit include asking the agent to record upgrade instructions for a PR, or describing a situation where you refactored framework code, the test suite went red in examples/ or packages/3-extensions/, and you fixed those tests by updating example or extension code.
Clear context helps. Mention the PR's target branch if it is stacked, since the skill compares against that branch rather than always main.
- Record upgrade instructions for this PR.
- I refactored the framework and fixed the red tests in examples/ by updating the example code. Write the upgrade fragment.
- This PR makes a breaking change to Prisma 8 that downstream extension authors will need to migrate across. Add the instructions.
What does a fragment look like and how do you check it?
Add upgrade-instructions/pending/<descriptive-name>/<audience>/instructions.md for each affected audience. The audience is app for examples/ changes and extension for packages/3-extensions/ and packages/3-targets/*/9-facade/ changes. Each change in the frontmatter has a kebab-case id, a one-line summary, and an optional detection block and script path.
Detection patterns are tested with new RegExp(pattern) with no flags, against the whole file. Test each pattern against a true positive and the nearest false positive. The skill's example shows a shipped pattern that excludes only the exact fns token.
Commit your changes, then run the coverage check against your pinned base and head commits. The check does not inspect uncommitted edits.
- Declare each audience independently, including real-change and no-op combinations.
- Put scripts in the audience directory and copy them to both audiences for cross-audience changes.
- Review must confirm the instructions match the PR's changes; the gate checks structure, not meaning.
git diff <base>..<head> -- examples/ packages/3-extensions/ 'packages/3-targets/*/9-facade/'
pnpm check:upgrade-coverage --mode pr --prev <base> --head <head>What about scripts and safety?
The skill itself runs no scripts and uses no network. The scripts it asks you to write are TypeScript that Node runs directly, shell, or codemods. They must need no network, no environment variables, and no input beyond the consumer's filesystem and bundled assets. Keep their relative references inside the fragment's audience directory.
Script tests live in test/integration/test/upgrade-instructions/<fragment-name>/. Tests that depend on live framework code only hold while the fragment is pending and are frozen or deleted at release. Validation by execution is still required, even when a script has its own tests.
- Run every new entry against its example or extension code, starting from the pre-PR state and ending with passing tests.
- Entries update consumer code, not the example or extension tests.
- A project made by orm init has no tsx, so Node's type stripping must accept your TypeScript syntax.
What people use it for
- Recording the app-side translation when a framework change breaks examples/ tests.
- Recording the extension-side translation for packages/3-extensions/ or a target facade.
- Writing a codemod script with a detection pattern that avoids false positives on similar identifiers.
- Declaring changes: [] for a PR that only touches internal APIs no published package re-exports.
Frequently asked questions
Is the record-upgrade-instructions skill free to use?
The source lists the licence as Apache-2.0 and does not mention pricing. The skill is distributed as a ZIP and a SKILL.md file from its page.
What do I need to run record-upgrade-instructions?
You need a Prisma monorepo checkout with git and the referenced upgrade-instructions lifecycle files. Node.js is needed to run TypeScript scripts that ship with fragments.
Can I use this skill to upgrade my own Prisma project?
No. The skill is for framework contributors submitting breaking-change PRs to the Prisma repository. Application developers upgrading their own project should use the published upgrade skills, which are the consumer-facing side.
Where do I install the skill in Claude?
Unzip the ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills.
Why does the coverage check fail after I wrote a fragment?
The check only inspects committed declarations, so commit the fragment and the updated example or extension code first. The check also does not verify that the instructions are semantically correct; review has to do that.
Does this skill compare with other upgrade tools?
The source does not compare it with other tools. It is scoped to Prisma monorepo contributors and does not apply to repositories unrelated to Prisma.
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 Prisma maintainer or contributor writing breaking-change PRs, or a reviewer checking that their upgrade instructions are scoped and tested. Pick something else if you only want to upgrade your own Prisma application, or if your repository is not the Prisma monorepo, because the referenced paths and lifecycle only exist there.
Download the skill