release-highlights
Skill160 starsChanged 5 days agoApache-2.0View on GitHub
Add a hand-written Highlights section to a GitHub release whose notes were auto-generated, summarizing the release's PRs in user-facing language above the generated changelog. Reads every PR in the range, drafts the section in the repo's house style, asks about ambiguous wording, and writes only after approval. Use when a release has shipped and its notes are still a bare What's Changed list, or when backfilling releases that never got Highlights.
- Commits and pushes
4 other projects use a version of this.
Adopted by
Most recently taken up by
- muxy-app/muxytheir own version, first seen Nov 15, 2026
- victorhqc/filberttheir own version, first seen Nov 8, 2026
- Lingyan000/fluxdotheir own version, first seen Oct 8, 2026
- leanprover/lean4their own version, first seen Oct 8, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- leanprover/lean4★ 10ksame name
- Lingyan000/fluxdo★ 2.5ksame name
- muxy-app/muxy★ 2.4ksame name
- victorhqc/filbert★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- app/CLAUDE.mdCLAUDE.md
- build-logic/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- fastlane/CLAUDE.mdCLAUDE.md
- .github/CLAUDE.mdCLAUDE.md
- shared/CLAUDE.mdCLAUDE.md
- audit-depsSkill
- audit-i18nSkill
- audit-paritySkill
- marketing-refreshSkill
- small-screensSkill
- sync-upstreamSkill
- update-web-assetsSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 5 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
If the script refuses, that refusal is the feature.
- Very specific: line 39
No argument → the newest release: gh release list --repo garfiec/Librechat-Mobile --limit 1
- Very specific: line 64
Read all of them, including the ones that look mechanical — a chore( prefix sometimes hides a user-visible change, and a feat( prefix …
- Distinctive: line 86
If nothing is ambiguous, ask nothing.
- Distinctive: line 120
Lead with the most visible change: If the release renames the app or changes the launcher icon, that is the first bullet.
- Distinctive: line 122
Keep it to roughly 3–6 sub-bullets per category.
- Distinctive: line 142
If it exits non-zero after the write, run the restore command it printed immediately and say what happened.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Release Highlights
Adds a # Highlights section between the badge row and ## What's Changed on a
published release. Nothing else about the release changes.
The invariant
Everything from ## What's Changed down is generated once, at publish time, and cannot
be rebuilt. It carries the compare link, the New Contributors block, the build provenance
attestation ID, and the CI run URL. Those come from the publish-time workflow run. If they
are overwritten they are gone.
So: never regenerate a release body. Never call gh release edit --notes with prose you
composed. Never let gh release create --generate-notes near an existing release. The only
supported write is scripts/insert_highlights.py, which fetches the live body, splits it at
the marker, and reassembles it with the tail byte-identical — then re-fetches and proves the
tail did not change, printing a restore command if it did.
If the script refuses, that refusal is the feature. Do not work around it by editing the body by hand.
Steps
1. Resolve the target
- No argument → the newest release:
gh release list --repo garfiec/Librechat-Mobile --limit 1 - Explicit tags → exactly those, in the order given.
--backfill→ every release with no Highlights section. Enumerate them and confirm before touching any. There are releases going back tov0.1.1that predate both calver and the Switchboard rename; they are almost never what the user meant.--since <tag>sets a floor. Backfill never runs implicitly.
Refuse a tag that already has a Highlights section. Replacing one is a separate, explicit
request, and only then does --replace get passed.
2. Read the release and every PR in it
gh release view "$TAG" --repo garfiec/Librechat-Mobile --json body -q .bodyExtract the PR numbers from the What's Changed list, then read every one of them:
for p in $PRS; do
echo "=== #$p"
gh pr view "$p" --json title,body -q '.title + "\n" + (.body | .[0:800])'
doneRead all of them, including the ones that look mechanical — a chore( prefix sometimes
hides a user-visible change, and a feat( prefix sometimes hides pure plumbing. The title
is a claim about the change, not a description of its effect; the body's Summary/Problem
section is what tells you whether a user would notice.
For each PR decide one thing: what changes for someone using the app? If the answer is "nothing they could observe", it is not a Highlights bullet.
3. Ask about anything ambiguous — once, before drafting
Collect every uncertain item across the whole release and ask them in a single round. Do not draft first and ask afterwards, and do not interrupt per-PR.
What counts as ambiguous is not "I don't understand the change" — read the PR again for that. It is when the change is understood but its framing is a judgment call the user owns:
- Was this broken in a shipped build, or never working at all? ("banners display again" vs. "banners display" — the first claims a regression that may never have existed)
- Is a fix worth naming, or is it noise that belongs in the Misc lines?
- Does a staged feature land in this release or the next one?
- Is an internal-sounding change actually user-visible?
If nothing is ambiguous, ask nothing.
4. Draft in the house style
# Highlights
* Features
* <short user-facing phrase>
* Bug Fixes
* <short user-facing phrase>
* Performance Improvements
* Misc Tech Debt Refactors
* Misc Stability ImprovementsRules, in force regardless of what prior releases happen to look like:
- Categories are fixed and ordered: Features, Bug Fixes, Performance Improvements, Misc Tech Debt Refactors, Misc Stability Improvements. Omit any with nothing to say — a release with no features has no Features line. A new top-level category is allowed when a release genuinely does not fit, but say so explicitly when presenting the draft.
- A category with nothing nameable stays a bare bullet.
* Performance Improvementswith no children is correct and common; it signals the work happened without itemizing it. - Sub-bullets are user-facing effects, in the user's vocabulary, sentence case, no trailing period, no PR links, no PR numbers, no commit-message prefixes. "Two-factor authentication now works end to end", not "fix(auth): make 2FA login work end to end".
- Collapse staged PRs into one bullet. A feature delivered across several PRs is one thing to a user. Five prefetch PRs (#335, #341, #342, #343, #344) are one line about background cache warming; three access-gateway PRs (#294, #298, #312) are one line about custom request headers.
- Never name infrastructure work individually. Dependabot bumps, CI changes, test additions, Claude skills, dead-code removal, comment cleanups, docs — these fold into the two Misc lines and are never their own sub-bullet.
- Lead with the most visible change. If the release renames the app or changes the launcher icon, that is the first bullet.
- Keep it to roughly 3–6 sub-bullets per category. If Bug Fixes runs to ten, the tail of the list is Misc Stability Improvements.
5. Propose, then write
Present the draft as a fenced markdown block, plus the judgment calls worth flagging. Do not write until the user approves.
On approval:
python3 .claude/skills/release-highlights/scripts/insert_highlights.py \
--tag "$TAG" --highlights-file "$HL" --applyDrop --apply first to dry-run it. The script backs up the original body, refuses on a
pre-existing Highlights section, refuses on a missing or duplicated marker, refuses on an
empty body, and verifies the tail after writing. Report what it prints — including the
backup path — rather than paraphrasing it as success.
If it exits non-zero after the write, run the restore command it printed immediately and say what happened.
Notes
- Repo is
garfiec/Librechat-Mobile; the local directory isLibreChat-Androidfor legacy reasons. - The app is Switchboard; LibreChat is the backend it talks to. Release notes describe Switchboard. Do not rename backend references.
- GitHub stores release bodies with CRLF line endings. Any pipeline that normalizes them
rewrites every line below the marker — the content survives, but the tail is no longer the
bytes that were published. The script reads the body verbatim, matches the existing line
ending when building the inserted block, and never converts. Do not pre-process a body
through
tr,sed, or a Python.replace("\r\n", "\n")on the way in. - GitHub appends a trailing newline to a body it stores. The script strips trailing whitespace before writing so repeat edits cannot accrete blank lines, and tolerates that single newline when verifying. Any other difference in the tail is treated as corruption.
- Reading a body with
-q .bodyis fine — that is what step 2 does. What must never happen is a write round-tripped that way (gh release view -q .body > f && edit f && gh release edit): that pipeline drops the CRLFs and appends a newline per pass. --backfilland--sinceare instructions in this file, not flags on the script. Nothing enforces them; they hold only as long as they are followed. The script's own guards are--apply,--replace, and the refusals listed above.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

