release-changelog

name	release-changelog
description	Use this skill when the user runs "/release-changelog", asks to "generate a release changelog", "write release PR description", "build preview links for release", or wants to summarize all docs changed in a release PR as a grouped list of links.
version	1.2.0

Release Changelog Skill

Generates a grouped, formatted changelog of new and updated docs for a Kong Gateway release. New docs are listed as-is; updated docs include a description of what changed, derived from the git diff. Saves to docs/release-changelog/{VERSION}.md.

Invocation

/release-changelog <VERSION> [BASE_BRANCH]

• VERSION — release version number (e.g. 3.14). Used as the filename when saving.
• BASE_BRANCH — branch to diff from (default: main).

Step-by-Step Instructions

1. Check current branch

Run:

git branch --show-current

If the branch name does not look like a release branch (e.g. release/3.14, release-3.14, feat/3.14-docs, or similar), warn the user:

Warning: current branch is {branch} — this may not be the release branch. The changelog will reflect all differences from main on this branch. Continue anyway or switch branches first.

Then proceed.

2. Get new vs updated files

Run both of these. Capture both .md page files and .yaml example files, excluding _includes and assets:

# Newly added files
git diff origin/main --name-only --diff-filter=A \
  | grep '^app/' \
  | grep -v '^app/_includes/' \
  | grep -v '^app/assets/' \
  | grep -E '\.(md|yaml)$'

# Modified existing files
git diff origin/main --name-only --diff-filter=M \
  | grep '^app/' \
  | grep -v '^app/_includes/' \
  | grep -v '^app/assets/' \
  | grep -E '\.(md|yaml)$'

If the user specified a different base branch, replace origin/main accordingly.

If both return nothing, fall back to git diff HEAD~1 --name-only with the same filters.

Keep the two lists separate — added files go under ## New docs, modified files go under ## Updated docs.

3. For each MODIFIED file — read the diff to understand what changed

This is the most important step for updated files. For each modified page file, run:

git diff origin/main -- <file>

From the diff output, extract:

• New headings: lines matching ^\+#{1,4}\s+ — these are new sections added to the page
• Removed headings: lines matching ^\-#{1,4}\s+ — sections removed
• Significant new content blocks: large additions that indicate a new feature, example, or reference was documented
• Frontmatter changes: if title changed, note the rename

Use this to write a short, specific annotation for the link, e.g.:

• — new section: Conditional plugin execution
• — new section: AI Plugin Partials
• — new examples: token exchange
• — updated: supported algorithms list (SHA1 removed)
• — new section: ACL evaluation logic

The annotation should describe the feature, not the file change. "New section: Conditional plugin execution" is good. "File updated" is useless.

If the diff is large and adds multiple distinct things, list them:

• — new sections: Token Exchange, Consumer Claims

If the diff is noise (e.g. only whitespace, formatting, or frontmatter version bumps), skip annotation or write — minor updates.

4. For ADDED files — no diff annotation needed

New files speak for themselves. List them with just the title and link, grouped by feature. Optionally add a one-line description from the frontmatter description field if it's useful context.

5. Read metadata for each file

For .md page files, read YAML frontmatter for:

• title — link text
• permalink — canonical URL path
• description — optional context for new files

For .yaml example files (under _kong_plugins/{plugin}/examples/), read the top-level YAML fields directly (no frontmatter delimiters):

• title — link text. If absent, derive from filename (replace hyphens with spaces, title-case)
• URL is always derived from path: app/_kong_plugins/{plugin}/examples/{name}.yaml → /plugins/{plugin}/examples/{name}/

If permalink is missing, derive from path:

• app/_how-tos/*/foo.md → /how-to/foo/
• app/_kong_plugins/foo/index.md → /plugins/foo/
• app/_kong_plugins/foo/examples/bar.md → /plugins/foo/examples/bar/
• app/_gateway_entities/foo.md → /gateway/entities/foo/
• app/gateway/foo.md → /gateway/foo/
• app/ai-gateway/foo.md → /ai-gateway/foo/
• app/mesh/foo.md → /mesh/foo/
• app/kic/foo.md → /kic/foo/
• app/_landing_pages/foo.yaml → read permalink field inside the file
• app/_references/foo.md → read permalink field

6. Handle auto-generated reference files

Files under app/_references/gateway/pdk/ or app/_references/gateway/cli/ are auto-generated version bumps. Do not list them individually. Add a single line at the bottom of the output:

_Auto-generated references updated: [Gateway CLI Reference](URL), [PDK Reference](URL)_

7. Handle bulk include-driven changes

If 5+ plugin index.md files were all modified and trace back to the same _includes partial change (e.g. all logging plugins changed when log-custom-fields-by-lua.md was modified), collapse them to a single inline list with a parenthetical note:

**Logging plugins** (updated for custom log fields): [File Log](URL), [HTTP Log](URL), ...

For other cases where a plugin index changed because of an include, still include the link but annotate with what the include change means to the reader, not the implementation detail.

8. Construct live URLs

https://developer.konghq.com{permalink}

9. Group the links

Group by product/feature area. Use the feature or capability as the group name, not the file type.

Grouping rules:

• AI Gateway — ai-gateway/ files, _kong_plugins/ai-*/, AI how-tos. Sub-group by feature (A2A, providers, guardrails, semantic, MCP, partials).
• Kong Gateway — gateway/ pages, entities, non-AI plugins, gateway how-tos
• OIDC plugin — always under Kong Gateway, not AI Gateway. Files: _kong_plugins/openid-connect/, OIDC how-tos
• MCP — MCP plugin docs and how-tos
• Observability — observability/ pages
• Konnect — catalog/, Dev Portal, and Konnect-specific content
• Changes — gateway/breaking-changes* always its own section at the end

Nesting: if multiple files relate to the same feature, group under a named parent with sub-bullets:

**Ollama provider:**
* [Ollama provider reference](URL)
* [How-to: Set up AI Proxy with Ollama](URL)

10. Output format

## New and updated docs for the [VERSION] release

## New docs

### [Product/Feature Area]

**[Feature name]:**
* [Link text](URL)
* [Link text](URL)

### [Another area]
* [Link text](URL)

---

## Updated docs

### [Product/Feature Area]

**[Feature name]:**
* [Link text](URL) — new section: Feature Name
* [Link text](URL) — updated: specific thing that changed

### [Another area]
* [Link text](URL) — description of change

_Auto-generated references updated: [Gateway CLI Reference](URL), [PDK Reference](URL)_

## Changes
* [Breaking changes, deprecations, and known issues](URL)

Rules:

• ## New docs — added files only
• ## Updated docs — modified files, each with a change annotation
• ## Changes — breaking changes page only, always last
• Annotations use em dash: — description
• Skip annotation only if the diff is pure noise (whitespace, version bumps)

11. Save the changelog

Write output to docs/release-changelog/{VERSION}.md. Create the directory if needed.

12. Handle missing context

If the user pastes an existing PR description or list of PRs, use it to supplement grouping decisions and identify anchors to append to URLs.

Notes

• Always prefer frontmatter permalink over path-derived URLs
• How-tos: app/_how-tos/{product}/{name}.md → /how-to/{name}/ (product subdir is NOT in the URL)
• Plugin examples: app/_kong_plugins/{plugin}/examples/{name}.md → /plugins/{plugin}/examples/{name}/
• OIDC is a Kong Gateway plugin, not an AI Gateway plugin — always group it under Kong Gateway
• Breaking changes go under ## Changes, never under new or updated docs
• Production base URL: https://developer.konghq.com