release-announcement Skill
起草或修订 ax 发布公告和网站更新日志页面。当用户说"write release notes"、"draft release announcement"、"prepare changelog"、"release page"、"version page"、"what changed in vX.Y.Z"、"generate announcement for vX.Y.Z"或请求发布说明时触发。使用 Release Please 范围证据、git 变更文件/提交,以及 ax sessions/recall 来说明该版本的来龙去脉。不要对普通提交信息或无关文档触发。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
ax:release-announcement
Write release announcements that are grounded in the actual release range and
the agent sessions that produced it. This skill owns the curated layer under
docs/releases/; Release Please still owns CHANGELOG.md.
Assumes ax is on PATH and the local ax database is reachable. If ax fails
with a DB connection error, tell the user to start the repo DB and continue
from git evidence only if they ask.
When to fire
Use this skill for:
- "write release notes" / "draft release announcement"
- "prepare changelog" / "update the website changelog"
- "release page" / "version page" / "SEO release page"
- "what changed in vX.Y.Z"
- "generate announcement for vX.Y.Z"
- "explain how we got to this release"
Do not use this for a single commit message, generic README edits, or a
non-release feature doc.
Workflow
1. Resolve the version and range
If the version is known:
bun run release:announcement -- X.Y.Z
This drafts docs/releases/vX.Y.Z.md and, when the Release Please compare
heading is present, embeds:
- previous release tag (
BASE_REF) - release tag or
HEAD(HEAD_REF) git diff --name-status "$BASE_REF..$HEAD_REF"git log --reverse --format='%h %cs %s' "$BASE_REF..$HEAD_REF"
If you need to inspect manually:
BASE_REF=<previous-release-tag>
HEAD_REF=<release-head-or-tag>
git diff --name-status "$BASE_REF..$HEAD_REF"
git log --reverse --format='%h %cs %s' "$BASE_REF..$HEAD_REF"
2. Map commits and files to agent sessions
Use the file list to identify touched subsystems. Use the commit list to pick
important SHAs. Then query ax:
ax ingest here --since=30d
ax sessions here --days=30
ax sessions near <important-sha>
ax recall "<subsystem or decision>" --sources=turn,commit --scope=here
For large releases, inspect at least:
- one SHA per major topic
- one SHA near each major schema/API/CLI change
- any SHA tied to a surprising bug fix or reversal
- session windows around the merge/release PR if available
3. Write the announcement
Replace the generated draft with a topical narrative. Keep it concise, but
make it useful:
- How we got here - the problem, decision tree, tradeoffs, and why the
final shape won. Cite session/commit evidence in prose.
- What changed - grouped by topic, not one flat commit list.
- Example - a CLI command, config snippet, output sample, schema fragment,
or before/after workflow when the release changes behavior.
- Visual evidence - screenshot, diagram, or output capture when a UI, CLI,
dashboard, TUI, or workflow is easier to understand visually.
- Why it matters - the practical day-to-day impact.
Do not invent motivation. If ax session evidence is missing, say what the
commits and changed files prove and keep the story narrower.
4. Assets and rendering
Put website-visible release images here:
apps/site/public/releases/assets/
Reference them from release markdown:

The website release renderer supports headings, lists, links, bold scopes,
fenced code blocks, and images. Use those instead of hand-written HTML.
5. Verify
Run:
bun run typecheck
cd site && bun run build
If the page changed, preview and smoke the specific version page:
cd site
bun run preview -- --host 127.0.0.1 --port 4175
Check /changelog and /changelog/vX.Y.Z.