commit-message-storyteller

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Commit Message Storyteller

提交消息叙事生成器

Transforms raw git diffs and change descriptions into clear, story-driven commit messages that follow the Conventional Commits specification. Instead of "update file.js", you get messages that communicate intent, context, and impact.

将原始 git diff 和更改描述转换为清晰、故事驱动的提交消息，并遵循 Conventional Commits 规范。你得到的不会是“update file.js”，而是能够传达意图、背景和影响的提交消息。

When to Use This Skill

何时使用此 Skill

User says "write a commit message", "help me commit", or "generate a commit"
User pastes a git diff or describes code changes
User says "what should I commit this as?" or "summarize my diff"
User wants better commit history for their team or open-source project
User is preparing a pull request and wants meaningful commit messages

用户要求“编写提交消息”“帮助我提交”或“生成提交”
用户粘贴了 git diff 或描述了代码更改
用户询问“我应该把这次更改提交为什么？”或“总结我的 diff”
用户希望为团队或开源项目建立更好的提交历史
用户正在准备 pull request，并希望提交消息更有意义

Prerequisites

前置条件

Have at least one of the following ready:

Output from
```
git diff
```
or
```
git diff --staged
```
A description of what you changed and why
A list of modified files

至少准备好以下内容之一：

```
git diff
```
或
```
git diff --staged
```
的输出
对更改内容及其原因的描述
已修改文件的列表

How It Works

工作原理

Step 1: Gather the Change Context

第 1 步：收集更改上下文

Ask the user (or infer from the diff) for:

What changed — files, functions, logic affected
Why it changed — bug fix, new feature, refactor, performance, etc.
Who/what triggered it — issue number, user request, tech debt, etc.

If the user provides a raw

git diff

, extract this context automatically from the diff.

询问用户（或从 diff 中推断）以下信息：

改了什么 — 涉及哪些文件、函数和逻辑
为什么更改 — bug 修复、新功能、重构、性能优化等
由什么触发 — issue 编号、用户请求、技术债务等

如果用户提供了原始

git diff

，则自动从 diff 中提取这些上下文。

Step 2: Identify the Commit Type

第 2 步：确定提交类型

Map the change to a Conventional Commits type using this guide:

Type	Use When
`feat`	A new feature or capability is added
`fix`	A bug or incorrect behavior is corrected
`refactor`	Code restructured without changing behavior
`perf`	A change that improves performance
`docs`	Documentation only changes
`style`	Formatting, whitespace, missing semicolons (no logic change)
`test`	Adding or updating tests
`chore`	Build process, dependency updates, config changes
`ci`	CI/CD pipeline changes
`revert`	Reverting a previous commit

See

references/conventional-commits-guide.md

for detailed examples.

根据以下指南将更改映射到 Conventional Commits 类型：

Type	使用场景
`feat`	添加了新功能或新能力
`fix`	修复了 bug 或错误行为
`refactor`	重构了代码，但未改变行为
`perf`	更改提升了性能
`docs`	仅修改了文档
`style`	仅调整格式、空格或分号等，不涉及逻辑变更
`test`	添加或更新了测试
`chore`	调整了构建流程、依赖或配置
`ci`	更改了 CI/CD 流水线
`revert`	撤销了之前的提交

有关更详细的示例，请参阅

references/conventional-commits-guide.md

。

Step 3: Write the Commit Message

第 3 步：编写提交消息

Follow this structure:

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

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

<footer — issue refs, breaking change notices>

遵循以下结构：

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

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

<footer — issue refs, breaking change notices>

Rules for Each Part

各部分的规则

Subject line (first line):

Use imperative mood: "add", "fix", "remove" — not "added" or "fixes"
Max 72 characters
No period at the end
Lowercase after the colon

Body (the story):

Explain the why, not the what (the diff already shows the what)
Describe the problem that existed before this change
Mention any alternatives considered if relevant
Keep lines under 100 characters
Separate from subject with a blank line

Footer:

Reference issues:
```
Closes #123
```
,
```
Fixes #456
```
,
```
Refs #789
```
Mark breaking changes:
```
BREAKING CHANGE: <description>
```

Subject（主题行，第一行）：

使用祈使语气，例如
```
add
```
、
```
fix
```
、
```
remove
```
，不要使用
```
added
```
或
```
fixes
```
最多 72 个字符
末尾不要加句号
冒号后使用小写字母

Body（正文，即故事）：

解释为什么更改，而不是改了什么（diff 已经展示了改了什么）
描述此次更改之前存在的问题
如有必要，提及其他考虑过的替代方案
每行保持在 100 个字符以内
与主题行之间空一行

Footer（尾部）：

引用 issue：
```
Closes #123
```
、
```
Fixes #456
```
、
```
Refs #789
```
标记破坏性变更：
```
BREAKING CHANGE: <description>
```

Step 4: Generate Output

第 4 步：生成输出

Produce the commit message in a copyable code block, followed by a one-line plain-English explanation of the story you told.

Example output:

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

Story told: A silent infinite loop on session expiry was crashing the app; this stops the cycle early and returns a clean error.

在可复制的代码块中生成提交消息，随后附上一行简明英文说明，解释你所讲述的故事。

示例输出：

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

讲述的故事： 会话过期时原本会静默触发无限循环并导致应用崩溃；此次更改会提前终止循环，并返回清晰的错误。

Multiple Commits from One Diff

从一个 Diff 生成多个提交

If the diff contains logically separate changes, split them into multiple commit messages and tell the user. Use this heuristic:

Different files with unrelated purposes → likely separate commits
Same file but distinct concerns (e.g., bug fix + refactor) → suggest splitting
Everything tightly coupled → one commit is fine

如果 diff 中包含逻辑上相互独立的更改，则将其拆分为多条提交消息，并告知用户。可以使用以下判断方法：

不同文件且用途无关 → 很可能是独立的提交
同一文件但涉及不同关注点，例如 bug 修复与重构 → 建议拆分
所有更改紧密关联 → 使用一条提交即可

Edge Cases

边界情况

Situation	How to Handle
User provides no context beyond a diff	Infer type and scope from file names and changed symbols
Changes span many files with no clear theme	Ask: "Is this one logical change, or multiple?"
Breaking change detected	Add `BREAKING CHANGE:` footer automatically
User says "keep it short"	Omit body, just write a strong subject line
No issue number available	Omit the footer entirely

情况	处理方式
用户除 diff 外未提供任何上下文	根据文件名和变更的符号推断类型与 scope
更改涉及许多文件且没有明确主题	询问：“这是一项逻辑变更，还是多项变更？”
检测到破坏性变更	自动添加 `BREAKING CHANGE:` footer
用户要求“保持简短”	省略正文，只编写有力的主题行
没有可用的 issue 编号	完全省略 footer

Quick Reference

快速参考

bash

undefined

bash

undefined

Get your staged diff to paste into Copilot

git diff --staged

Or get the last uncommitted working tree changes

git diff


See `references/conventional-commits-guide.md` for type examples and scope guidelines.

git diff


有关类型示例和 scope 指南，请参阅 `references/conventional-commits-guide.md`。