Skip to content
Skills Library
Programming · Writing

release-notes

/release-notes

Write the release-notes line a branch owes to the changelog of the program it changes -- cmd/hive/releasenotes/changelog/unreleased/ for the hive CLI, cmd/desktop/releasenotes/changelog/unreleased/ for Hive Desktop, cmd/drive-server/releasenotes/changelog/unreleased/ for Hive Drive Server. Use when asked to update the changelog or release notes, or to check whether the work on this branch earns an entry before the PR goes up.

Repository
hive ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Write the release-notes line a branch owes to the changelog of the program it changes -- cmd/hive/releasenotes/changelog/unreleased/ for the hive CLI, cmd/desktop/releasenotes/changelog/unreleased/ for Hive Desktop, cmd/drive-server/releasenotes/changelog/unreleased/ for Hive Drive Server. Use when asked to update the changelog or release notes, or to check whether the work on this branch earns an entry before the PR goes up.

Original author description

Write the release-notes line a branch owes to the changelog of the program it changes -- cmd/hive/releasenotes/changelog/unreleased/ for the hive CLI, cmd/desktop/releasenotes/changelog/unreleased/ for Hive Desktop, cmd/drive-server/releasenotes/changelog/unreleased/ for Hive Drive Server. Use when asked to update the changelog or release notes, or to check whether the work on this branch earns an entry before the PR goes up.

How it works

  1. 1. Find what the branch changed
  2. 2. Decide whether it earns a note
  3. 3. Add to an existing fragment, or write a new one
  4. 4. Write it well
  5. 5. Verify
Original SKILL.md headings · 138 lines, 996 words
SKILL.md preview
---
name: release-notes
description: Write the release-notes line a branch owes to the changelog of the program it changes -- cmd/hive/releasenotes/changelog/unreleased/ for the hive CLI, cmd/desktop/releasenotes/changelog/unreleased/ for Hive Desktop, cmd/drive-server/releasenotes/changelog/unreleased/ for Hive Drive Server. Use when asked to update the changelog or release notes, or to check whether the work on this branch earns an entry before the PR goes up.
---

# Add a release note

A user-visible change adds a fragment to the changelog of the program it
changes, **in the pull request that earns it**:

| Program | `--product` | Changelog |
| --- | --- | --- |
| hive CLI/TUI (`cmd/hive`) | `cli` | `cmd/hive/releasenotes/changelog/` |
| Hive Desktop (`cmd/desktop`) | `desktop` | `cmd/desktop/releasenotes/changelog/` |
| Hive Drive Server (`cmd/drive-server`) | `drive-server` | `cmd/drive-server/releasenotes/changelog/` |

Every release ships every program under one version. The desktop embeds its
changelog and shows the fragments as the draft in the app; the CLI's and the drive server's notes ship
on the GitHub release. Either way, what you write here is the product's
changelog, not a note to a future maintainer.

A change to the shared `internal/` packages earns a note in each program
whose users can notice it, and only there. One that changes both programs'
behaviour gets one fragment per program, each written for that program's
users.

One file per change is what keeps concurrent branches from conflicting over the
changelog, so **never collapse two branches' notes into one file and never
create the file by hand** -- `changelog:new` builds the name
(ADR [release-notes-accumulate-as-fragments](../../../docs/decisions/2026-09-12-release-notes-accumulate-as-fragments.md)).

A `changelog/<version>.md` is written by promotion during a release, on `main`,
by `cmd/tools/release`. Writing one on a feature branch is wrong even when the version
looks obvious, and a file naming a prerelease is rejected at parse time.

## 1. Find what the branch changed

```bash
git diff main...HEAD --stat
git log main..HEAD --format='%s%n%n%b'
```

The commit bodies carry the intent, which is most of the line already. For a
PR that is not the checked-out branch, `gh pr diff <number>` and
`gh pr view <number>`.

## 2. Decide whether it earns a note

The test is whether a user could notice without reading the diff.

Earns a note:

- a capability that did not exist -- a view, an overlay, a connector, a source,
  a node type, an MCP tool, a palette scope, a shortcut, a CLI command or flag,
  a TUI keybinding;
- behaviour that changed under someone who was already using it, including a
  default, a keybinding, or where something opens;
- a bug a user could hit, described as the symptom they saw;
- a new `settings.yaml` key or `actions.yml` field they can write, or a new
  key in the CLI's config file.

Earns nothing:

- a refactor with no behaviour change, however large;
- tests, fixtures, mocks, e2e specs;
- CI, mise tasks, lefthook, `cmd/` development tooling;
- `docs/`, ADRs, `AGENTS.md`, agent skills;
- a change to the shared `internal/` packages or a dependency bump that changes
  nothing visible in either program;
- a fix to something that never reached a build a user runs -- if the bug was
  introduced and fixed inside the same draft cycle, correct or delete the
  fragment that described it instead of adding a "Fixed" note beneath it.

## 3. Add to an existing fragment, or write a new one

Read what is already unreleased before writing:

```bash
ls cmd/hive/releasenotes/changelog/unreleased/ cmd/desktop/releasenotes/changelog/unreleased/ cmd/drive-server/releasenotes/changelog/unreleased/
```

**If a fragment already describes the exact surface you touched, edit that
fragment** so the release says what the app now does rather than listing five
days of work. A feature that lands over several PRs is one note. Two branches
editing the same fragment is a real conflict worth resolving by hand; that is
the trade, and it is rare.

Otherwise write a new one:

```bash
mise run changelog:new -- --product desktop --kind added "**A notify terminal node**, so a feed can notify on new items."
```

`--product` is `cli`, `desktop`, or `drive-server`. `--kind` is `added`, `changed`, or
`fixed` -- the section it renders under. For
a note that spans lines, pipe it on stdin instead of quoting it:

```bash
mise run changelog:new -- --product desktop --kind fixed <<'NOTE'
**Refresh now fetches.** The feed's Refresh button and `r` re-read the
database and nothing else, so a source was only ever as fresh as the last
poll tick.
NOTE
```

The command prints the path it wrote. Read it back and edit the body or the
`kind` header if either needs work. The filename is only an ordering key, so
it does not have to match what the note ends up saying -- leave it alone.

## 4. Write it well

This is product copy a user reads: inside the app for the desktop, on the
GitHub release for the CLI. **The Simplified Technical
English rule in `CONTRIBUTING.md` applies to commit and PR text, not here** --
write these the way the committed entries in `changelog/*.md` are written.

- one fragment is one bullet: open with the thing in bold, then say what it
  does and where it is:
  `**A notify terminal node**, so a feed can notify on new items.`
- present tense, addressed to the user, describing the app rather than the
  work: "the palette knows where you are", never "we added" or "this PR";
- name the surface a user can find (`Settings ▸ Terminal`, the command palette,
  the Code view's session tree, `hive hc next`, the TUI's tasks view) and
  config keys as they are written (`profiles.order` in `settings.yaml`);
- for a `changed` note, say what a user has to do differently, and for a
  `fixed` note, describe the symptom, not the cause;
- mark an unfinished area `(experimental)` the way Terminal mode and Chats are;
- never name a Go package, a Vue component, an ADR, an issue, or a PR number.

Do not write a release summary. The draft has no `summary`: it describes a
whole release, which no single change can write, so promotion writes it.

## 5. Verify

```bash
go test ./cmd/hive/releasenotes/... ./cmd/desktop/releasenotes/... ./cmd/drive-server/releasenotes/...
```

Each program's `TestChangelogParses` reads its embedded files, so a broken header, an unknown kind, a name the tool did not build, or
an empty body fails there rather than at release time. It runs inside
`mise run check`, which the pre-push hook already runs.

Versions

RepositoryScoreLicence
This page · colonyops/hive100MIT
mono/SkiaSharp100MIT
niekcandaele/claude-helpers100MIT
kenryu42/cc-safety-net100MIT
zeitlos/lucity100AGPL-3.0
openshift-pipelines/pipelines-as-code100Apache-2.0
paperwingio/paperwing100Apache-2.0
jelvodev/yaap100MIT
yearzen1/LocalSkillManager100MIT

Database snapshot: 13.11.2026 · package version 10cfeb30207d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100changelog
    Use when writing, updating, or generating a CHANGELOG.md — for a new release, an unreleased section update, or drafting from git history or diff. Triggers: "update the changelog", "write release notes", "what changed since X", "generate changelog for v1.2.0", "add this to the…
  • 100release
    Cut the next release of every program -- the hive CLI and Hive Desktop under one version. Use when asked to release or publish hive, the CLI, or the desktop app, or when explicitly invoked as `/release`.
  • 90changelog
    AI DevKit · Update CHANGELOG.md Unreleased items from git commits since the latest release. Use when users ask to update changelog/release notes from recent commits, with one concise line per commit and commit/PR links.
  • 100changelog
    Write release notes or a CHANGELOG.md entry from git history. Use when the user says "write the changelog", "release notes for v2.3", "what changed since the last release/tag", or is preparing a release or version bump.
  • 90changelog-writer
    Read the git log and write a user-facing changelog entry in Keep a Changelog format. Use when the user wants to document what changed in a release, write release notes, or update their CHANGELOG.md.
  • 100changelog-entry
    Add an entry for a described change to CHANGELOG.md in Keep a Changelog format, under Unreleased and the right change type (Added, Changed, Deprecated, Removed, Fixed or Security). Use when the user asks to log, record or note a change in the changelog, or wants a changelog line…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.