ziya: Skill for Claude Code

Writing a Release Announcement

When to use

You are announcing a tagged release and need to produce a short highlight summary from a changelog. Two jobs use this skill, and they own different channels:

• sweep (cuts the release) announces to #ziya-dev — highlights in the channel, changelog + commit link in the thread.
• release (publishes the artifacts) announces to #ziya-interest — one prose message, no thread.

Whichever job you are in, post only to that job's channel. Availability claims differ between them; see "Availability claims" below.

Also use this when asked for "highlights", "what's new", or "what changed" for a version.

Why this needs a skill at all

A changelog and an announcement are different genres, not different lengths. Ziya's changelog entries are deliberately enormous forensic root-cause narratives written for a future engineer debugging a regression — a single entry runs 400 words about why Number.isFinite(newScale) passed on a zero-size container. That is correct for a changelog.

If you "summarize the changelog" you produce a shorter changelog. That is the failure mode. You must instead re-derive what changed from the reader's point of view, using the changelog as evidence rather than as a draft.

Run four passes, in order. Do not start writing bullets until pass 3.

---

Pass 1 — AGGREGATE (do this first, always)

Group entries into themes. A theme is a user-observable capability, never a file, module, or subsystem.

Aggregate only where several changelog entries describe facets of one change — the same capability written up separately because the bugs were in different files. Two entries that a user would experience as two different things are two items, and they stay two items.

• Do NOT aggregate to shorten the message. There is no item cap (see "Hard caps"), so merging distinct work buys nothing and costs the reader a change they can no longer see. Aggregation exists to remove duplication, not volume. A release with 200 distinct user-observable changes has 200 lines.
• N entries that are genuinely one theme produce one title naming the theme. A bare (N fixes) count is the ONLY parenthetical permitted, and only when the count is load-bearing; never enumerate the N, and never append two or three of them as examples.
• Read git diff --stat <prev-tag>..HEAD for new top-level modules. A cluster of new files is the mechanical signal that a platform landed, and the platform is the headline — not whichever feature built on it happens to appear first in the changelog.
• Ask of every candidate bullet: is this the trunk or a leaf? Ship the trunk and stop there — do not follow it with the leaf as an example. Naming leaves after the trunk claim is how a one-clause bullet becomes a 251-character one; if a leaf is genuinely more important than the trunk, it replaces the trunk claim rather than trailing it.