chore: add release notes skill

.agents/skills/create-draft-release-notes/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: create-draft-release-notes
+description: Create or update draft GitHub releases for the current project's main GitHub repository, then organize GitHub-generated release notes into user-friendly sections without rewriting release note items. Use for preparing, formatting, categorizing, creating, or updating GitHub release notes or draft releases.
+---
+
+# Create Draft Release Notes
+
+## Overview
+
+Create a GitHub draft release, organize the generated notes by conventional commit type, and save the organized body back to the draft. Preserve each release note item exactly; only split accidentally joined bullets, move bullets into sections, and adjust headings.
+
+## Draft Release Workflow
+
+Input: a release tag/title such as `v2.0.6`. If title and tag differ, ask for the tag.
+
+1. Resolve `repo` as `<owner>/<repo>`.
+   Prefer an explicit repo from the user. Otherwise infer the current project's main GitHub repository from project metadata or the current GitHub remote. For npm projects, `package.json` `repository` is a useful signal; in monorepos, inspect the package or project being released rather than assuming the workspace root. Ignore subdirectory metadata such as `repository.directory` because GitHub releases are repository-level. If the repo is ambiguous, ask.
+
+2. Set variables:
+
+   ```bash
+   repo="<owner>/<repo>"
+   release_tag="v2.0.6"
+   release_title="$release_tag"
+   ```
+
+3. Verify access and ensure the release does not already exist:
+
+   ```bash
+   gh auth status
+   gh repo view "$repo" --json nameWithOwner --jq '.nameWithOwner'
+   gh release view "$release_tag" -R "$repo" --json tagName,isDraft,url
+   ```
+
+   If the release exists, stop unless the user explicitly asked to update that draft.
+
+4. Infer the previous tag:
+
+   ```bash
+   previous_tag="$(gh release list -R "$repo" --exclude-drafts --exclude-pre-releases --limit 1 --json tagName --jq '.[0].tagName')"
+   gh release list -R "$repo" --exclude-drafts --exclude-pre-releases --limit 5
+   ```
+
+   Ask for confirmation if the previous tag is missing, surprising, or part of a non-standard range.
+
+5. Before creating anything, state the repo and range: `previous_tag -> release_tag`. If the user did not explicitly ask to create the draft in this turn, ask for confirmation.
+
+6. Create the draft with GitHub-generated notes:
+
+   ```bash
+   gh release create "$release_tag" -R "$repo" --draft --generate-notes --notes-start-tag "$previous_tag" --title "$release_title"
+   ```
+
+   Add `--verify-tag` when the release must use an existing remote tag.
+
+7. Organize and save the draft body:
+
+   ```bash
+   tmp_dir="$(mktemp -d)"
+   gh release view "$release_tag" -R "$repo" --json body --jq '.body' > "$tmp_dir/generated.md"
+   node .agents/skills/create-draft-release-notes/scripts/create-draft-release-notes.mjs "$tmp_dir/generated.md" > "$tmp_dir/organized.md"
+   gh release edit "$release_tag" -R "$repo" --draft --title "$release_title" --notes-file "$tmp_dir/organized.md"
+   ```
+
+8. Return the draft URL:
+
+   ```bash
+   gh release view "$release_tag" -R "$repo" --json url --jq '.url'
+   ```
+
+## Markdown-Only Workflow
+
+Use this when the user provides generated release note Markdown and only wants it organized:
+
+```bash
+node .agents/skills/create-draft-release-notes/scripts/create-draft-release-notes.mjs release-notes.md
+```
+
+Omit the file path to read from stdin. Review that every original item still appears once and non-item sections remain.
+
+## Categories
+
+Emit non-empty sections in this order:
+
+1. `### Breaking Changes 🍭`
+2. `### New Features 🎉`
+3. `### Performance 🚀`
+4. `### Bug Fixes 🐞`
+5. `### Refactor 🔨`
+6. `### Document 📖`
+7. `### Other Changes`
+
+Classify by the item prefix:
+
+- Breaking Changes: `type!:` or `type(scope)!:`, plus `breaking:` / `break:`.
+- New Features: `feat:` / `feat(scope):`, plus `feature:`.
+- Performance: `perf:`.
+- Bug Fixes: `fix:`.
+- Refactor: `refactor:`.
+- Document: `docs:` / `docs(scope):`, plus `doc:`.
+- Other Changes: everything else.
+
+Keep each category in generated top-to-bottom order.
+
+## Preservation Rules
+
+- Do not rewrite bullet text, authors, URLs, PR numbers, package names, scopes, punctuation, or casing.
+- Do not drop comments, `**Full Changelog**`, or other non-item sections.
+- Do not add commentary to the release note itself.
+- Do not emit empty category sections.
+
+## Resources
+
+- `scripts/create-draft-release-notes.mjs`: deterministic formatter for generated release note Markdown.

.agents/skills/create-draft-release-notes/scripts/create-draft-release-notes.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { argv, stdin, stdout, stderr } from 'node:process';
+
+const categories = [
+  ['breaking', '### Breaking Changes 🍭'],
+  ['feat', '### New Features 🎉'],
+  ['perf', '### Performance 🚀'],
+  ['fix', '### Bug Fixes 🐞'],
+  ['refactor', '### Refactor 🔨'],
+  ['docs', '### Document 📖'],
+  ['other', '### Other Changes'],
+];
+
+const typeMap = {
+  feat: 'feat',
+  feature: 'feat',
+  perf: 'perf',
+  fix: 'fix',
+  refactor: 'refactor',
+  docs: 'docs',
+  doc: 'docs',
+};
+
+const itemRE = /^[*-]\s+([a-zA-Z]+)(?:\([^)]+\))?(!)?:\s+/;
+const joinedItemRE = /(?<!^)(?=\*\s+[a-zA-Z]+(?:\([^)]+\))?!?:\s+)/g;
+
+async function readMarkdown(input) {
+  if (input && input !== '-') {
+    return readFile(input, 'utf8');
+  }
+
+  let markdown = '';
+  stdin.setEncoding('utf8');
+
+  for await (const chunk of stdin) {
+    markdown += chunk;
+  }
+
+  return markdown;
+}
+
+function classify(item) {
+  const match = itemRE.exec(item);
+
+  if (!match) {
+    return 'other';
+  }
+
+  const type = match[1].toLowerCase();
+
+  if (match[2] === '!' || type === 'breaking' || type === 'break') {
+    return 'breaking';
+  }
+
+  return typeMap[type] ?? 'other';
+}
+
+function organize(markdown) {
+  const heading = /^##\s+What's Changed\s*$/m.exec(markdown);
+
+  if (!heading) {
+    throw new Error("Could not find a `## What's Changed` section.");
+  }
+
+  const bodyStart = heading.index + heading[0].length;
+  const afterHeading = markdown.slice(bodyStart);
+  const nextSection = /^(?:##\s+|\*\*Full Changelog\*\*:)/m.exec(afterHeading);
+  const bodyEnd = nextSection ? bodyStart + nextSection.index : markdown.length;
+  const grouped = Object.fromEntries(categories.map(([key]) => [key, []]));
+  const preserved = [];
+
+  for (const rawLine of markdown.slice(bodyStart, bodyEnd).split('\n')) {
+    for (const line of rawLine.split(joinedItemRE)) {
+      const trimmed = line.trim();
+
+      if (!trimmed || trimmed.startsWith('### ')) {
+        continue;
+      }
+
+      if (trimmed.startsWith('* ') || trimmed.startsWith('- ')) {
+        grouped[classify(trimmed)].push(trimmed);
+      } else {
+        preserved.push(line);
+      }
+    }
+  }
+
+  const lines = preserved.filter((line) => line.trim());
+
+  for (const [key, title] of categories) {
+    if (grouped[key].length > 0) {
+      lines.push(title, ...grouped[key]);
+    }
+  }
+
+  if (lines.length === 0) {
+    return markdown;
+  }
+
+  const prefix = markdown.slice(0, bodyStart).trimEnd();
+  const suffix = markdown.slice(bodyEnd).replace(/^\n+/, '');
+
+  return suffix
+    ? `${prefix}\n${lines.join('\n')}\n\n${suffix}`
+    : `${prefix}\n${lines.join('\n')}\n`;
+}
+
+try {
+  if (argv.length > 3) {
+    throw new Error('Usage: create-draft-release-notes.mjs [release-notes.md]');
+  }
+
+  stdout.write(organize(await readMarkdown(argv[2])));
+} catch (error) {
+  stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

CONTRIBUTING.md

@@ -97,4 +97,4 @@ Repository maintainers can publish new versions of changed packages.
 3. Open a pull request with a title like `release: 0.7.10` or `release: @rstest/coverage-istanbul 0.1.7` and ensure CI passes.
 4. Trigger the [release action](https://github.com/web-infra-dev/rstest/actions/workflows/release.yml) to publish packages to npm.
 5. Merge the release pull request to `main`.
-6. Create a GitHub Release for the merged commit so GitHub generates release notes and creates the version tag.
+6. Use the `create-draft-release-notes` skill to create a draft [GitHub release note](https://github.com/web-infra-dev/rstest/releases). Review the draft release note, optionally add release highlights, and publish it.

knip.jsonc

@@ -7,7 +7,13 @@
   "ignoreExportsUsedInFile": true,
   "workspaces": {
     ".": {
-      "entry": ["cspell.config.cjs", "rslint.config.mts"],
+      "entry": [
+        "cspell.config.cjs",
+        "rslint.config.mts",
+        // Agent skill scripts are invoked by the skill runtime, not imported by source files.
+        ".agents/skills/**/scripts/**/*.mjs",
+        ".claude/skills/**/scripts/**/*.mjs",
+      ],
     },
     "benchmarks": {
       "entry": [

skills-lock.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "skills": {
+    "create-draft-release-notes": {
+      "source": "rstackjs/agent-skills",
+      "sourceType": "github",
+      "skillPath": "skills/create-draft-release-notes/SKILL.md",
+      "computedHash": "72a427134af52e91cbba9bc55f9926cadd8f5bedf48d654952697f08d540e7bb"
+    }
+  }
+}