mcpField
C
commit-message-storyteller

commit-message-storyteller

github.com/ilteoood开发2544 次安装6 天前更新
代码仓库

关于 commit-message-storyteller

将 Git diff 或变更描述整理为符合 Conventional Commits 规范、突出意图的提交信息，适用于希望改善提交记录和 Pull Request 的开发者。还能识别无关变更并建议拆分提交。

主要功能

  1. 01从 diff 推断变更背景
  2. 02选择 Conventional Commits 类型
  3. 03撰写主题、正文和页脚
  4. 04拆分无关变更的提交
  5. 05说明提交信息的缘由

适用场景

  1. 01根据暂存变更生成提交信息
  2. 02概括代码变更的意图
  3. 03为 Pull Request 准备有意义的提交

安装

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

$npx skills add https://github.com/ilteoood/harness --skill commit-message-storyteller

安装后在 Claude Code 中输入/commit-message-storyteller确认已加载。

附带文件references/conventional-commits-guide.md

详细介绍

提交信息故事讲述者

将原始的 git diff 和变更描述转化为清晰、有故事性的提交信息，并遵循 Conventional Commits 规范。你得到的不再是“update file.js”，而是能够传达意图、上下文和影响的提交信息。

何时使用此技能

  • 用户说“写一条提交信息”、“帮我提交”或“生成一次提交”
  • 用户粘贴 git diff 或描述代码变更
  • 用户说“我应该把它作为什么提交？”或“总结我的 diff”
  • 用户希望为团队或开源项目获得更好的提交历史
  • 用户正在准备 pull request，并希望获得有意义的提交信息

前置条件

至少准备好以下一项：

  • git diff 或 git diff --staged 的输出
  • 对你改了什么以及为什么改的描述
  • 已修改文件的列表

工作方式

第 1 步：收集变更上下文

向用户询问（或从 diff 中推断）以下内容：

  1. 改了什么 — 受影响的文件、函数、逻辑
  2. 为什么改 — bug 修复、新功能、重构、性能等
  3. 由谁/什么触发 — issue 编号、用户请求、技术债等

如果用户提供的是原始 git diff，请从 diff 中自动提取这些上下文。

第 2 步：确定提交类型

使用以下指南将变更映射到 Conventional Commits 类型：

类型使用时机
feat添加了新功能或能力
fix修复了 bug 或不正确的行为
refactor在不改变行为的情况下重构代码
perf提升性能的变更
docs仅文档变更
style格式、空白、缺少分号（无逻辑变更）
test添加或更新测试
chore构建流程、依赖更新、配置变更
ciCI/CD 流水线变更
revert回滚之前的提交

详细示例见 references/conventional-commits-guide.md。

第 3 步：编写提交信息

遵循以下结构：

<type>(<optional scope>): <short imperative summary>

<body — the story: why this change was made, what problem it solves>

<footer — issue refs, breaking change notices>
各部分规则

主题行（第一行）：

  • 使用祈使语气：“add”、“fix”、“remove” —— 而不是“added”或“fixes”
  • 最多 72 个字符
  • 末尾不加句号
  • 冒号后使用小写

正文（故事）：

  • 解释 为什么，而不是 是什么（diff 已经展示了是什么）
  • 描述此变更之前存在的问题
  • 如相关，提及考虑过的其他方案
  • 每行保持在 100 个字符以内
  • 用空行与主题行分隔

页脚：

  • 引用 issue：Closes #123、Fixes #456、Refs #789
  • 标记破坏性变更：BREAKING CHANGE: <description>
第 4 步：生成输出

将提交信息放入可复制的代码块中，随后用一行通俗英文解释你讲述的故事。

示例输出：

fix(auth): prevent token refresh loop on expired sessions

When a user's session expired mid-request, the auth middleware was
triggering a token refresh, which itself failed validation and triggered
another refresh — causing an infinite retry loop that crashed the app.

This adds a recursion guard flag that aborts the refresh cycle if a
refresh is already in progress, returning a clean 401 instead.

Closes #312

讲述的故事： 会话过期时出现的静默无限循环导致应用崩溃；此变更提前终止该循环并返回清晰的错误。

从一个 Diff 生成多个提交

如果 diff 包含逻辑上相互独立的变更，请将它们拆分为多条提交信息，并告知用户。使用以下启发式方法：

  • 不同文件且用途无关 → 可能是不同的提交
  • 同一文件但关注点不同（例如 bug 修复 + 重构）→ 建议拆分
  • 所有内容紧密耦合 → 一次提交即可

边界情况

情况如何处理
用户除 diff 外没有提供任何上下文根据文件名和变更的符号推断类型和范围
变更跨越许多文件且没有明确主题询问：“这是一个逻辑变更，还是多个？”
检测到破坏性变更自动添加 BREAKING CHANGE: 页脚
用户说“保持简短”省略正文，只写一条有力的主题行
没有可用的 issue 编号完全省略页脚

快速参考

# Get your staged diff to paste into Copilot
git diff --staged

# Or get the last uncommitted working tree changes
git diff

类型示例和范围指南见 references/conventional-commits-guide.md。

评论

支持 Markdown