前言¶
用 AI 辅助写代码已经很常见，但提交信息往往还是一笔糊涂账：update、fix stuff、WIP 这类消息在团队协作里几乎没法检索，Changelog 自动生成工具也读不懂。Conventional Commits 规范用类型前缀、可选 scope 和正文，把提交变成「人能读、机器也能解析」的结构化文本；问题在于，让 Agent 每次都自觉遵守同一套规则并不容易。
writing-commit-messages 正是为这件事准备的 Agent Skill：把 Conventional Commits 的格式、类型表、好坏示例和破坏性变更写法写进 SKILL.md，Agent 在写 commit 时按同一套指令执行。本文介绍它是什么、核心规则、如何安装启用，以及典型用法。
这是什么¶
writing-commit-messages 来自 GitHub 仓库 spencerpauly/awesome-cursor-skills，目录为 resources/writing-commit-messages/。仓库将其归在 Workflow 一类，官方一句话说明是：撰写带类型前缀、scope 和有意义描述的 Conventional Commit 信息。
Skill 本身是一份可复用的 SKILL.md 指令文件。按 Agent Skills 通用格式，可在 Cursor、Claude Code、Codex CLI 等支持该标准的 AI 编程工具中使用。frontmatter 中声明了：
name: writing-commit-messagesdescription: Write clear, conventional commit messages with proper type prefixes, scopes, and body content.user-invocable: true（支持用户主动调用）
它解决的核心问题很具体：约束 Agent 生成清晰、一致、可被工具解析的提交信息，而不是随口写一句「改了一点东西」。
核心功能与规范¶
Skill 要求提交信息对人和机器都有用，并采用 Conventional Commits 常见结构：
<type>(<optional scope>): <subject>
<optional body>
<optional footer>
主题行规则¶
- 主题（subject）控制在 50 个字符以内
- 使用祈使语气：写
add feature，不要写added feature或adding feature - 类型前缀之后的首字母不要大写
- 主题行末尾不加句号
类型（type）¶
| Type | 适用场景 |
|---|---|
feat |
面向用户的新功能 |
fix |
缺陷修复 |
refactor |
不改变行为的代码重组 |
docs |
文档变更 |
test |
新增或更新测试 |
chore |
构建、CI、工具链、依赖等 |
perf |
性能优化 |
style |
格式/空白调整（不是指 CSS） |
ci |
CI/CD 流水线变更 |
revert |
回滚先前提交 |
这与 Conventional Commits 1.0.0 的约定一致：feat / fix 对应 SemVer 的 MINOR / PATCH；带 BREAKING CHANGE 或类型后的 ! 则对应 MAJOR。
Scope（可选）¶
用括号标明受影响的代码区域，例如：
feat(auth): add OAuth2 login flowfix(api): handle null response from payments endpointrefactor(db): extract query builder into module
Body 与 Footer¶
正文需要时再写，重点解释 为什么，而不是重复 diff 里已经能看到的「改了什么」。页脚可放破坏性变更说明、关联 Issue、共同作者等，例如：
BREAKING CHANGE: rename `getUserById` to `findUser`
Closes #456
Co-authored-by: Name <email>
破坏性变更¶
若本次提交引入破坏性变更，Skill 要求：
- 在 type 后加
!，例如：feat(api)!: change auth token format - 在 footer 中写
BREAKING CHANGE:，并附上迁移说明
何时提交¶
Skill 还约束提交粒度：
- 一次提交对应一个逻辑变更
- 不要把重构和功能开发混在同一次提交里
- 不要提交半成品（可用
git stash） - 功能分支上可频繁提交，合并前按需 squash
安装与启用¶
方式一：手动放入项目（Cursor）¶
awesome-cursor-skills 仓库说明：把 SKILL.md 复制到项目的 .cursor/skills/ 目录后，Agent 会自动发现。可按下面结构放置：
.cursor/skills/writing-commit-messages/SKILL.md
也可放到用户级目录 ~/.cursor/skills/，便于多个项目共用。Cursor 官方文档还写明会从 .agents/skills/、~/.agents/skills/ 加载，并为兼容 Claude / Codex 读取 .claude/skills/、.codex/skills/ 等路径。
原始文件地址：
https://github.com/spencerpauly/awesome-cursor-skills/blob/main/resources/writing-commit-messages/SKILL.md
方式二：用 skills CLI 安装¶
vercel-labs/skills 提供的 npx skills 可从 GitHub 仓库安装指定 Skill。针对本 Skill，可按目标 Agent 选用：
安装到 Cursor：
npx skills add spencerpauly/awesome-cursor-skills --skill writing-commit-messages --agent cursor
安装到 Claude Code：
npx skills add spencerpauly/awesome-cursor-skills --skill writing-commit-messages --agent claude-code
需要全局安装时可加 -g。安装后，在 Cursor Agent 对话里可用 / 搜索并调用技能名（例如 /writing-commit-messages），也可在相关上下文中由 Agent 自动选用。
典型用法示例¶
启用后，让 Agent 根据当前改动写提交信息即可。Skill 给出的正反例如下。
推荐写法：
feat(dashboard): add real-time notification bell
fix: resolve race condition in WebSocket reconnect
refactor(api): consolidate error handling middleware
test: add integration tests for payment webhook
chore: upgrade TypeScript to 5.4
带正文的修复示例：
fix(checkout): prevent duplicate order submissions
The submit button was not disabled after the first click,
allowing users to create multiple orders. This caused
duplicate charges in Stripe.
应避免的写法：
fixed stuff
WIP
update
changes
asdf
实际对话里可以这样触发，例如：
请根据当前暂存区改动写一条 Conventional Commit 提交信息，并执行提交。
或显式调用：
/writing-commit-messages
请为这次支付回调相关的修复写 commit message。
Agent 应按 Skill 选择合适的 type / scope，主题行用祈使语气，必要时补充 body 或 BREAKING CHANGE footer。
适用场景与注意事项¶
适合这些情况：
- 团队已采用或计划采用 Conventional Commits，希望 Agent 输出与人工规范一致
- 需要从提交历史自动生成 Changelog，或配合 semantic-release 等工具做版本 bump
- 多人协作、Code Review 时希望提交历史可检索、可分类
- 与同仓库的
creating-pr等 Workflow Skill 搭配，保持 PR 标题与 commit 风格统一
使用时注意：
- Skill 约束的是消息格式与提交习惯，不会替你审查 diff 是否正确；提交前仍应自己确认改动范围
- 类型表以本 Skill 列出的为准；若团队另有约定（例如额外使用
build），需要在项目规则或本地改写 Skill 中补充 - 「一次一个逻辑变更」依赖 Agent 正确拆分暂存内容；若工作区混杂多种改动，应先自行分批
git add，再让 Agent 写消息 - 规范本身不能替代 code review；坏消息少了，不代表坏代码少了
小结¶
writing-commit-messages 把 Conventional Commits 的结构、类型、scope、正文/页脚和破坏性变更写法固化成 Agent 可执行的指令，适合作为日常编码工作流里最基础的 Skill 之一。安装成本低：复制一份 SKILL.md，或用 npx skills add 指定 --skill writing-commit-messages 即可。
官方地址：https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/writing-commit-messages
规范原文可对照：https://www.conventionalcommits.org/en/v1.0.0/
