---
name: Draft Release Notes
slug: draft-release-notes-3
category: Writing
description: Draft Release Notes turns a structured list of changes from changelog-scan into a clean, categorized, user-facing release notes draft. Use it after a changelog scan to prepare a release notes file for human review without publishing.
github: "https://github.com/cobusgreyling/loop-engineering/tree/main/starters/changelog-drafter/.grok/skills/draft-release-notes"
language: JavaScript
stars: 10380
forks: 1410
install: "npx degit https://github.com/cobusgreyling/loop-engineering/tree/main/starters/changelog-drafter/.grok/skills/draft-release-notes ~/.claude/skills/draft-release-notes"
installs_to: ~/.claude/skills/draft-release-notes
source_path: starters/changelog-drafter/.grok/skills/draft-release-notes/SKILL.md
collection_size: 23
category_size: 1012
collection_url: "https://dirskills.com/collections/cobusgreyling/loop-engineering"
added: 2026-08-15T06:50:31.656Z
last_synced: 2026-08-15T06:50:31.656Z
canonical_url: "https://dirskills.com/skills/draft-release-notes-3"
---

# Draft Release Notes

Draft Release Notes turns a structured list of changes from changelog-scan into a clean, categorized, user-facing release notes draft. Use it after a changelog scan to prepare a release notes file for human review without publishing.

**Install:**

```bash
npx degit https://github.com/cobusgreyling/loop-engineering/tree/main/starters/changelog-drafter/.grok/skills/draft-release-notes ~/.claude/skills/draft-release-notes
```

## README

# Draft Release Notes Skill

## Inputs
- Structured output from `changelog-scan` (the list of items + summary)
- Previous release version (from state)
- Target next version (or "unreleased" / "next")
- Optional: short "Release voice" guidance from AGENTS.md or a project skill (tone, what to highlight, what to omit)

## Output
Write a ready-to-review draft to `RELEASE_NOTES_DRAFT.md` (or print it clearly so the loop can save it).

Use this structure (adapt section names to what actually exists; omit empty sections):

```markdown
# Release Notes — vX.Y.Z (unreleased)

## Breaking Changes
- ...

## Features
- ...

## Bug Fixes
- ...

## Performance
- ...

## Security
- ...

## Documentation & Examples
- ...

## Internal / Maintenance (usually omitted from public notes)
- ...

**Thanks** to @contributor1, @contributor2 for contributions to this release.

**Full changelog**: https://github.com/ORG/REPO/compare/vPREV...HEAD
```

## Rules
- Be concise and scannable. One line per item when possible, with link to PR.
- Use the actual title / one-sentence summary from the scan. Do not embellish or add marketing fluff unless the project voice explicitly wants it.
- Always call out breaking changes and security items at the top.
- If a change has a user upgrade step that is obvious from the PR, include a one-sentence "Upgrade note".
- Never claim a change was made if it was not in the scanned input.
- At the very end of the draft, include a short "Draft generated by loop — please review for accuracy and tone before publishing."

## When to Escalate Instead of Drafting
- More than ~40 items in one window → suggest splitting the release or human curation.
- Any breaking or security item → include prominent callout and recommend human wordsmithing.
- The scan summary says "human review needed first".

After writing the draft, the loop should update state with the draft location and "pending human review".