skills: add content-write-changelog, the skill that writes the changelog entry

.claude/skills/README.md

@@ -1,6 +1,6 @@
 # Skills
 
-Local skills for this repo. They help you write blog posts, create blog cover images, and write documentation in a consistent style.
+Local skills for this repo. They help you write blog posts, create blog cover images, write documentation, and write the changelog in a consistent style.
 
 ## How skills work
 
@@ -15,6 +15,7 @@ A skill is a folder with a `SKILL.md` (the instructions) and sometimes `referenc
 |-------|-----------|-----------------|
 | [`content-write-blog`](content-write-blog/SKILL.md) | Scaffold a new Prisma blog post (frontmatter + section stubs) | "Draft a blog post about connection pooling" |
 | [`content-create-hero-image`](content-create-hero-image/SKILL.md) | Generate a post's hero (SVG) and social/OG image (PNG) in the Eclipse house style | "Create a cover image for my Compute post" |
+| [`content-write-changelog`](content-write-changelog/SKILL.md) | Write the entry for prisma.io/changelog from everything that shipped since the last one, and open the pull request | "Write this month's changelog" |
 | [`docs-writer`](docs-writer/README.md) | Write or rewrite developer docs (how-to, concept, reference) | "Write a how-to for deploying to Prisma Compute" |
 | [`docs-reader-review`](docs-reader-review/SKILL.md) | Check a written page reads for an ordinary user: banned-jargon, staccato, and AI-signs checks, then a fresh reviewer reads it cold and marks what it cannot follow | "Reader review this page" |
 | [`docs-reader-review/scripts/check-ai-signs.sh`](docs-reader-review/scripts/check-ai-signs.sh) | Runs in CI (`docs-prose.yml`) on every hand-written docs page a pull request adds or changes (the generated ORM and CLI error-reference pages are skipped; their text is fixed upstream); its word list is dated in `references/ai-writing-signs.md` and needs re-checking against Wikipedia's [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) about every six months | "Update the AI-signs word list" |
@@ -51,6 +52,21 @@ Generates a `hero` (editable SVG) plus a pixel-exact `meta` (Open Graph PNG) for
 
 For the render to use the real brand fonts, the bundled `assets/fonts/` is used automatically. See [`content-create-hero-image/README.md`](content-create-hero-image/README.md) for tooling details.
 
+## content-write-changelog
+
+Writes the entry for [prisma.io/changelog](https://www.prisma.io/changelog) and opens the pull request. It gathers what merged since the last entry, keeps only what a user can see and what is already released, and explains each change from the reader's side, with the most impactful change at the top.
+
+**How to use:**
+
+1. Ask for the changelog ("write this month's changelog"). The window starts at the newest entry in `apps/site/content/changelog/`.
+2. It lists the merged pull requests across the Prisma repositories with the `gh` CLI, then reads the release notes and the docs for the candidates it keeps. You need access to the Prisma organization for the private repositories, or the entry covers the public ones only.
+3. It writes `apps/site/content/changelog/{date}.mdx` and adds screenshots to `apps/site/public/changelog/`.
+4. It runs `content-write-changelog/scripts/check-entry.mjs`, which checks the frontmatter, compiles the MDX, and checks every link and anchor against production.
+5. It runs the `docs-reader-review` checks and has a fresh reviewer read the entry cold, so that the entry explains each change instead of listing it the way a spec would.
+6. It opens a pull request whose body lists everything it held back or excluded, with a reason for each. You review, edit, and merge.
+
+The skill reads the same positioning doc as `content-write-blog`, from the **prisma/ignite** repository. Its rules live in four short references: [gathering](content-write-changelog/references/gathering.md), [filtering](content-write-changelog/references/filtering.md), [voice](content-write-changelog/references/voice.md), and [structure](content-write-changelog/references/structure.md).
+
 ## docs-writer
 
 Writes or rewrites developer-facing documentation a reader can follow without getting stuck. Covers how-to, concept, and reference pages.

.claude/skills/content-write-changelog/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: content-write-changelog
+description: Use when the operator asks to write, generate, or publish a changelog entry for prisma.io/changelog, says "this week's changelog" or "this month's changelog", asks what shipped since the last entry, or asks to open the changelog pull request.
+metadata:
+  author: Prisma
+  version: "2026.10.2"
+---
+
+# Write the changelog entry
+
+Turn everything that shipped since the last entry into one dated MDX file at `apps/site/content/changelog/{YYYY-MM-DD}.mdx`, plus a triage note that lists every candidate you left out and why. Then open a pull request for humans to review. This skill never merges.
+
+The reader is a working developer with no time. In a ten-second scan the entry must answer three questions: what can I do now, what stopped hurting, and do I have to act.
+
+## Pre-conditions
+
+Stop and tell the operator if one of these is missing.
+
+1. **A checkout of this repo**, synced with the default branch. Work on a new branch or worktree, never on a branch that carries someone's unfinished work.
+2. **The `gh` CLI, signed in** with access to the Prisma organization. Much of the platform is built in private repositories. Without access to them the entry covers the public repositories only, and you must say so in the pull request.
+3. **The positioning doc**, read before you write a product claim. The authoritative copy is `docs/prisma/positioning.md` in the `prisma/ignite` repository, the same source `content-write-blog` uses. There is no copy in this repo. If you cannot read it, ask the operator for the current product names and maturity labels.
+
+## Rules that always apply
+
+- **Outcome first, product named in the same sentence.** The title, the opening paragraph, and the first sentence of each section lead with what the reader can now do and name the product. Write "You can now enroll a coding agent in Prisma with a credential of its own", not "Agent enrollment is now available".
+- **Explain, do not state.** A changelog written from pull request titles reads like a spec. Say what each change means for the reader, in sentences a person would say aloud, with the "so" and "because" left in. `references/voice.md` and the `docs-reader-review` skill describe how.
+- **Publish what the user can see, wherever the code lives.** A Console workflow, a CLI command, a REST API route, or a docs page is publishable even when its code is private. Describe the effect and link a public docs page, or link nothing. Never link a private pull request and never name a private repository.
+- **Only what is released.** A merged pull request is not a shipped feature. Check each product's release before you write about it, as described in `references/gathering.md`.
+- **Every claim has a source you have read.** Use a public one wherever it exists: a release note, a docs page, a blog post, or a public pull request. A change built in a private repository often has none yet. In that case the merged pull request is your source, the entry describes the effect without a link, and the item goes into the triage note as "no public PR" so that a reviewer confirms it in the product before the entry is merged. Quote dates, limits, and prices from the source and never from memory.
+- **Full product names on every mention**, as the positioning doc spells them. Check the name and the maturity of each product against the docs when you write, because both change between entries.
+- **Most impactful first, at every level.** The title is the biggest change. The headline sections, the bullets in a section, the actions a reader must take, and the fixes are each ordered by how many readers they reach and how much they change.
+- **Never pad.** A window with a few fixes gets a short entry with no headline sections. A window with nothing user-facing gets no entry, and you report that instead.
+- **No em dashes, no emoji, no vague adjectives, and no vocabulary from the source code.** State the behavior the reader will observe, in words the reader already has.
+
+## Workflow
+
+1. **Set the window.** The window starts at the newest entry in `apps/site/content/changelog/` and ends today. Read that entry in full: its structure is the precedent, and the pull requests it links mark where the window starts.
+   Done when you can name the start date, the end date, and the last pull request already covered.
+2. **Gather.** Collect the merged pull requests, the releases, the new docs pages, and the new blog posts for the window, following `references/gathering.md`.
+   Done when every source in that file has been read or reported as unreachable.
+3. **Gate.** Give each candidate one verdict from `references/filtering.md`: publish, rewrite, flag, or exclude. When unsure, flag.
+   Done when every candidate has a verdict and every flag and exclusion has a one-line reason.
+4. **Confirm.** For each candidate you keep, find the public source, check that it is released, and note the docs page that documents it.
+   Done when no kept item rests on a pull request title alone.
+5. **Write.** Read `references/voice.md` and the three `docs-reader-review` references it names, then draft the entry in the order `references/structure.md` gives.
+   Done when the frontmatter is valid, `slug` equals `date`, and the date is the day the entry lands.
+6. **Check.** Run `node .claude/skills/content-write-changelog/scripts/check-entry.mjs apps/site/content/changelog/{YYYY-MM-DD}.mdx --links`. Then run the three scripts in `.claude/skills/docs-reader-review/scripts/` on the same file: `check-plain.sh`, `check-staccato.py`, and `check-ai-signs.sh`. The closing `---` before the Enterprise line is the one hit `check-ai-signs.sh` is expected to report.
+   Done when the scripts report nothing else.
+7. **Have it read cold.** Give the entry to a fresh reviewer, as the `docs-reader-review` skill describes, and rewrite every sentence it could not restate. Repeat with a new reviewer until a round reports no sentence it could not restate and no word it had to guess. Then check every rewritten sentence against its source again, because rewriting drifts meaning.
+   Done when a round comes back clean, the facts have been checked again, and you have gone through the checklist below.
+8. **Open the pull request.** Create the branch `changelog/{YYYY-MM-DD}`, commit the entry and its images as `docs(site): add changelog entry {YYYY-MM-DD}`, push, and open the pull request with the body in `references/structure.md`. If an entry for that date already exists, ask the operator whether to replace it or pick another date.
+   Done when the pull request is open and its body carries the triage note.
+9. **Report and stop.** Give the operator the pull request link, the items that need a human decision, and anything you could not verify. Do not merge and do not enable auto-merge.
+
+## Checklist before you open the pull request
+
+- [ ] The title leads with a user action or outcome and names the product. It has no `Prisma:` prefix, no version number, and no chain of features joined by semicolons.
+- [ ] The opening paragraph states the biggest change in its first sentence, and names every date the reader must act on.
+- [ ] There are at most three headline sections, each one changes what a reader can do, and each heading states an outcome or an action.
+- [ ] The most impactful item comes first in the entry, in every section, and in every list.
+- [ ] "What you need to do" exists whenever a reader has to act, with one bullet per audience.
+- [ ] Every breaking change says what to change. Every deprecation names the old surface, the replacement, and the date.
+- [ ] Every documented surface links its docs page, and every link and anchor was checked against production.
+- [ ] Every technical identifier is in backticks, and every term a reader of the previous version would not know is replaced or explained where it first appears.
+- [ ] Headline sections and short product sections are paragraphs. Lists are used only for items the reader scans.
+- [ ] Bold appears on the first sentence, on interface labels, on dates that need action, and on the first sentence of items in a scanned list, and nowhere else.
+- [ ] No private pull request links, no private repository names, no internal names, no issue-tracker IDs, no customer names, and no description of how a security problem worked.
+- [ ] No CI, dependency, refactor, test, SEO, or analytics items.
+- [ ] Every image has alt text that describes what the screenshot shows.
+- [ ] Every blog and guide link carries one sentence taken from what the page says, not from its title.
+- [ ] The triage note lists every flagged and excluded candidate, including the ones with no public pull request.
+
+## Reference
+
+- `references/gathering.md`: where the changes come from, and how to tell merged from released.
+- `references/filtering.md`: the verdicts, and the rules for private repositories, unreleased work, and security fixes.
+- `references/voice.md`: how to turn a pull request into a sentence a reader can use.
+- `references/structure.md`: frontmatter, section order, components, images, and the pull request body.
+- `scripts/check-entry.mjs`: checks the frontmatter, the MDX, the images, and the links.
+- The two newest entries in `apps/site/content/changelog/` are the samples. Match their shape before you match this document.

.claude/skills/content-write-changelog/references/filtering.md

@@ -0,0 +1,90 @@
+# Filtering: what reaches the public changelog
+
+Run this on every candidate, including the ones that sit under a product heading in someone else's summary. Give each candidate exactly one verdict. When you are unsure, flag it. Every flag and every exclusion goes into the triage note with a one-line reason, so nothing is dropped silently.
+
+## The baseline test
+
+A changelog records what changed for the user, not how the team worked.
+
+Include user-visible behavior changes, new capabilities, fixes a reader would notice, performance gains stated as an effect, breaking changes, deprecations, and retirements.
+
+Exclude dependency bumps with no user effect, refactors, CI and build changes, repository configuration, test-only changes, and changes to internal documentation.
+
+## The four verdicts
+
+### Publish, or rewrite
+
+Publish a shipped change to a public product as it is. Rewrite a change that carries a real benefit wrapped in internal detail: strip the detail and keep the effect.
+
+### Flag
+
+Pull the item from the entry and list it for a human decision when:
+
+- you cannot confirm that the capability is public, for example a feature that is rolling out, limited to eligible accounts, or switched on by a flag
+- it touches pricing, plan limits, a launch date, or a maturity label, and no public page states it
+- it reverts something an earlier entry announced
+- it is a fix with no user-visible change you can name
+- you are not sure
+
+### Exclude
+
+Never publish:
+
+- **Internal names.** Codenames, internal tools, internal agents, and anything that is not in the public product vocabulary.
+- **Internal references.** Issue-tracker IDs, chat channels, dashboards, and internal links.
+- **Internal process.** CI, builds, dependency bumps, repository configuration, SEO, analytics, consent, and tracking.
+- **Implementation detail.** Which vendor, model, or runtime powers a feature, how the infrastructure is laid out, and how a rollout is staged.
+- **Security mechanics.** How a vulnerability worked, what a credential looks like, and how tokens are checked.
+- **People and customers.** Customer names, support-ticket details, and the names or email addresses of individuals.
+
+## The strip test
+
+Remove the internal detail from a line and look at what is left.
+
+- Nothing a reader can use: exclude.
+- A real benefit: rewrite it as user value.
+- You cannot tell: flag.
+
+## Changes from private repositories
+
+Much of the platform is built in private repositories. Whether the repository is public does not decide the verdict. Whether the user can see the change does.
+
+Publish a Console workflow, a CLI command, a REST API route, a platform behavior, or a docs page. Describe what the user sees, link a public docs page when one exists, and otherwise link nothing. Add the item to the triage note as "no public PR".
+
+Exclude work that stays internal even though the product is public: how builds run, how a rollout is staged, where a service is hosted, and observability plumbing.
+
+Never link a private pull request. The link returns 404 for readers and gives away the repository name.
+
+## Products that are not generally available
+
+A product in Early Access or in release candidates often has a public repository full of internal engineering. Apply the test to each line, not to the repository.
+
+Publish a change that alters what a user can do or see: a new capability in the schema, a CLI command or flag, an editor feature, a query API addition, or a support policy. Keep the wording to what the release notes say.
+
+Exclude parser and compiler rewrites, internal type machinery, project close-outs, and architecture records.
+
+State the product's maturity once per entry, in the wording the docs use today. A change to a product before its public launch is not publishable.
+
+## Guides and articles
+
+Blog posts and docs guides are written for users, so list them. Link the published page and never the pull request that added it.
+
+Skip a post about an internal tool. Skip site mechanics such as redirects, metadata, images, and copy tweaks.
+
+A guide that is the main reference for a feature covered above is linked there, not repeated in the list.
+
+## Security fixes
+
+State the outcome, not the exploit. "Connection strings are now redacted from error logs" is publishable. The code path that leaked them is not.
+
+A dependency update that resolves a published advisory can be one neutral line. Name the advisory only if the public pull request already does.
+
+When in doubt, flag the item for a security reviewer.
+
+## Incidents
+
+A fix that follows an incident is published as the fix. Leave out the incident, the dates, the number of customers affected, and the cause.
+
+## People and customers
+
+Replace a named customer with a neutral phrase. "Fixed a replication lag issue reported by Acme" becomes "Fixed a replication lag issue that affected some databases".