Agent Skills › haxzie/prequel › changelog

changelog

GitHub

指导在合并前为用户撰写简洁的发布说明,区分于开发日志,强调用户视角与格式规范。

.claude/skills/changelog/SKILL.md haxzie/prequel

Trigger Scenarios

准备推送到 main 分支 创建针对 main 的 PR 需要添加或更新 changelog 被要求编写发布说明

Install

npx skills add haxzie/prequel --skill changelog -g -y
More Options

Non-standard path

npx skills add https://github.com/haxzie/prequel/tree/main/.claude/skills/changelog -g -y

Use without installing

npx skills use haxzie/prequel@changelog

指定 Agent (Claude Code)

npx skills add haxzie/prequel --skill changelog -a claude-code -g -y

安装 repo 全部 skill

npx skills add haxzie/prequel --all -g -y

预览 repo 内 skill

npx skills add haxzie/prequel --list

SKILL.md

Frontmatter
{
    "name": "changelog",
    "description": "Write or edit a release entry in apps\/web\/src\/content\/changelog. Use whenever work is about to be pushed to main or put in a PR against main, when asked to add something to the changelog, update the draft, write release notes, or when told the changelog reads badly. Covers the voice, how short an entry has to be, what never goes in, and the rule that the changelog is written before the push and not after."
}

Changelog

One line per thing a person using Prequel can now do, or no longer has to put up with. Published at /docs/changelog, and the newest release's highlight is the badge on the home page.

Not the marketing site's prose, which is [[site-copy]]. Not a commit log — apps/web/src/content/changelog.ts says it plainly at the top of the file:

A commit log is a record of work and a changelog is a record of what somebody using the app can now do, and most releases contain a good deal of the first and very little of the second. Anything that changed only for us stays out.

Where the entry is written now

In a changeset, not in the .mdx. The files under apps/web/src/content/changelog are generated: release.yml collects the pending changesets, writes <version>.mdx from their sentences, adds the version to RELEASES and tags the result. Writing one by hand puts it in the way of the generator.

So this file is still the voice — every rule below applies to the sentence in a changeset, which is published verbatim — and the changeset skill is the shape and the bump. Read both.

The rule

The changeset is written before the work reaches main — in the same branch, in the same PR, before the push. Not afterwards.

Written after the fact it gets written from git log, by someone reconstructing what happened from commit subjects, which is exactly how a changelog turns into a dev log. Written alongside the work, the question is still "what will somebody notice?" rather than "what did I change?".

So: before git push to main, and before opening a PR that targets main, check whether the branch changes anything a user can see. If it does and there is no changeset for it, stop and write one.

Nothing to add is a normal answer. Refactors, tests, build fixes, internal renames and fixes to features that never shipped all belong in no release.

The trap

This repo's comments are long, discursive and full of em dashes, and AGENTS.md rewards that on purpose. That voice is wrong here and it leaks constantly, because you arrive at the .mdx straight from writing the code.

A changelog entry is read by somebody who has just updated and wants to know whether anything they care about changed. They are scanning. Every clause that explains why the bug happened is a clause between them and the next entry.

The shape

  • One sentence. A second only for a genuine consequence they must act on — "recordings already in this state cannot be recovered". Never for the cause.
  • About twenty words. If it will not fit, it is two entries or one smaller claim.
  • Say what they can do, in their words. "Titles", not "text slices". The names on the buttons, not the names in the code.
  • No mechanism. No file, type, API or framework. Not "ScreenCaptureKit returns -3808", not "the plan is resolved per clip". They cannot see any of it.
  • No "it used to". Describing the old broken behaviour doubles the length and teaches a bug to somebody who never hit it. Say what it does now. The exception is when they may have already been bitten and need to know.
  • Five to eight entries a release. More than that and nothing stands out. Group the small related ones into one line.

highlight is the release in one fragment, no full stop — it sits in a pill. "Text over the recording". "Filters, over the whole picture".

Before and after

These are real entries from this repo, cut down. The left-hand column is what the comment voice produces.

A text is its own length. It used to take the length of the clip beneath it, so splitting a recording under a title, or trimming the footage there, changed how long the title was on screen. What you set is what it stays.

→ A title stays the length you set it, whatever you do to the footage under it.

Texts can be carried past one another along a row. A text that was third stayed third: dragging it towards the front stopped dead against its neighbour and sprang back. It goes wherever there is room on the row now, and it changes rows as you cross them rather than when you let go.

→ Drag titles anywhere on their row, past each other, or onto another row.

A take could come out unplayable if what you were recording went away — the window you were capturing was closed, or a display was unplugged. Stopping the take failed halfway and left the video and audio files unfinished, so the recording sat in the library, opened, and never played. Stopping now finishes the files whatever the capture did.

→ Closing the window you were recording, or unplugging a display, no longer breaks the take. Recordings already damaged by this cannot be recovered.

Note what survives: the thing they did, and the thing that now happens. The sample rate, the missing moov atom and the error number are all gone, and nothing a user needs went with them.

Where it lives

One file per release, apps/web/src/content/changelog/<version>.mdx — written by scripts/version-packages.mjs, not by you. What it generates:

export const date = "2026-09-25";
export const highlight = "Filters, over the whole picture";
export const draft = true;

- Put a filter over the whole picture: CRT, VHS, film, fish eye and seven more.
  • date — the day the release was versioned, which is the day it ships.
  • highlight — the fragment above. Taken from a <!-- highlight: … --> comment in a changeset, or from the most significant one's sentence.
  • The version is added to the top of RELEASES in apps/web/src/content/changelog.ts, which is what orders the page — a directory sorted as text puts 0.0.9 after 0.0.13.

There is no draft export any more. An entry exists once the release is versioned, and before that the pending release is the set of files in .changeset — which is also where you add to it.

Check

pnpm changeset status --since=origin/main   # what this branch would ship
pnpm --filter @prequel/web dev              # /docs/changelog, once released

Then read the release as a stranger who has just updated. If any line makes you ask "why are they telling me this?", cut it.

Version History

  • df09e0c Current 2026-11-19 02:50

    重构流程:将手动版本管理改为基于 changeset 的自动化发布,明确 entries 应写在 push 前而非事后补记。

  • f755daa 2026-09-27 11:09

Same Skill Collection

.claude/skills/backgrounds/SKILL.md
.claude/skills/campaign-emails/SKILL.md
.claude/skills/changeset/SKILL.md
.claude/skills/lifetime-grants/SKILL.md
apps/desktop/resources/skill/SKILL.md
.agents/skills/seo/SKILL.md
.claude/skills/blog-research/SKILL.md
.claude/skills/blog-review/SKILL.md

Metadata

Files
0
Version
df09e0c
Hash
300ce946
Indexed
2026-09-27 11:09

Accueil - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-19 03:46
浙ICP备14020137号-1