前言¶
用 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/
