发布说明撰写

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install release-writing
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 release-writing。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

发布说明撰写是 Openclaw Skills 指南，介绍发布软件版本时组织特定的标准和工作流程。它规定变更日志分区、版本与发布标题格式、发布说明长度，以及准备发布、通过拉取请求合并、为已合并提交打标签并在 GitHub 上发布的正确顺序。
该技能并非要取代变更日志生成器，而是帮助将生成的草稿转化为清晰、准确的发布沟通内容。它还涵盖修订旧版发布说明、在仓库更名后修复链接，以及在变更可能影响用户时说明升级操作。

应用场景

准备新版本发布，例如发布版本 X.Y.Z。
格式化或审查根据提交记录生成的 CHANGELOG 草稿。
编写简洁的 GitHub 发布说明，清楚说明用户可见的变更和升级步骤。
在发布前后检查测试、CI、拉取请求检查、标签、发布说明和变更日志链接是否正确。
更正过往发布说明，而不重写历史变更日志。
仓库或组织更名后，查找并修复发布说明中过时的仓库引用。
在现有仓库中采用组织的发布惯例，而不重写其发布历史。

工作原理

确认发布已准备就绪：更新本地 main 分支，确认工作树干净，检查 main 分支最近一次 CI 运行已通过，并运行仓库的发布检查。
准备 CHANGELOG：将 Unreleased 部分转换为带日期的 X.Y.Z 版本部分，按要求顺序使用 Keep a Changelog 的六个类别，添加比较链接，并创建新的 Unreleased 部分。
通过专用分支和拉取请求提交发布变更。等待所有 PR 检查通过，然后按照仓库预期的工作流程合并，而不是直接推送到 main。
更新 main，并在已合并到 main 的提交上创建带注释的 vX.Y.Z 标签，然后将标签推送到远程仓库。
发布 GitHub release，使用简洁的标题和不超过 20 行的发布说明，其中包含指向对应 CHANGELOG 部分的链接。
验证远程标签和已发布的 release。检查发布说明的实际行数、变更日志锚点和任何安装说明；如果有错误，应修复发布说明，而不是修改已发布的标签。
后续需要更正时，在适当情况下编辑发布说明。代码问题应发布补丁版本；仓库更名后，应审查旧说明中的失效链接。

配置指南

此技能规定工作流程和写作标准；所提供的 SKILL.md 未定义软件包安装程序或通用的代理安装路径。将技能文件添加到为 Openclaw Skills 代理配置的 skills 目录中；如果 references/templates.md 文件可用，请与技能文件一同保留。在具有 CHANGELOG 且已记录项目发布检查的仓库中使用，相关说明通常位于 CONTRIBUTING.md。
所需工具为 Git 和 GitHub CLI (gh)，并且需要通过身份验证，以便对该仓库创建拉取请求、标签和 release。请将版本、所有者、仓库和 PR 占位符替换为项目对应的值。
git --version
gh --version
gh auth status
git status --short
发布前，请遵循仓库自身的检查要求，并分别验证 main 和 CI：
git checkout main && git pull --ff-only
git status --porcelain
gh run list --branch main --limit 1

数据架构

该技能通过两种互补产物来组织发布信息：作为历史记录的仓库 CHANGELOG，以及面向读者的 GitHub 发布说明摘要。它不规定单独的数据库，也不会生成新的数据格式。
Artifact or field Convention
待发布的变更日志部分 ## [Unreleased]
版本部分 ## [X.Y.Z] - YYYY-MM-DD
变更日志类别 Added、Changed、Deprecated、Removed、Fixed、Security；按此顺序使用英文标签，并省略空类别
变更日志正文语言 遵循仓库 README 的主要语言
版本控制 Semantic Versioning
变更日志链接 在文件底部为每个版本保留一个比较链接；根据实际相邻标签生成比较内容
GitHub release 标题 vX.Y.Z —
GitHub release 正文 不超过 20 行，以指向对应 CHANGELOG 锚点的链接结尾
Git 标签 带注释的 vX.Y.Z 标签，指向已合并到 main 的发布提交
迁移仓库时，从下一个版本开始应用此标准；保留历史变更日志部分。可以修订发布说明，但除修复失效引用外，CHANGELOG 应继续作为历史记录。该技能的格式模板记录在 references/templates.md 中。

高级特性

提供端到端的 GitHub CLI 工作流程，涵盖创建 PR、验证检查、压缩合并、带注释的标签、发布 release 和发布后检查。
通过已发布 release 检查强制执行实际的 20 行发布说明限制；并提醒，仅声明目标长度并不能确保说明符合限制。
指导撰写用户影响内容：在读者需要采取行动时，说明破坏性变更、回归问题和必要的升级操作；省略内部发现和不必要的自我批评。
明确处理版本号与内容不匹配的情况，包括解释仅从补丁版本号无法看出的破坏性变更。
支持使用
gh release edit
维护历史 GitHub releases，包括通过基于 shell 的审计查找过时的仓库名称和缺少主题的发布标题。
保留已发布的标签和历史变更日志条目；区分修正发布呈现内容与通过新的补丁版本发布代码修复。
支持在一次过渡中采用仓库标准：规范下一个版本、保留历史条目、根据实际标签关系添加有效的比较链接，并审查较早的发布说明。

name: release-writing description: ZenStory AI 的发布标准与发布流程：切版本、写 CHANGELOG 与 GitHub release notes、修订往期发布、仓库改名后清理失效链接。当有人说“发个 release”“切 0.x.y”“整理 CHANGELOG”“release notes 怎么写”“把往期发布说明改一下”时使用。它规定本组织的格式与发布动作顺序；条目本身的起草可以借助任何 changelog 生成器。 license: MIT

发布写作

本 skill 管两件外部工具管不了的事：本组织的格式约定，和发布这串动作的顺序与验收。

条目怎么从 commit 里生成、怎么分类，现成的 changelog 生成器已经做得不错——实测在「这条改动 会不会拒绝旧输入」这类判断上，它们能主动去读源码并判进 Changed。起草可以用它们；本文 只规定成品长什么样、以什么顺序发出去。

格式骨架与模板见 references/templates.md。

1. 组织标准 项目 标准
   小节名 英文，Keep a Changelog 六类：Added Changed Deprecated Removed Fixed Security
   小节顺序 按上表，没有内容的省略
   正文语言 跟随该仓库 README 的主语言
   版本标题 ## [X.Y.Z] - YYYY-MM-DD
   待发布节 ## [Unreleased]
   底部链接 每个版本一行 compare 链接，必须维护
   版本号 Semantic Versioning
   release 标题 vX.Y.Z — 三到八个字的主题
   release 正文 20 行以内，末尾链到该 tag 的 CHANGELOG 锚点

英文小节配中文正文是刻意的：六个类别是语义标签，英文让它们跨仓库可比；正文是给人读的。 一个仓库内部保持一致即可。

仓库若有自己的分级细则（例如区分「可阻断的约束」与「可覆盖的默认做法」），保留——那是 对分类判据的细化，与六个类别不冲突。

2. 发布流程 阶段一：确认可以发

git checkout main && git pull --ff-only
git status --porcelain # 必须为空

gh run list --branch main --limit 1 # main 上最近一次 CI 必须绿

跑仓库自己定义的发布检查（CONTRIBUTING.md 里通常有），不要只跑单元测试。

测试和 push 不要串在一条命令里。 失败时后面照样执行；分开跑，亲眼确认输出再继续。

阶段二：写 CHANGELOG

起草可借助生成器，再按 第 1 节 校格式：把 ## [Unreleased] 切成 ## [X.Y.Z] - YYYY-MM-DD、补底部 compare 链接、在上方留一个新的空 Unreleased 节。

阶段三：走 PR，不要直接推 main

git checkout -b release/vX.Y.Z
git add CHANGELOG.md && git commit -m "release: X.Y.Z"
git push -u origin release/vX.Y.Z

gh pr create --base main --title "release: X.Y.Z" --body ""
gh pr checks

# 全部 SUCCESS 再合

gh pr merge --squash --delete-branch

发布提交走同一条路径，分支保护、CI 和评审才仍然生效。

阶段四：打 tag

tag 必须打在已合并的 main 上，否则它指向一个不在主线上的提交。

git checkout main && git pull --ff-only
git tag -a vX.Y.Z -m "vX.Y.Z" # 带注释的 tag，不用轻量 tag
git push origin vX.Y.Z

阶段五：建 release
gh release create vX.Y.Z --title "vX.Y.Z — " --notes "$(cat