agentleFS
garfiecgarfiec/Librechat-Mobile/.claude/skills/release-highlights/SKILL.md

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

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
  1. Distinctive:

    If the script refuses, that refusal is the feature.

    line 32
  2. Very specific:

    No argument → the newest release: gh release list --repo garfiec/Librechat-Mobile --limit 1

    line 39
  3. Very specific:

    Read all of them, including the ones that look mechanical — a chore( prefix sometimes hides a user-visible change, and a feat( prefix …

    line 64
  4. Distinctive:

    If nothing is ambiguous, ask nothing.

    line 86
  5. Distinctive:

    Lead with the most visible change: If the release renames the app or changes the launcher icon, that is the first bullet.

    line 120
  6. Distinctive:

    Keep it to roughly 3–6 sub-bullets per category.

    line 122
  7. Distinctive:

    If it exits non-zero after the write, run the restore command it printed immediately and say what happened.

    line 142

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 to v0.1.1 that 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 .body

Extract 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])'
done

Read 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 Improvements

Rules, 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 Improvements with 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" --apply

Drop --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 is LibreChat-Android for 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 .body is 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.
  • --backfill and --since are 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.