mcpField
K
keep-a-changelog

keep-a-changelog

github.com/lelborn开发047 次安装2 周前更新
代码仓库

关于 keep-a-changelog

一项依据 Keep a Changelog 和 Semantic Versioning 编写及审查 CHANGELOG.md 的技能，指导开发者整理面向用户的条目、选择版本升级幅度并准备发布。

主要功能

  1. 01Unreleased 与版本章节
  2. 02六类变更分类
  3. 03SemVer 升级指引
  4. 04变更日志审查清单
  5. 05发布准备工作流

适用场景

  1. 01在 Unreleased 下记录改动
  2. 02为发布整理变更日志
  3. 03检查版本顺序与升级幅度

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lelborn/skills --skill keep-a-changelog

安装后在 Claude Code 中输入/keep-a-changelog确认已加载。

详细介绍

Keep a Changelog

维护符合 Keep a Changelog 1.1.0 规范的 CHANGELOG.md 文件，并使用语义化版本控制设置版本号（配套的 semver 技能详细说明了版本递增规则）。变更日志的作用是让人们一眼看清发生了哪些变化，因此条目应面向读者编写（而不是直接倾倒 git log 内容）、按类型分组，并按时间倒序排列。

核心原则

  • 面向读者编写——将提交记录和差异改写为通俗、面向用户的文字；切勿粘贴原始的 git 日志。
  • 每个已发布版本都应有一个条目，按时间倒序排列，并标注 YYYY-MM-DD 格式的日期。
  • 顶部的 [Unreleased] 部分用于汇总尚未定版的变更。
  • 按以下六种类型对变更分组；没有条目的类型应省略标题。
  • 前言应同时提及 Keep a Changelog 和语义化版本控制。

文件结构

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.2.0] - 2026-07-20

### Added

- User-facing description of a new feature.

### Fixed

- User-facing description of a bug fix.

[unreleased]: https://github.com/OWNER/REPO/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/OWNER/REPO/compare/v1.1.0...v1.2.0

链接页脚会将每个版本标题转换为差异链接。根据项目的远程仓库构建比较 URL；不要猜测 URL，如果无法确定，就省略页脚。

六种类型

多个类型适用时，按以下顺序排列：Added（新增功能）、Changed（现有行为变更）、Deprecated（仍然存在，但计划移除）、Removed（在本次发布中移除）、Fixed（错误修复）、Security（漏洞修复——即使与某条 Fixed 条目重复，也要单独列出）。每条项目用一行简短说明变更内容，以及它对用户的意义，而非实现细节。

确定版本

根据影响最大的变更递增版本；semver 技能详细说明了完整的逻辑和推理步骤。

版本为 1.0.0 及以上——公共 API 是一项承诺：

发布内容……版本递增
任何 Removed，或会破坏兼容性的 Changed 条目MAJOR
任何 Added 或 Deprecated 条目（没有破坏性变更）MINOR
只有 Fixed / SecurityPATCH

版本低于 0.y.z——尚无兼容性承诺，因此整个递增级别下移一档（与 npm ^ 范围的解析方式一致——参见 semver）：

发布内容……版本递增
任何 Removed，或会破坏兼容性的 Changed 条目MINOR（0.3.1 → 0.4.0）
只有非破坏性条目——Added / Changed / Deprecated / Fixed / SecurityPATCH（0.3.1 → 0.3.2）

一项破坏性变更就会决定整个发布的递增级别。提议版本递增时，请说明推理依据，并指出 0.x 版本不提供兼容性保证。API 稳定并投入生产后，应发布 1.0.0。

版本来源

提议递增版本前，先读取当前版本——切勿臆造。

  1. 如果存在 package.json 文件，以其中的 version 为准——这是下一个版本递增的真实依据。
  2. 否则，以 CHANGELOG.md 中最新的 ## [x.y.z] 标题为准。
  3. 否则，查看其他项目清单文件（Cargo.toml、pyproject.toml 等）。
  4. 如果以上文件都不存在，请询问；不要猜测。

发布版本时，如果存在 package.json 文件，请提议将其更新为新版本。未经用户确认，不要修改该文件。

此技能不会自动执行的操作

更新变更日志不代表获得了发布权限。绝不要创建 Git 标签、GitHub 发布（gh release create）或推送发布提交，除非用户明确要求——在变更日志语境中，推送、合并或“发布”并不意味着要执行这些操作。

当发布看起来已准备就绪时，完成变更日志（和版本建议）后就停下来，询问用户是否希望你：

  • 更新 package.json 中的版本
  • 提交
  • 打标签
  • 推送
  • 创建 GitHub 发布

只执行用户确认的操作。如果用户说“只更新变更日志”，那就是全部工作。

工作流

**记录变更：**对变更进行分类，并在 ## [Unreleased] 中对应类型下添加一条单行项目（如果缺少该节或标题，则创建）。暂不填写版本或日期。

**发布版本：**从 package.json（或版本来源中的备用来源）读取当前版本，根据上表计算版本升级幅度，然后将 ## [Unreleased] 中的内容重命名为新的 ## [x.y.z] - YYYY-MM-DD 节，在其上方保留一个新的空 ## [Unreleased]，并更新链接页脚（将 [unreleased] → compare/vNEW...HEAD，添加 [vNEW]）。如果适用，建议同步更新 package.json 中的版本。打标签、推送或创建 GitHub 发布前先停下来询问——请参阅此技能不会自动执行的操作。

**根据提交记录生成：**剔除无关内容（合并、格式调整、纯重构、仅涉及文档或 CI 的提交——即 Conventional Commits 中的 chore/style/ci/build/test 类型；请参阅 conventional-commits 技能），将其余提交改写为面向用户的条目，归入六种类型，并建议版本升级幅度。

撤回发布版本：发布后撤回的版本应在标题中标明，且保留，不要删除（安装了该版本的用户需要了解情况）：

## [1.4.1] - 2026-07-18 [YANKED]

审核 CHANGELOG.md

检查：日期格式为 YYYY-MM-DD；没有原始提交或差异转储；没有空的类型标题；版本严格按降序排列；前言同时列出两种规范；每个版本的升级幅度与变更相符（例如，移除了某项功能却只升级 PATCH 时应标出）。列出一份简短的具体修正清单；如果用户要求的是修复而非审核，则随后应用这些修正。

评论

支持 Markdown