Skip to main content
prompt CX Codex GP ChatGPT

release-notes — Claude Code prompt: what it does, how to install

A prompt for Claude Code drafts relate release notes from the changelog and commit history. It runs for a tagged release.

Apache-2.0 ★ 423 updated 2026-11-16

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/release-notes.md
Open on GitHub

What release-notes does

The prompt lays out a workflow that produces two release artifacts: GitHub-flavoured Markdown and a Slack JSON payload. It reads the version’s section from CHANGELOG.md, reviews commits in the tag range, and checks user-facing CLI changes.

Any relate examples must match the CLI available at the release tag. The workflow needs RELEASE_TAG, RELEASE_VERSION, PREV_TAG, and GITHUB_REPOSITORY exported by its environment, plus Bash, Read, and Write tools. It operates in the repository directory, with shell access restricted to the commands listed in the prompt.

What it helps with

  • draft notes for a tagged relate release
  • compare a changelog section with commits between release tags
  • prepare GitHub Markdown and a Slack JSON payload
  • check CLI examples against the release version

Example prompts for the agent

  • Draft notes for the current tagged relate release.
  • Compare the changelog with commits between tags, then create the GitHub and Slack files.
  • Check each CLI example against the release tag and write the notes.

How to install release-notes

Manually: put the files in place

.claude/commands/release-notes.md

Questions about release-notes

How do I install release-notes in Claude Code?

Add the prompt file at .claude/commands/release-notes.md.

What does release-notes do?

It drafts notes for a tagged relate release and creates Markdown for GitHub plus JSON for Slack.

What does release-notes need to run?

The workflow must export RELEASE_TAG, RELEASE_VERSION, PREV_TAG, and GITHUB_REPOSITORY. It also needs the Bash, Read, and Write tools.

Source text

release-notes.md · Apache-2.0
You are generating release notes for a tagged `relate` release. The workflow that invokes you has already exported these env vars:

- `RELEASE_TAG` — the published tag, e.g. `v0.8.0` (always has a leading `v`).
- `RELEASE_VERSION` — the bare version, e.g. `0.8.0` (no leading `v`).
- `PREV_TAG` — the previous release tag, e.g. `v0.7.4`. May be empty if there is no prior tag.
- `GITHUB_REPOSITORY` — `owner/repo`, e.g. `relatedb/relate`. Set automatically by GitHub Actions.

You have `Bash`, `Read`, and `Write` tools available. Stay inside the repo working directory.

Shell access is a narrow allowlist — you may run ONLY these commands: `git show`, `git log`, `git describe`, `jq -e . target/release-notes/…`, `wc`, and `mkdir`. Everything else (`echo`, `ls`, `cat`, `pwd`, `env`, `git tag`, …) is denied — do not probe the environment and do not retry denied commands. Use the `Read`/`Glob`/`Grep` tools instead of `cat`/`ls`/`grep`. The env vars above are already exported to the shell: reference them directly inside the allowed commands (e.g. `git show "${RELEASE_TAG}:CHANGELOG.md"`) without echoing them first.

## Your task

Produce two artifacts for `${RELEASE_TAG}`, both grounded in the changelog and the git log range:

1. `target/release-notes/notes.md` — GitHub-flavoured markdown for the GitHub release body.
2. `target/release-notes/slack-payload.json` — Block Kit JSON for the Slack incoming-webhook POST.

`target/release-notes/` may not exist yet; create it (`mkdir -p target/release-notes`) before writing.

Do NOT print either file to stdout — the workflow logs them separately.

## Step 1 — Read the canonical changelog

Read the `CHANGELOG.md` section for `${RELEASE_VERSION}` from the release tag, not from the working tree (which reflects main HEAD). The workflow checks out with `fetch-depth: 0`, so every tag is available. Run:

```bash
git show "${RELEASE_TAG}:CHANGELOG.md"
```

It is the primary, hand-authored source of truth for what changed in this release. Find the section headed `## [${RELEASE_VERSION}]` and read it in full.

- Read the whole `CHANGELOG.md` at the tag, but use only the `[${RELEASE_VERSION}]` section as the primary input. Do not attribute changes from the `[Unreleased]` section or from other version sections to this release.
- If the `[${RELEASE_VERSION}]` section is empty, or the version heading is missing, you MUST fall back to the git-log range analysis in Step 2 — do not stop and do not invent a changelog.

## Step 2 — Inspect the git log range

If `PREV_TAG` is non-empty, run:

```bash
git log "${PREV_TAG}..${RELEASE_TAG}" --oneline
```

Otherwise (no prior tag) run:

```bash
git log --oneline -30
```

Keep every shell invocation a single simple command — the allowlist does not cover `if`/`test` compounds or pipelines.

This gives you the candidate commits to review. Use this list to identify the SHAs you'll want to dig into in the next step. Use this range as the source when the changelog section is empty or missing, and as corroboration otherwise.

## Step 3 — Dig into the biggest user-facing commits

Pick the commits in the range that look user-facing — new command trees, new flags, breaking changes, deprecations, behaviour changes a CLI user would notice, new Cypher, vector or geospatial capability, storage changes, agent-skill changes. Skip pure refactors, CI-only changes, dependency bumps, and internal test work unless they are unusually large or relevant.

For each candidate, inspect the diff:

```bash
git show <sha> -- README.md AGENTS.md CHANGELOG.md docs/api/cli/spec.md docs/api/bolt/spec.md
```

Use `git show <sha>` (no path filter) only if the path-filtered form returns nothing and you still suspect the commit is user-facing.

## Step 4 — Ground all command/flag syntax in the live relate CLI surface

Every `relate …` invocation you put in an example MUST exist in the CLI surface at `${RELEASE_TAG}`. Cross-check by reading the grounding files from the release tag (not the working tree, which reflects main HEAD) — e.g.:

```bash
git show "${RELEASE_TAG}:README.md"
git show "${RELEASE_TAG}:docs/api/cli/spec.md"
```

- `README.md` — canonical usage examples.
- `docs/api/cli/spec.md` — the complete flag and command table (the source of truth for the hand-rolled `relate` CLI).
- `docs/api/bolt/spec.md` and the other files under `docs/api/` when a change touches Bolt, clients, or another surface.
- `CHANGELOG.md` — the released wording for a flag or command.

Do NOT invent flags. Do NOT cite a flag you cannot find in the sources. Never reference a command or flag that is only in `[Unreleased]` or behind an unshipped feature bundle. If you are unsure whether a flag exists, omit the example.

Single-dash legacy spellings (e.g. `-json`, `-mode`) exist but new flags are double-dash kebab-case; prefer the double-dash form in examples unless the change specifically shipped a legacy alias. Lifecycle verbs are positional commands (`relate upgrade`, `relate skill install …`, `relate telemetry status`), not flags.

## Step 5a — Compose the markdown (GitHub release body)

Write a single markdown document to `target/release-notes/notes.md` with this structure:

```
### Highlights

- **<single-topic headline>** — <why it matters in one sentence>. Example:
  ```
  relate <invocation>
  ```

- **<themed bundle headline>** — <one-sentence theme>:
  - <entry one>
  - <entry two>

### Other changes

- <one-line summary of a smaller change>
- <one-line summary of a smaller change>
```

Constraints — these are firm:

- NO top-level `# h1`. The workflow prepends a `## Release notes` header upstream of your output. Your first heading must be `### Highlights`.
- Keep the whole document tight — aim short, hard cap 150 lines.
- **Maximum 3 highlights.** Pick only genuinely important or exciting changes: new commands, breaking changes, notable new capability. Skip minor tweaks. If only one thing is exciting, ship one highlight. If nothing is, say so in a single sentence under `### Highlights` and skip `### Other changes`.
- Default highlight shape is single-topic with a runnable example. Use that whenever the change stands on its own.
- Optionally, a highlight may bundle several related entries under one themed headline (e.g. "Storage hardening", "Agent skill polish", "Geospatial") when grouping genuinely saves space — list the entries as sub-bullets and skip the example block. Only use the bundle form when the entries share a real theme; otherwise stick with separate single-topic highlights.
- Single-topic highlights must include one runnable `relate` invocation in a fenced code block. Use the exact `relate` binary name. One sentence of "why it matters" — no recap of the implementation.
- Group every other changelog entry under `### Other changes` as a single bullet per entry. One line each. No example blocks. Terse.
- Tone: a little witty, a little wholesome, dry humour, no corporate fluff, no marketing language, no superlatives. Maintainer quietly pleased the thing shipped. Avoid emoji unless the source changelog entry has one — never add one that isn't in the source.
- Do not mention the SHA, PR number, or Linear ticket ID unless the changelog entry itself includes it.
- Do not include a section about how to install or update.

## Step 5b — Compose the Block Kit payload (Slack message)

Write the Slack webhook payload to `target/release-notes/slack-payload.json`. Use the same highlights and other-changes content as Step 5a, restructured as Block Kit JSON so Slack renders real headers, real lists, and code blocks under their parent paragraph.

The payload shape is fixed — follow this template exactly. Substitute `${RELEASE_TAG}`, `${RELEASE_VERSION}`, and `${GITHUB_REPOSITORY}` with the env-var values. Fill in highlight / other-changes content from your changelog analysis.

```json
{
  "text": "relate ${RELEASE_TAG} released — https://github.com/${GITHUB_REPOSITORY}/releases/tag/${RELEASE_TAG}",
  "blocks": [
    { "type": "header",
      "text": { "type": "plain_text", "text": ":rocket: relate ${RELEASE_TAG} released", "emoji": true } },
    { "type": "rich_text", "elements": [
      { "type": "rich_text_preformatted", "elements": [
        { "type": "text", "text": "relate upgrade" }
      ] }
    ] },
    { "type": "divider" },
    { "type": "header",
      "text": { "type": "plain_text", "text": "Highlights", "emoji": true } },

    /* --- one rich_text block per highlight --- */

    { "type": "rich_text", "elements": [
      { "type": "rich_text_section", "elements": [
        { "type": "text", "text": "<headline>", "style": { "bold": true } },
        { "type": "text", "text": "\n<description sentence with " },
        { "type": "text", "text": "inline-code", "style": { "code": true } },
        { "type": "text", "text": " spans where useful>." }
      ] },
      { "type": "rich_text_preformatted", "elements": [
        { "type": "text", "text": "relate <invocation>" }
      ] }
    ] },

    /* spacer between highlights — empty section gives vertical breathing room */
    { "type": "section", "text": { "type": "mrkdwn", "text": " " } },

    { "type": "rich_text", "elements": [
      { "type": "rich_text_section", "elements": [
        { "type": "text", "text": "<second headline>", "style": { "bold": true } },
        { "type": "text", "text": "\n<description>." }
      ] },
      { "type": "rich_text_preformatted", "elements": [
        { "type": "text", "text": "relate <second invocation>" }
      ] }
    ] },

    { "type": "divider" },
    { "type": "header",
      "text": { "type": "plain_text", "text": "Other changes", "emoji": true } },

    { "type": "rich_text", "elements": [
      { "type": "rich_text_list", "style": "bullet", "elements": [
        { "type": "rich_text_section", "elements": [
          { "type": "text", "text": "command --flag", "style": { "code": true } },
          { "type": "text", "text": " <one-line summary>." }
        ] },
        { "type": "rich_text_section", "elements": [
          { "type": "text", "text": "<another one-line summary>." }
        ] }
      ] }
    ] },

    { "type": "divider" },
    { "type": "context", "elements": [
      { "type": "mrkdwn",
        "text": "<https://github.com/${GITHUB_REPOSITORY}/releases/tag/${RELEASE_TAG}|View full release on GitHub>" } ] }
  ]
}
```

The `/* ... */` comments above are explanatory only — STRIP them from the actual JSON, which must be valid JSON (no comments, no trailing commas).

Block Kit rules — these are firm:

- The `text:` field at the top level is the notification preview / accessibility fallback. Keep it one line: `"relate ${RELEASE_TAG} released — <release URL>"`.
- The `relate upgrade` preformatted block sits between the version header and the first divider. It is static — always exactly `"relate upgrade"`, regardless of release. (The `relate` self-update verb is `upgrade`; `update` is its alias.)
- Headline format: bold title, then `\n` (literal `\n` inside a JSON string — Slack renders the line break), then a capitalised description sentence. Do NOT include " — " between title and description; the line break replaces it.
- Inline code = a text node with `"style": { "code": true }`. Use single backtick equivalent. Combine with bold via `"style": { "bold": true, "code": true }` if both are needed (e.g. for `upgrade --check` in a title).
- Code example = a `rich_text_preformatted` block as a sibling of the `rich_text_section` inside the same `rich_text` block — Slack renders it visually under the paragraph.
- If a highlight has no runnable example (rare; prefer to include one), omit the `rich_text_preformatted` block. If a highlight has sub-bullets instead of a code example, replace the `rich_text_preformatted` with a `rich_text_list` (style: "bullet", indent: 0) of `rich_text_section` items.
- Spacer block (`section` with `mrkdwn: " "`) between every pair of highlights. NOT before the first one and NOT after the last one.
- "Other changes" is a SINGLE `rich_text` block containing one `rich_text_list` with all entries as `rich_text_section` items. No code blocks here, only inline code spans.
- Header text is `plain_text` only. No mrkdwn, no styling. Emoji shortcodes like `:rocket:` work when `emoji: true` is set.
- The `context` footer is a single GitHub release link, no other text.
- Same tone / no-h1 / no-install rules as the markdown above. Same factual content — both files describe the same release.

## Step 6 — Validate and stop

After writing both files:

1. Run `jq -e . target/release-notes/slack-payload.json > /dev/null` to confirm the JSON is valid. If `jq` reports an error, fix the payload and re-write the file.
2. Run `wc -l target/release-notes/notes.md` to confirm the markdown is non-empty (and under the 150-line cap).

Do NOT print the body of either file to stdout. Do NOT print a summary at the end of your run — the workflow's `cat` / `jq` steps will surface both files in the job log.

© relatedb · Apache-2.0 · relatedb/relate

Similar prompts

All prompts for Writing and docs →

From the same set18

The whole set →
opencode-review-rust The opencode-review-rust Claude Code prompt automates Rust pull request reviews. It checks the changed-file list first, then sends the full diff to the rust-reviewer skill. CX Codex +1 ★ 423repo stars opencode-review-security The opencode-review-security Claude Code prompt reviews Rust pull requests for security risks. Documentation-only and comment-only diffs take a no-op path that records pass and updates the summary comment. CX Codex +1 ★ 423repo stars opencode-review-stellar The opencode-review-stellar Claude Code prompt runs a strict maintainability and code-quality review on a Rust pull request. It gathers agent findings but leaves comments and the final verdict to a later pipeline step. CX Codex +1 ★ 423repo stars opencode-review-protocol The opencode-review-protocol Claude Code prompt defines a pull request review workflow. It posts line-specific findings, updates a summary comment, and writes a verdict for CI. CX Codex +1 ★ 423repo stars security-review The security-review Claude Code skill reviews code changes for security risks and suggests remediations. It activates for auth or permission changes, secrets and PII handling, public endpoints, and dependency upgrades. CX Codex +1 ★ 423repo stars neo4j-query-workload-skill The neo4j-query-workload-skill Claude Code skill builds a graph-database query workload one requirement at a time. It runs new queries against the dataset and checks earlier results for regressions. CX Codex +1 ★ 423repo stars relate This Claude Code skill guides JVM projects through using Relate as a local graph database with Cypher. It activates when Java or Kotlin code needs to create, query, or embed the database. CX Codex +1 ★ 423repo stars relate This Claude Code skill guides Python work with Relate, an embedded openCypher graph database. It activates for building a local database, running Cypher queries, and handling query results. CX Codex +1 ★ 423repo stars

Project sponsors

Companies that keep this analytics open