Git故事化提交消息技能：让每一次 commit 都成为可读的开发文档
- 解决什么问题：commit message 写成“更新”“修复一下”是团队通病，技能把“写清楚提交信息”这件事变成有章可循的流程，而不是靠个人自觉。
- 核心方法：以“主题行 + 正文 + 页脚”三部分结构为基础，配合 feat / fix / docs / refactor / test / perf / style / chore / revert 类型前缀，约束 50 字符主题行与 72 字符正文换行。
- 能力边界：技能本身只“教怎么写”，它允许 AI 助手调用 Bash 与 Read 两个工具去读改动、看历史，再产出符合规范的提交消息，不涉及代码逻辑改动。
- 适配人群：个人开发者、团队协作项目、开源贡献者、需要生成发布说明与变更日志的维护者。
- 上手成本：极低，装好之后一句自然语言指令即可触发，重点在于团队是否愿意统一约定。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
这个技能的中文名是 Git故事化提交消息技能，英文名 git-storytelling-commit-messages，技能 ID 为 14086。
它瞄准的是一个被长期忽视、却几乎每个开发者每天都会遇到的痛点：提交消息写得太随意。一次 git commit -m "update" 看似省了三秒，代价却是半年后没人（包括你自己）知道这次改动到底为什么发生。技能详情里写得很直白——提交消息要服务于未来开发者、代码审查者、项目经理、自动化变更日志工具，以及 git blame、git log、git bisect 这类调试场景。换句话说，提交消息不是写给当下的自己看的，而是写给“未来的所有人”看的。
“一键安装”的思路是：把一套成熟的写作规范封装成 AI 技能，让写作规范的执行从“靠记忆”变成“靠工具”。安装与使用的基本前提和步骤如下：
- 准备环境：你需要一个支持加载 AI 技能的编程助手客户端，并且在本地或云端具备可用的 Git 仓库。技能详情里声明它允许使用 Bash 与 Read 两个工具，因此客户端需要开放相应的工具权限，AI 才能读取改动内容与提交历史。
- 获取技能：在技能市场或技能库中通过技能 ID 14086 或英文名 git-storytelling-commit-messages 检索并安装，具体入口、命令与操作路径以官方说明为准。
- 启用技能：在项目会话中启用该技能，确保它处于可被调用的状态。多数客户端支持“项目级启用”与“会话级启用”两种方式，按你所在团队的协作习惯选择即可，具体形式以官方说明为准。
- 验证是否生效：暂存一小段改动，然后用自然语言让助手“按技能规范生成一条提交消息”。如果返回的消息带有
feat:、fix:这类类型前缀、主题行简短、正文解释了“为什么”，说明技能已经正常生效；如果返回的仍是“更新文件”这类泛泛之词，则需要检查技能是否启用成功。 - 固化到流程：把技能写进团队的提交规范说明里，或在代码评审清单中增加“提交消息是否符合规范”一项，让“一键生成”真正变成“一键落地”。
2. 该技能的主要功能和特点
- 三部分结构强制成型：主题行（50 字符以内的简短摘要）、正文（解释“什么”和“为什么”）、页脚（问题引用、重大更改、合作作者），结构固定，读者可以快速扫读。
- 类型前缀体系完整：覆盖
feat（新功能）、fix（错误修复）、docs（文档）、refactor（重构）、test（测试）、perf（性能）、style（格式化）、chore（维护任务），并额外支持revert（回滚），避免“feat / feature / add”混用导致历史混乱。 - 祈使语气约束：强调“添加功能”而不是“已添加功能”，这条规则看似吹毛求疵，实际直接决定了
git log --oneline读起来像不像一份命令清单。 - 正文写作有明确指引：要求说明什么改变了、为什么改、有无副作用、考虑过哪些替代方案、有哪些不明显的上下文，并规定每行 72 字符换行、用项目符号列举多项内容。
- 页脚要素齐全：支持
引用: #123、关闭: #789、重大更改:、合作作者:等写法，为语义化版本管理和自动化变更日志生成留好接口。 - 八类场景范式示例：详情中给出了带上下文的 feat、带根本原因的 fix、带动机的 refactor、带指标的 perf、带安全严重性说明的 fix、带迁移步骤的依赖升级、带回滚原因说明的 revert 等具体范例，可直接对照套用。
- 附带工程化手段：给出
~/.gitmessage提交模板的配置方式、commit-msg钩子脚本示例（校验类型前缀、检查主题行长度），以及git log --format="%h %s" | awk 'length($0) > 52 { print }'这类自查命令，让规范从“AI 提醒”升级为“工具强制”。 - 常见陷阱清单：明确列出“模糊主题行”“使用过去时”“主题以句号结尾”“把文件名塞进主题”“缺少重大更改警告”等 15 条反面案例。
和普通工具比强在哪？ 对比单纯的规范文档，它把规范变成了“被 AI 主动执行的动作”；对比只做格式校验的钩子脚本，它能补充正文里的“为什么”，而钩子只能拦住格式错误，拦不住内容空洞。
3. 如何使用该技能？
以下流程适用于绝大多数支持技能的 AI 编程助手，具体指令措辞可自行调整。
第 1 步：完成改动并暂存
先用 git add 把你打算提交的改动放进暂存区。如果改动跨越多个独立主题，建议拆成多次提交——技能强调“具体范围”，一条提交消息只讲一件事。
第 2 步：发起调用
在助手会话中用自然语言描述诉求，例如：
请读取当前暂存区的 diff 和最近的提交历史，
按 git-storytelling-commit-messages 技能规范，
为我生成一条符合约定式提交格式的消息。
重点说明这次改动的动机和副作用。
技能允许调用 Bash 与 Read，因此助手可以自行执行类似 git diff --staged、git log --oneline -10 的命令获取上下文。
第 3 步：阅读并校验输出
一条合格的输出长这样：
feat: 添加密码重置功能
实现带邮箱验证的密码重置流程：
- 生成安全重置令牌
- 发送带有效期的重置邮件
- 在允许密码更改前验证令牌
- 记录密码重置事件用于安全审计
引用: #234
检查三件事：类型前缀是否正确、主题行是否在 50 字符内且用祈使语气、正文是否解释了“为什么”而非复述“改了什么”。
第 4 步：迭代与修正
如果输出不满意，可以直接告诉助手“正文太笼统，请补充根本原因”或“主题行超过 50 字符，请精简”。如果已经提交但消息写错了，可用 git commit --amend 修改最后一次提交消息，或用 git rebase -i 编辑历史提交消息（谨慎用于已推送的公共分支）。
第 5 步：沉淀为团队约定
把技能推荐的模板写进本地配置，让每次 git commit 都弹出结构提示；再把 commit-msg 钩子加进仓库，拦截缺少类型前缀或主题行超长的提交。这一步做完，规范才真正从“建议”变成“默认”。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| git-storytelling-commit-messages（本技能） | AI 技能，把提交规范变成助手可执行的动作 | 三部分结构、类型前缀、祈使语气、页脚要素、八类场景范例、模板与钩子建议 | 需支持技能的 AI 助手客户端，开放 Bash 与 Read 权限；安装入口以官方说明为准 | 日常开发提交、代码评审准备、开源贡献、变更日志生成 | 优势：能自动补全“为什么”这类钩子校验不了的内容，学习成本低；不足：依赖 AI 客户端的工具权限，团队仍需统一个人习惯 |
| 约定式提交规范（Conventional Commits）人工遵循 | 行业通用的文本规范 | 定义类型前缀、破坏性变更标记、页脚格式 | 零安装，纯靠记忆与自律 | 追求轻量约束的小团队 | 优势：无依赖、通用性强；不足：没有执行者，规范容易在赶进度时被放弃 |
| 交互式提交工具（如 Commitizen 一类，以官方说明为准） | 命令行向导式提交流程 | 分步提问生成格式化的提交消息、可对接变更日志工具 | 需在项目中安装配置，具体方式以官方说明为准 | 希望强制统一格式的团队 | 优势：格式化可靠、与工具链集成好；不足：只能保证格式，正文内容质量仍取决于填写者 |
| 通用 AI 助手的默认提交消息生成 | 大模型直接根据 diff 生成 | 生成一段概括性描述 | 无需额外安装技能 | 临时性、非正式的本地提交 | 优势：开箱即用；不足：格式不统一、容易复述代码细节而忽略动机，缺少重大更改提示 |
选型建议：如果你只想要“格式别乱”，钩子脚本就够了；如果你希望“历史可读、动机可追溯”，本技能的价值才真正体现；两者叠加使用效果最好。
5. 该技能的典型应用场景与实际体验情况
场景一：个人开发者维护长期项目
痛点是自己半年后回看代码，完全不记得某次重构的动机。使用方式是在提交前让助手读取 diff 生成消息，重点让它补上“为什么改”。实际体验：上手几乎没有门槛，改变的是习惯而非流程；坚持一两个月后，git log --oneline 会从一串“更新”变成一条清晰的演进时间线。需要注意的是，小改动也不必强行凑正文，技能本身也把正文标为“可选”。
场景二：团队协作与代码评审
评审者最怕看到一大坨 diff 配一句“修复问题”。使用方式是要求提交消息必须引用 issue 编号并在正文写明影响范围。实际体验：评审沟通成本明显下降，评审者能先读懂意图再看实现。注意点是要在团队内统一类型前缀的写法，避免 feat 与 feature 并存。
场景三：开源项目贡献 维护者对 PR 的提交质量要求通常更高，重大更改必须显式标注，否则会坑到下游用户。技能详情里“重大更改”的写法（旧格式 vs 新格式、迁移步骤 1/2/3）在这里特别好用。实际体验：贡献被接受的概率会提高，因为维护者不必再反复要求你改写提交信息。
场景四：生成发布说明与变更日志
自动化工具依赖规范化的类型前缀来归类“新功能 / 修复 / 破坏性变更”。使用方式是回溯检查当前分支的提交（例如查看 git log main..HEAD --format="%B"），把不合格的用 rebase -i 修正。实际体验：发版前的整理时间从半天压缩到几十分钟。注意：已经推送并被他人拉取的历史，不要随意改写。
6. 该技能能为用户带来的价值
第一，把隐形成本显性化。 一条含糊的提交消息省下的是几秒钟，消耗的是未来每一次排查时重新理解代码的时间。技能用固定结构逼出“动机”和“副作用”这两项信息，这是任何 diff 都无法直接告诉你的。
第二，降低团队规范落地门槛。 规范文档的问题在于“读过就忘”，技能把它变成助手在每次提交时主动执行的动作，从“要求人记得”变成“工具帮你记”。
第三，为工程效能工具链打好地基。 类型前缀统一之后，自动化变更日志、语义化版本号推导、发布说明生成才有可靠输入。技能详情里提到的 commit-msg 钩子、~/.gitmessage 模板，正是把这份价值固定下来的手段。
第四，长期可搜索的资产。 技能结论里写得很清楚：精心编写的提交消息是对项目未来的投资。一年后你能用 git log --author="你的名字" 检索自己的所有改动，用 git bisect 快速定位引入问题的提交——这些能力都建立在“消息写得清楚”之上。
7. 常见问题 FAQ
Q1：这个技能怎么安装？需要什么前提？ 在支持 AI 技能的市场或技能库中，通过技能 ID 14086 或英文名 git-storytelling-commit-messages 检索并安装，具体入口与命令以官方说明为准。前提是你的 AI 编程助手客户端支持加载技能，并开放 Bash 与 Read 两个工具的权限，否则助手无法读取改动内容和提交历史。
Q2：使用这个技能收费吗？ 技能本身的功能范围是提供提交消息写作规范与示例，是否收费取决于所在技能平台与客户端版本的商业策略，以官方说明为准。技能不依赖任何付费第三方服务。
Q3：它适合谁用？新手会不会太复杂？ 适合所有需要写 commit 的人：个人开发者、团队协作成员、开源贡献者、需要维护变更日志的项目维护者。新手完全可以从最简单的部分开始——先只要求“类型前缀 + 50 字符以内的祈使句主题行”，等形成习惯后再逐步补充正文和页脚。
Q4：它和 Commitizen 这类交互式工具冲突吗？该怎么选？ 不冲突。交互式工具解决的是“格式强制”，本技能解决的是“内容质量”，两者可以叠加：用工具保证字段结构，用技能补足动机说明。如果你的团队只在意格式统一，工具就够了；如果你希望提交历史兼具可读性与可追溯性，技能带来的增量更大。
Q5：它会自动帮我提交代码吗？ 技能的职责是生成符合规范的提交消息文本。虽然它允许调用 Bash，理论上具备执行命令的能力，但实际是否自动执行取决于你的客户端配置与权限设置。稳妥做法是：生成的提交信息先人工过一遍再执行提交，尤其是涉及重大更改或安全修复时。