Back to skills
SKILL.md
Release Notes
ASecurityRelease Note 与 CHANGELOG 的标题、五段结构、体裁区别和 SemVer 指针:面向用户的可感知变化写进发布说明,过程复盘留在复盘记录;版本号只作指针,不替代证据。触发:"写 release / release note / release notes / CHANGELOG / 版本说明 / 发版说明 / SemVer / 发布文案"。
- 8 stars
- 0 votes
- 0 copies
- 0 views
- Added November 18, 2026
Security analysis
92/100- Installs packages at runtime which could introduce malicious dependencies
npx -y skills add webkubor/writing-standard-skills --skill release-notes --agent claude-codeAre you the author of Release Notes?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/webkubor-release-notes)---
name: release-notes
version: "1.0.0"
description: Release Note 与 CHANGELOG 的标题、五段结构、体裁区别和 SemVer 指针:面向用户的可感知变化写进发布说明,过程复盘留在复盘记录;版本号只作指针,不替代证据。触发:"写 release / release note / release notes / CHANGELOG / 版本说明 / 发版说明 / SemVer / 发布文案"。
---
# 发布说明与 CHANGELOG
## 适用范围
适用于版本发布说明、GitHub/GitLab Release 正文、包版本发布摘要和 `CHANGELOG.md` 版本小节。它管“用户读到什么、怎么判断是否升级”,不负责是否发版、分支怎么合并、包怎么发布。
## SemVer 指针
版本号只表达兼容性方向,发布内容仍要以可核验事实描述:
- **Major `X.0`**:可能破坏兼容,必须给迁移步骤。
- **Minor `0X.0`**:新增能力或向后兼容的功能变化。
- **Patch `0.X`**:修复或小幅调整,不改变承诺的接口语义。
版本号不能代替发布内容,也不能把文档、元数据或自省改动伪装成用户可见功能。具体是否提高版本由项目的发布规则决定。
## Release Note 标题
固定写法:
```text
v<SemVer> — <一句话核心价值>
```
### ✅ 正例
```text
v2.5.0 — 发布门禁与安装说明对齐
```
### ❌ 反例
```text
release: v2.5.0
```
裸版本号或机械前缀看不出升级价值。
## 五段结构
无论手动还是脚本生成,正文按以下五段组织。没有内容的段落也要显式说明,避免读者以为漏了:
````markdown
## [2.5.0] - YYYY-MM-DD
> **一句话摘要**:<用户升级后能感知的变化>
### 新增特性
- <能力、使用场景和前后行为变化>
### 体验与性能优化
- <体验变化;性能数字要给实测口径>
### 缺陷修复
- <现象、触发条件、修复结果、Issue/PR 入口>
### 破坏性变更与迁移
- 无破坏性变更(向后兼容)
- 或:Before → After、受影响对象、迁移命令
### 安装与升级
```text
<一条可直接执行的安装或升级命令>
````
```
五段中的标题保持稳定,内容按项目实际情况填写。用户能感知的变化放前面,内部实现细节只在帮助理解风险时出现。
## CHANGELOG 与 Release Note 的体裁区别
| 体裁 | 读者 | 写什么 | 不写什么 |
|---|---|---|---|
| `CHANGELOG.md` | 下一位升级者、长期查阅者 | 每个版本的用户可见变化、兼容性、迁移和安装入口 | 失败探索、个人复盘、内部职责调整 |
| Release Note | 本次升级者 | 当前版本最值得知道的价值、风险、升级动作 | 与 CHANGELOG 不一致的另一套故事 |
两种体裁的版本事实必须一致,但不一定逐字复制:CHANGELOG 适合长期检索,Release Note 适合快速决策。发布页面不能另编一套与 `CHANGELOG.md` 冲突的事实。
过程踩坑、根因、SOP 修订和身份纠正写进复盘记录,不写进用户发布说明。读者是“要升级的陌生人”时进发布说明;读者是“下一位改这块代码的人”时进复盘。
## 反例与正例
### ❌ 反例:只有内部视角
> 优化了代码逻辑,重构了若干模块,提升了可维护性。
升级者不知道自己会看到什么、要不要改配置、是否值得升级。
### ✅ 正例:给用户结果和动作
> **一句话摘要**:安装流程不再要求手工复制技能文件,升级后自动建立引用。
>
> **新增特性**:安装脚本支持幂等升级,重复执行不会覆盖已有工作区。
>
> **缺陷修复**:修复重复执行产生重复目录的问题,见 Issue #123。
>
> **破坏性变更与迁移**:无破坏性变更(向后兼容)。
>
> **安装与升级**:`npm install example-package@^2.5.0`
### ❌ 反例:版本号冒充证据
> v2.5.0 已发布,质量全面提升。
没有变化清单、验证依据或升级入口,读者无法判断。
### ✅ 正例:数字和口径都可查
> 冷启动从 850ms 降到 19ms(同一基准、连续 30 次、中位数),见基准记录。
## 与流程机制的边界
- 发版审批、tag 触发、CI、包发布、回滚和分支策略属于项目流程;本 skill 只管标题、五段和版本语义的表达。
- 提交、构建、发布、部署、业务验收分别确认;发布说明不能用“已发布”替代部署或验收证据。
- 触达 owner 的通道选择属于流程。本 skill 只写发布文字,按使用方自己的路由规则通知,不写死投递渠道。
- 汇报格式以 `task-reporting` 为准;`executive-briefing` 只叠加 `✅/⏸` 与拍板项。
- 停手/上报只认五类必停项:花钱、删生产数据、对外发布、凭据变更、项目方向。
## 自检清单
- [ ] 标题是否是 `v<SemVer> — 核心价值`?
- [ ] 一句话摘要是否说清升级后可感知的变化?
- [ ] 新增、优化、修复、破坏性变更、安装升级五段是否齐全?
- [ ] 每条变化是否有具体行为、数字或可查入口?
- [ ] 破坏性变更是否给了 Before/After 和迁移动作?
- [ ] 安装或升级命令能否直接复制执行?
- [ ] CHANGELOG 与 Release Note 的事实是否一致?
- [ ] 过程复盘是否误放进用户发布说明?
- [ ] SemVer 方向与变化性质是否匹配?
- [ ] 是否把发布、部署、验收写成同一个完成状态?
Attribution
Related skills
View all in ai-agents →Comments
Loading comments…
Newsletter
Get the weekly list of safe new skills, and the ones we pulled.