# Record Upgrade Instructions

Record upgrade instructions alongside a Prisma 8 breaking-change PR, so downstream...

- Repository: https://github.com/prisma/orm (47661 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add prisma/orm --skill record-upgrade-instructions -g -a claude-code -y`
Codex: `npx skills add prisma/orm --skill record-upgrade-instructions -g -a codex -y`
Cursor: `npx skills add prisma/orm --skill record-upgrade-instructions -g -a cursor -y`
Gemini CLI: `npx skills add prisma/orm --skill record-upgrade-instructions -g -a gemini-cli -y`

## Description

Record upgrade instructions alongside a Prisma 8 breaking-change PR, so downstream consumers (users of `@internal/*` and authors of Prisma 8 extensions) can apply the matching code translation automatically via the published upgrade skills. Use when you have refactored framework code and the test suite went red in `examples/`, `packages/3-extensions/` or a target facade, when you fixed those red tests by updating example or extension code, when you are told to "record upgrade instructions for this PR", or when you made a breaking change to Prisma 8 that downstream consumers will need help migrating across.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Record upgrade instructions

Contribute an independent fragment on the PR that changes Prisma 8. Release preparation combines fragments into the published app and extension guides; **feature PRs do not edit shared transition guides or choose a release number**. Read the canonical [upgrade instruction lifecycle](../../upgrade-instructions/README.md) for storage, release assembly, and checker modes.

## Detection signals and routing

Use this skill when a framework change makes tests red in `examples/`, `packages/3-extensions/` or a target facade (`packages/3-targets/*/9-facade/`) and you fix them by updating the example or extension code rather than reverting the framework change. Those edits are the same translation downstream consumers need.

| Directory changed by the PR | Fragment audience | Consumers |
| --- | --- | --- |
| `examples/` | `app` | Public package API, contract files, on-disk migrations |
| `packages/3-extensions/` and `packages/3-targets/*/9-facade/` | `extension` | Framework SPI and extension authors |
| Both | Both, independently | Both audiences |

Changes in these directories require a declaration, subject to existing coverage-check exclusions. Generated artefacts are not generally exempt: contract format changes require a codemod or re-emission instructions. Genuinely consumer-invisible changes still get an explicit `changes: []` declaration, with no prose.

**Stacked PRs:** compare against the branch the PR actually targets, not always `main`. Each PR adds its own declaration in its own commits; inherited fragments do not cover a new PR. Do not pool a stack's instructions in its bottom PR.

Throughout this skill, `<target>` is the target branch (`main` unless stacked), `<base>` is its pinned comparison commit, and `<head>` is the PR head commit.

## Authoring workflow

The rest: https://github.com/prisma/orm/blob/HEAD/skills-contrib/record-upgrade-instructions/SKILL.md