docs(skills): fix claims-vs-reality drift from the skills audit (TML-3223)

docs/releases/README.md

@@ -16,9 +16,11 @@ These files are drafted automatically by the [`draft-release-notes`](../../skill
 - **Write for users, not maintainers.** The audience is someone upgrading their app, not the team that shipped the change. Do not carry internal `TML-NNNN:` issue prefixes — link the PR instead.
 - **Categorize** entries under the fixed section order below, and **omit any section that has no entries**.
 - **Lead with breaking changes** — they are what a reader scanning the notes most needs to see.
-- **Show the impact of breaking changes with a short before/after example.** For the code-visible breaking changes (contract-shape changes, authoring-surface changes, runtime-option changes), nest a compact `before` / `after` snippet under the prose bullet so a reader can see the change at a glance. Source the snippet from the matching `<prev.minor>-to-<head.minor>` upgrade recipe so it stays accurate. Lead with PSL (```` ```prisma ````) when the change is on the authoring surface; use TS/JSON only when the change is genuinely a TS/emitted-shape change. Operational-only breaks (version floors, peer-dep changes, package removals) need no example.
-- **Link PRs and contributors as absolute markdown links** — `[#1234](https://github.com/prisma/prisma-next/pull/1234)` and `[@handle](https://github.com/handle)`, never bare `#1234` / `@handle`. Bare references only autolink inside the GitHub Release body, **not** when this file is read as a repo file or in PR review; explicit links work in every context. Attribute contributors, especially first-time ones.
-- **Link migration recipes as absolute, tag-pinned URLs** — `https://github.com/prisma/prisma/blob/v<version>/skills/upgrade/prisma-next-upgrade/upgrades/<prev.minor>-to-<head.minor>/` — not repo-relative paths. This file is published verbatim as the GitHub Release body, where repo-relative links do not resolve; pinning to the release tag keeps the link working and rot-proof.
+- **Show the impact of breaking changes with a short before/after example.** For the code-visible breaking changes (contract-shape changes, authoring-surface changes, runtime-option changes), nest a compact `before` / `after` snippet under the prose bullet so a reader can see the change at a glance. Source the snippet from the matching `<transition-label>` upgrade recipe so it stays accurate. Lead with PSL (```` ```prisma ````) when the change is on the authoring surface; use TS/JSON only when the change is genuinely a TS/emitted-shape change. Operational-only breaks (version floors, peer-dep changes, package removals) need no example.
+- **Link PRs and contributors as absolute markdown links** — `[#1234](https://github.com/prisma/prisma/pull/1234)` and `[@handle](https://github.com/handle)`, never bare `#1234` / `@handle`. Bare references only autolink inside the GitHub Release body, **not** when this file is read as a repo file or in PR review; explicit links work in every context. Attribute contributors, especially first-time ones.
+- **Link migration recipes as absolute, tag-pinned URLs** — not repo-relative paths. This file is published verbatim as the GitHub Release body, where repo-relative links do not resolve; pinning to the release tag keeps the link working and rot-proof. A breaking change can affect either audience or both, so link whichever recipe directories exist:
+  - User-facing migrations: `https://github.com/prisma/prisma/blob/v<version>/skills/prisma-next-upgrade/upgrades/<transition-label>/`
+  - Extension-author migrations: `https://github.com/prisma/prisma/blob/v<version>/skills/prisma-8-extension-upgrade/upgrades/<transition-label>/`
 
 The section order is: **Breaking changes → Features → Fixes → New contributors**.
 
@@ -38,7 +40,7 @@ Copy this into `docs/releases/v<version>.md` and fill it in, dropping any sectio
 
 ## Breaking changes
 
-- **<short title>** — <what changed and what the reader must do>. See the [migration recipe](https://github.com/prisma/prisma/blob/v<version>/skills/upgrade/prisma-next-upgrade/upgrades/<prev.minor>-to-<head.minor>/). ([#<pr>](https://github.com/prisma/prisma-next/pull/<pr>))
+- **<short title>** — <what changed and what the reader must do>. See the [migration recipe](https://github.com/prisma/prisma/blob/v<version>/skills/prisma-next-upgrade/upgrades/<transition-label>/). ([#<pr>](https://github.com/prisma/prisma/pull/<pr>))
 
   Before:
 
@@ -54,15 +56,15 @@ Copy this into `docs/releases/v<version>.md` and fill it in, dropping any sectio
 
 ## Features
 
-- <new capability>. ([#<pr>](https://github.com/prisma/prisma-next/pull/<pr>))
+- <new capability>. ([#<pr>](https://github.com/prisma/prisma/pull/<pr>))
 
 ## Fixes
 
-- <bug fix>. ([#<pr>](https://github.com/prisma/prisma-next/pull/<pr>))
+- <bug fix>. ([#<pr>](https://github.com/prisma/prisma/pull/<pr>))
 
 ## New contributors
 
-- [@<handle>](https://github.com/<handle>) made their first contribution in [#<pr>](https://github.com/prisma/prisma-next/pull/<pr>)
+- [@<handle>](https://github.com/<handle>) made their first contribution in [#<pr>](https://github.com/prisma/prisma/pull/<pr>)
 ````
 
 ## See also

skills-contrib/ast-visitor-pattern/SKILL.md

@@ -14,7 +14,7 @@ When a discriminated union has **3+ variants** and **2+ dispatch sites** (render
 
 ## Structure
 
-Four pieces, always in the same file:
+Four pieces, usually in one file — the Mongo DDL set below spreads them over three:
 
 ```typescript
 // 1. Abstract base (not exported — consumers use the union type)
@@ -93,5 +93,6 @@ export function bar(value: string): Foo { return Object.freeze({ kind: 'bar', va
 
 ## Codebase examples
 
-- `MongoAstNode` / `MongoDdlCommandVisitor` — `packages/2-mongo-family/4-query/query-ast/src/ddl-commands.ts`
-- `OpFactoryCall` / `OpFactoryCallVisitor` — `packages/3-mongo-target/1-mongo-target/src/core/op-factory-call.ts`
+- `MongoAstNode` base — `packages/2-mongo-family/4-query/query-ast/src/ast-node.ts`
+- `MongoDdlCommandVisitor` interface — `packages/2-mongo-family/4-query/query-ast/src/ddl-visitors.ts`
+- Concrete DDL commands and their union — `packages/2-mongo-family/4-query/query-ast/src/ddl-commands.ts`

skills-contrib/bumping-biome/SKILL.md

@@ -9,7 +9,7 @@ description: Bumps `biome` package versions (e.g. `@biomejs/biome`) using `pnpm`
 
 1. Run `pnpm up -D -w -r @biomejs/biome@<version>` - replace `<version>` with a specific package version provided in the session, otherwise fallback to `latest`.
 
-2. Rename all `biome.json` files to `biome.jsonc` and replace the old package version number in `$schema` with the newly installed package version number from the previous step.
+2. If any `biome.json` files remain, rename them to `biome.jsonc`. Then replace the old package version number in `$schema` with the newly installed package version number from the previous step, in every `biome.jsonc`.
 
 3. Run `pnpm -w lint:fix`. Report any issues/regressions briefly.
 

skills-contrib/contrib-pr/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: contrib-pr
-description: Open a high-quality external contributor PR against prisma-next. Use when the user is an outside contributor (not a Prisma maintainer) and wants to submit a change as a pull request from a fork. Encodes the contribution flow from CONTRIBUTING.md so the resulting PR passes review on the first round.
+description: Open a high-quality external contributor PR against prisma/prisma. Use when the user is an outside contributor (not a Prisma maintainer) and wants to submit a change as a pull request from a fork. Encodes the contribution flow from CONTRIBUTING.md so the resulting PR passes review on the first round.
 ---
 
 # Contributor PR skill (external)
 
-This skill is for **external contributors** to `prisma/prisma` who are using an LLM-based agent to author or finalize a PR. It is intentionally separate from the maintainer-facing `create-pr` skill: it does not depend on Linear access, internal plan/spec documents, or any private context. It encodes the expectations laid out in [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) as a runnable workflow, so the PR you produce matches the shape maintainers expect on the first review round.
+This skill is for **external contributors** to `prisma/prisma` who are using an LLM-based agent to author or finalize a PR. It is intentionally separate from the maintainer-facing `create-pr` skill: it does not depend on Linear access, internal plan/spec documents, or any private context. It encodes the expectations laid out in [`CONTRIBUTING.md`](../../CONTRIBUTING.md) as a runnable workflow, so the PR you produce matches the shape maintainers expect on the first review round.
 
 If the user is a maintainer with access to internal Linear tickets, use `create-pr` instead.
 
@@ -14,8 +14,8 @@ If the user is a maintainer with access to internal Linear tickets, use `create-
 Trigger this skill when the user says any of:
 
 - "Open a PR for this contribution"
-- "Submit this as a PR to prisma-next"
-- "I'm contributing to prisma-next, finalize my change"
+- "Submit this as a PR to prisma/prisma"
+- "I'm contributing to Prisma Next, finalize my change"
 - "Help me get this PR ready for review"
 
 If the user has clearly already followed the contribution flow and just needs the `gh pr create` invocation, you may skip directly to step 5.
@@ -38,9 +38,9 @@ This skill is a pit of success — there is no CI gate that checks you used it.
 
 Before doing anything else, read the project's contribution docs:
 
-1. Read [`CONTRIBUTING.md`](../../../CONTRIBUTING.md). This is the source of truth for setup, the test command set, DCO signoff, and PR expectations.
-2. Read [`CODE_OF_CONDUCT.md`](../../../CODE_OF_CONDUCT.md) so you understand what's expected in your interactions on the PR thread.
-3. Skim [`SECURITY.md`](../../../SECURITY.md). If your change is fixing a security issue, **stop and use the Private Vulnerability Reporting flow instead** — do not open a public PR.
+1. Read [`CONTRIBUTING.md`](../../CONTRIBUTING.md). This is the source of truth for setup, the test command set, DCO signoff, and PR expectations.
+2. Read [`CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md) so you understand what's expected in your interactions on the PR thread.
+3. Skim [`SECURITY.md`](../../SECURITY.md). If your change is fixing a security issue, **stop and use the Private Vulnerability Reporting flow instead** — do not open a public PR.
 
 If anything in `CONTRIBUTING.md` contradicts what this skill says, `CONTRIBUTING.md` wins.
 
@@ -51,7 +51,7 @@ Before opening the PR, check:
 - **One logical change.** If the diff includes unrelated cleanup or "while I was here" fixes, ask the user whether to split them into separate PRs. Mixed-scope PRs almost always trigger a "please split this" review comment.
 - **Substantive change?** If the change is more than a typo / doc fix / obvious bug fix, ask the user whether they opened a tracking issue first per `CONTRIBUTING.md`. If not, recommend they do — maintainers will respond within 5 business days, and a half-day issue conversation can prevent a one-week PR rewrite when the design direction differs from what they expect.
 - **Tests updated.** If the change has any behavioural delta and there are no test changes in the diff, push back on the user before opening the PR. "Why aren't there tests?" is the most common reason a PR gets bounced.
-- **No backward-compat shims.** prisma-next is pre-1.0; if the change renames or removes an API, the call sites should be updated, not aliased.
+- **No backward-compat shims.** Prisma Next is pre-1.0; if the change renames or removes an API, the call sites should be updated, not aliased.
 
 ### Step 3 — Run the right test suites
 
@@ -114,15 +114,16 @@ Examples:
 - `fix(postgres-adapter): handle null in jsonb columns`
 - `docs(contributing): clarify pnpm install steps`
 
-The PR title flows directly into the auto-generated GitHub Release notes when the version that contains it is published — pick a title a downstream user would understand.
+PR titles are the raw material the release-notes author triages when a version ships, so pick a title a downstream user would understand.
 
 #### Body
 
-Fill in the [pull request template](../../../.github/PULL_REQUEST_TEMPLATE.md) sections in order:
+Fill in the [pull request template](../../.github/PULL_REQUEST_TEMPLATE.md) sections in order:
 
 - **Linked issue**: `Fixes #N` / `Refs #N`. If no issue exists because the change is small, write `n/a — small change`.
 - **Summary**: one or two sentences focused on *why*, not file-by-file *what*. "Adds X because Y was broken" rather than "Adds X function in foo.ts and modifies bar.ts".
 - **Testing performed**: list the actual `pnpm test:*` commands you ran. If you ran a manual repro (e.g. against the demo), say so.
+- **Skill update**: say which agent skill the change teaches. Write `n/a — internal only` only when the change is purely internal or a refactor with no user-visible delta. A user-facing change that teaches no existing skill still needs a sentence saying why no skill update is required. The checklist below asks you to confirm this section.
 - **Checklist**: confirm DCO signoff, scope, tests, conventional title.
 - **Notes for the reviewer** (optional): alternative approaches you considered, follow-ups intentionally deferred, anything you want the reviewer to focus on.
 

skills-contrib/create-pr/SKILL.md

@@ -69,11 +69,13 @@ The PR description must follow a **decision-led, narrative** structure. A teamma
 
 #### Consult the PR template
 
-Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's required headers (in prisma-next today: `## Linked issue`, `## Testing performed`, `## Checklist`) must appear in the final body even when the skill's recommended structure below doesn't list them. Where the template and the skill overlap, use the template's richer header (e.g. `## Linked issue` — with a `Refs:` link and any prerequisite-PR / follow-up-PR context — replaces the bare close-line at the top).
+Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's required headers (today: `## Linked issue`, `## Summary`, `## Testing performed`, `## Skill update`, `## Checklist`, `## Notes for the reviewer`) must appear in the final body even when the skill's recommended structure below doesn't list them. Where the template and the skill overlap, use the template's richer header (e.g. `## Linked issue` — with a `Refs:` link and any prerequisite-PR / follow-up-PR context — replaces the bare close-line at the top).
 
 #### Required structure (in this order)
 
-1. **`## Linked issue`** — the template header, used instead of a bare close-line. Single `Refs [$TICKET_ID](https://linear.app/...)` link plus, if relevant, links to any prerequisite or follow-up PRs and the Linear tickets they close. Keep it short — three lines max.
+1. **`## Linked issue`** — the template header, used instead of a bare close-line. The template asks for a GitHub issue here; a maintainer PR puts the Linear ticket in the same place: a single `Refs [$TICKET_ID](https://linear.app/...)` link, plus `Fixes #N` as well when a GitHub issue exists, plus links to any prerequisite or follow-up PRs and the Linear tickets they close. Keep it short — three lines max.
+
+   **`## Skill update`** — name the agent skill the change teaches. Reserve `n/a — internal only` for changes that are purely internal or a refactor with no user-visible delta; a user-facing change that teaches no existing skill still needs a sentence saying why no update is required. The template checklist asks you to confirm this section, so a body without it cannot tick that box truthfully.
 
 2. **`## At a glance`** — a copy-pasteable code sample from real code in the branch (not invented, not pseudocode) that demonstrates the change in user-observable terms. Below the code, one short sentence that grounds the "before" state if relevant.
 
@@ -125,7 +127,7 @@ Read `.github/PULL_REQUEST_TEMPLATE.md` once before drafting. The template's req
 
 #### Drafting workflow
 
-1. Run the `.agents/skills/drive-pr-walkthrough/SKILL.md` workflow for the current branch vs base (default: `origin/main...HEAD`) and write `walkthrough.md` to disk. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it.
+1. Run the `drive-pr-walkthrough` skill for the current branch vs base — `"$BASE_BRANCH...HEAD"` with the `BASE_BRANCH` resolved in Step 1, falling back to `"origin/$BASE_BRANCH...HEAD"` exactly as Step 1's commands do (`main...HEAD` when `BASE_BRANCH` resolves to the default) — and write `walkthrough.md` to disk. That skill lives in [prisma/ignite](https://github.com/prisma/ignite), not in this repo. If it is not installed, either install it with `npx skills add prisma/ignite/skills/.pilot --skill '*'` (the command the root `CLAUDE.md` documents) or derive the walkthrough from the diff yourself. The walkthrough provides raw material — narrative steps, behavior changes, evidence links — but its default section order is **not** the PR shape. You will restructure it.
 2. Write the PR body to disk as a working file (e.g. `wip/pr-<num>-body.md`) following the **Required structure** above. Reuse the walkthrough's narrative, behavior bullets, and evidence links where they fit; restructure to lead with the code sample and the decision, and to end with alternatives.
 3. **Adjust links for GitHub**:
    - Keep helpful link text (file paths, optionally line ranges).