prisma-next-extension-upgrade - SKILL.md Agent Skill

name: prisma-next-extension-upgrade description: >- Upgrade Prisma Next in your extension. Bumps every `@prisma-next/` dependency to the requested target (or npm `latest`), runs the per-transition upgrade instructions for the extension SPI (middleware lifecycle, codec / migration-tools / framework-components churn, seed-migration on-disk shape), verifies the pins are correctly exact via `prisma-next-check-pins`, runs the extension's own typecheck and tests, and commits each minor step on its own. Use when the user asks to "upgrade Prisma Next" in an extension package, or to update an extension's `@prisma-next/` deps to a new minor.

Upgrade Prisma Next (extension)

This skill upgrades a project that is a Prisma Next extension — a package that consumes the framework SPI (@prisma-next/contract, @prisma-next/framework-components, @prisma-next/migration-tools, etc.) and exposes contract / middleware / codec / migration surfaces that downstream apps install via prisma-next.config.ts.

If the project you are upgrading is a consumer app (it imports @prisma-next/postgres or @prisma-next/mongo from its application code), use the prisma-next-upgrade skill instead — or both, if the repo contains both a consumer app and an extension package, in which case run the user flow first then the extension flow in the same session.

Step 0 — Ensure the skill is up to date

Before doing anything else, ensure this skill is installed at @latest and reload it. Bug fixes to old per-transition upgrade instructions ship in the latest skill release as part of its cumulative set; running against a stale skill can apply a known-broken translation.

Concretely: if the agent runtime supports an in-session refresh, perform it now. Otherwise, exit and ask the user to re-install:

pnpm dlx skills add prisma/prisma-next/skills/extension-author --all

The extension-author skill subpath is intentionally unpinned (always main) — the cumulative instruction set is the source of truth and the latest release fixes apply to every prior transition.

Then re-invoke this skill before proceeding.

Role detection

This skill applies when the project is a Prisma Next extension. Heuristics:

package.json declares @prisma-next/contract (or another SPI package) under dependencies or peerDependencies, and
the package's name matches ^@.*/extension- (the in-tree convention used by @prisma-next/extension-pgvector, etc.), or
the package is referenced as an extensionPacks entry from a sibling app's prisma-next.config.ts in the same monorepo.

If the project additionally consumes Prisma Next from its own app code, install the prisma-next-upgrade skill (pnpm dlx skills add prisma/prisma-next/skills/upgrade --all) and run the user flow first, then this flow in the same session.

If detection is ambiguous, ask the user which role to operate under.

Version detection

From-version. Read the currently-installed Prisma Next version from pnpm-lock.yaml (or package-lock.json / yarn.lock) by inspecting the resolved version of any @prisma-next/* entry. If the lockfile shows multiple @prisma-next/* packages at different minors, the lowest minor is the from-version.
To-version. Either the version the user specified, or the latest stable from npm view @prisma-next/contract dist-tags.latest.

Report both back to the user before continuing.

Transition chain

If the from-to delta spans multiple minor versions (e.g. 0.6 → 0.8), build the chain of one-minor steps:

0.6 → 0.7 → 0.8

Apply each step in order, fully: bump, install, run instructions, check pins, validate, commit — before moving to the next. Halt the chain on the first failed step.

Per-step flow

This flow assumes you are an external extension author — your extension lives in its own repo and consumes @prisma-next/* from npm. (Extensions inside the prisma/prisma-next monorepo itself are bumped via pnpm bump-minor / scripts/set-version.ts, which rewrites every workspace:<X.Y.Z> spec in lockstep with the root version; they do not run this skill.)

For each (from, to) step in the chain:

Bump @prisma-next/* deps. Rewrite every @prisma-next/* entry in the extension's package.json to the exact <to> version (e.g. "0.8.0" — no caret, no tilde, no range, no workspace: specifier; the exact-pin rule below details why). All entries advance to the same version. Cover whichever dep field(s) the extension uses today — dependencies and/or peerDependencies — and any optionalDependencies. The extension-upgrade skill itself ships via pnpm dlx skills add (see Step 0); there is no @prisma-next/extension-upgrade-skill npm entry to bump. The companion CLI tool is @prisma-next/extension-author-tools — leave its pin at the version the extension's CI is currently using; bumping it is independent of the framework upgrade and is normally a no-op.
Install. Run pnpm install (or the project's lockfile-managing command). The extension's source is now broken against the new SPI — the upgrade instructions for <from> → <to> exist to fix it.
Check pins. Run pnpm exec prisma-next-check-pins (shipped by @prisma-next/extension-author-tools). This sanity check asserts that every @prisma-next/* entry across dependencies, peerDependencies, and optionalDependencies is a single exact-version string and that all entries share the same version. If the check fails, the bump step did not rewrite every spec — fix the offending entries and re-run before proceeding.
Read the upgrade instructions. Load upgrades/<from>-to-<to>/instructions.md from this skill package. Parse the YAML frontmatter and pay particular attention to its changes[] array.
Apply each change. For each entry in changes[]:
- If the entry has a detection block (a glob + content predicate), run it. If no files match, skip this change.
- If the entry has no detection, apply unconditionally.
- If the entry names a script: (a relative path next to instructions.md), invoke it from the project root:
  - *.ts → pnpm exec tsx <skill>/upgrades/<from>-to-<to>/<script>
  - *.sh → bash <skill>/upgrades/<from>-to-<to>/<script>
  - codemods → invoke per the script's own instructions.md prose.
- If the entry has no script, follow the prose body in instructions.md directly.
If changes[] is empty (the placeholder shape for transitions with no extension-side breaking changes), this sub-step is a no-op — proceed to validation.
Validate. Run pnpm build && pnpm test (or the project's equivalent — the scripts field of the extension's package.json is the discovery surface). If anything is red, halt the chain. Do not auto-roll-back; surface the failure to the user with the failing change's id (from the frontmatter), the file paths the change operated on, and the inferred remediation.
Commit. Create one commit containing this step's changes: the package.json bump, the lockfile churn from pnpm install, and any source-file rewrites from the applied changes. Use the message:
```
chore: upgrade @prisma-next/* to <to-version>
```
(Or the extension's own commit-message convention, if it has one.) One commit per step — never squash steps.

Move on to the next step. Repeat.

Exact-pin rule

Prisma Next extensions pin every @prisma-next/* dependency to a single exact version (no ^, no ~, no range, no wildcard, no workspace: specifier in the published package.json). All @prisma-next/* entries share the same version. The pin advances only after a successful upgrade run against the new minor.

prisma-next-check-pins (shipped by @prisma-next/extension-author-tools — install with pnpm add -D @prisma-next/extension-author-tools) enforces the rule. Run it locally with:

pnpm exec prisma-next-check-pins

Wire it into the extension's CI alongside the build/test step so an accidental range pin fails the PR before it lands.

When the chain is done

Report back to the user: the number of steps applied, the SHAs of the commits you made, and any open follow-ups.

Failure surfaces

When a step fails:

Surface a structured error with code PN-UPGRADE-NNNN, the failing change's id, the file paths the change touched (or the lockfile, or the pin check, or the validation command), and the inferred remediation.
Do not retry automatically.
Do not auto-roll-back the commit. The user can revert if they want a clean slate.