造Commit信息Skill：读diff秒出规范提交

首页 › tutorials › 造Commit信息Skill：读diff秒出规范提交

概述

本教程带你从零打造一个 Claude Code 自定义 Skill —— commit-message，它能读懂 git diff、自动判别变更类型、生成符合 Conventional Commits 规范的提交信息，并支持中英双语与 emoji 前缀。学完你将掌握 Skill 的目录结构、frontmatter 写法、渐进式披露（Progressive Disclosure）三层架构，以及触发测试与迭代优化。适合已装好 Claude Code、想用 Skill 把重复操作固化成"一句话能力"的开发者。

前置条件

已安装 Claude Code 并能在终端正常启动（claude 命令可用）
一台装了 Git 的机器，且本地有一个 git 仓库可供测试
了解 Conventional Commits 规范的基本概念（不知道也没关系，本教程会带）
一个文本编辑器（VS Code 即可），用于查看生成的 SKILL.md

一、先搞清楚：为什么用 Skill 而不是直接写提示词

很多人第一次想把"生成 commit 信息"这个动作固化下来时，会纠结：到底是写进 CLAUDE.md，还是做成 Skill？

方案	何时加载	上下文成本	可复用性
写进 `CLAUDE.md`	每次会话都加载	始终占用	单项目
临时口头指令	一次性	用完即丢	不可复用
做成 Skill	按需加载	用才进上下文	跨项目共享

关键区别在于 按需加载：Skill 的 description 平时只占很小的 token，只有当你的需求匹配它描述的场景时，Claude 才把完整指令读进上下文。这正是渐进式披露（Progressive Disclosure）的核心思想——把上下文留给真正需要它的那一刻。

所以结论很清晰：高频、可复用、偶尔才用 的能力，做成 Skill 最划算。生成 commit 信息完美命中这三条。

二、确定 Skill 目录与骨架

Claude Code 的 Skill 存放在固定位置，按作用域分三种：

用户级（全局可用）：~/.claude/skills/<skill-name>/SKILL.md
项目级（仅当前仓库）：<repo>/.claude/skills/<skill-name>/SKILL.md
插件级（随插件分发）：plugins/<plugin>/skills/<skill-name>/SKILL.md

我们的 commit-message 想在任何项目都用，所以放在用户级。

操作：在 Claude Code 里直接用自然语言下达指令，让它帮你创建骨架。

请在 ~/.claude/skills/ 下创建一个名为 commit-message 的 skill，
目录里放一个 SKILL.md，内容先留骨架。

预期结果：Claude 会创建如下目录结构。

~/.claude/skills/commit-message/
└── SKILL.md

常见问题：建完之后怎么确认生效？退出当前会话重新进入，或在会话里输入 / 看命令列表能否找到它（手动调用时会以 /<skill-name> 形式出现）。如果没出现，多半是目录名和 frontmatter 里的 name 不一致。

三、写好 frontmatter：description 是灵魂

SKILL.md 顶部是一段 YAML frontmatter，被 --- 包裹。对 commit-message 这个 Skill，frontmatter 这样写：

---
name: commit-message
description: 读取 git diff / staged 改动，生成符合 Conventional Commits 规范的提交信息。当用户准备提交代码、想要 commit message、问"这次改动怎么写提交信息"、或显式说"生成提交信息"时使用。支持中英双语与 emoji 前缀。
allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*)
---

三个字段的作用与坑：

name：必须与目录名完全一致，用 kebab-case（连字符小写）。
description：整个 Skill 最关键的一行。Claude 靠它判断"现在该不该加载这个 Skill"。写法三原则： - 用第三人称描述它"做什么"； - 明确列出"何时使用"，把用户可能说的话写进去（"想要 commit message""怎么写提交信息"）； - 覆盖关键词（commit、提交信息、Conventional Commits）。 - 反面教材：只写"帮我生成提交信息"——没有触发场景，Claude 不知道什么时候该用。
allowed-tools：最小权限白名单。我们只让它跑只读的 git 命令（diff/status/log），故意不放 git commit——是否真正提交交由人工确认，避免 AI 自作主张 push。这是把"建议"和"执行"分离的安全设计。

预期结果：保存后，Claude 在后续会话里一旦识别到"提交信息"相关意图，就会自动加载这个 Skill 的正文。

常见问题：发现 Skill 总是不自动触发？八成是 description 缺少用户视角的关键词。修法：把你自己平时会脱口而出的那句话原样写进 description。

四、编写正文指令：把"生成提交信息"拆成确定性流程

frontmatter 之下就是 Markdown 正文，这才是 Claude 加载后真正读的"操作手册"。写正文的核心心法是 把模糊任务拆成确定性步骤，而不是泛泛地说"给我写个好的提交信息"。

正文骨架如下（写到 SKILL.md 里 frontmatter 之后）：

# 生成规范提交信息

## 工作流程

### 1. 采集变更
运行以下命令获取改动全貌（注意只读，不要执行任何修改操作）：
- `git status --short`：看改了哪些文件、是新增/修改/删除
- `git diff --staged`：看已暂存改动（优先用这个）
- `git diff`：看未暂存改动
- 若两者都为空，提示用户先 `git add`

### 2. 分类变更类型
依据改动内容，映射到 Conventional Commits 的 type：
- feat：新功能
- fix：修 bug
- docs：文档
- style：格式（不影响逻辑）
- refactor：重构（既非新增功能也非修 bug）
- perf：性能优化
- test：测试相关
- build：构建系统/依赖
- ci：CI 配置
- chore：杂务
- revert：回滚
若一次改动跨多个 type，按"影响最大者优先"选主 type，其余写进正文要点。

### 3. 提取 scope（可选）
scope 用括号标注影响范围，取自被改动的模块/包名，如 `feat(auth):`。
无法明确范围时省略，不要硬编。

### 4. 组装信息
按规范组装：
<type>(<scope>): <简明描述，祈使句，≤50字>
空行
<正文，每条以 - 开头，说明 Why 而非 What>

### 5. 询问偏好（首次使用时）
若不确定用户语言/emoji 偏好，先用一句话询问：
"提交信息用中文还是英文？要不要 emoji 前缀？"
记住本次选择，后续默认沿用。

### 6. 输出与确认
先展示建议的提交信息（放在代码块里方便复制），再问：
"是否需要我帮你执行 git commit？（默认仅生成，不提交）"
只有用户明确同意，且本 Skill 也不具备 commit 权限时，
引导用户自行复制执行。

这套流程把"读改动 → 判类型 → 定范围 → 组装 → 确认偏好 → 输出"串成了确定性 pipeline，Claude 每一步都有明确动作，质量才稳定。

预期结果：做完一次 git add 后说"帮我生成这次提交信息"，Claude 会先跑只读 git 命令，再按规范产出信息。

常见问题：生成的描述太长、超出 50 字？在正文里加一条硬约束："描述行严格 ≤50 个字符，超出时精简"。Skill 正文就是你给 AI 立的规矩，越具体越好。

五、引入规范参考：用渐进式披露第二层

把 Conventional Commits 全套规则塞进 SKILL.md 正文，会让正文臃肿、每次都吃 token。正确做法是 第二层 —— references/ 目录：详细规范放这里，正文只在需要时引导 Claude 去读。

操作：在 skill 目录下建 references/commit-convention.md，把完整的 type 表、scope 约定、breaking change 标记法（! 或 BREAKING CHANGE: 脚注）写进去。

~/.claude/skills/commit-message/
├── SKILL.md
└── references/
    └── commit-convention.md

然后在 SKILL.md 正文里加一句引导：

> 如对 type 选择或 breaking change 标记存疑，先读 references/commit-convention.md。

这就是渐进式披露的精髓：正文给骨架，references 给细节，按需加载。平时 Claude 只看正文（省 token），遇到边界情况才把 references 拉进上下文。

预期结果：处理一次"包含破坏性变更"的提交时，Claude 会主动去读规范文件，正确加上 feat(api)!: 前缀或脚注。

常见问题：references 文件名随便取？尽量取语义化名字，且正文引导里写死文件名，避免 Claude 找不到。

六、完整实战案例：commit-message Skill 全貌

把前面拼起来，下面是一个可直接落地的完整目录与文件内容。

目录结构：

~/.claude/skills/commit-message/
├── SKILL.md
└── references/
    └── commit-convention.md

SKILL.md 完整内容：

---
name: commit-message
description: 读取 git diff / staged 改动，生成符合 Conventional Commits 规范的提交信息。当用户准备提交代码、想要 commit message、问"这次改动怎么写提交信息"、或显式说"生成提交信息"时使用。支持中英双语与 emoji 前缀。
allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*)
---

# 生成规范提交信息

## 工作流程

### 1. 采集变更
只读运行（禁止任何修改/提交操作）：
- `git status --short`
- `git diff --staged`（优先）
- `git diff`
改动为空时提示用户先 `git add`。

### 2. 分类 type
feat / fix / docs / style / refactor / perf / test / build / ci / chore / revert。
跨类型时取影响最大者为主 type，其余进正文。

### 3. 提取 scope（可选）
取自被改模块名，无法明确则省略。

### 4. 组装

(): <描述，祈使句，≤50字>

要点1（说 Why）
要点2

### 5. 偏好
首次询问语言（中/英）与 emoji 前缀，记忆沿用。

### 6. 输出
代码块展示建议信息，问是否需要代为执行（本 Skill 无 commit 权限，
引导用户自行复制提交）。

> type 选择或 breaking change 标记存疑时，先读 references/commit-convention.md。

references/commit-convention.md 完整内容：

# Conventional Commits 速查

## 类型（type）
| type | 含义 |
|------|------|
| feat | 新功能 |
| fix | 修缺陷 |
| docs | 文档 |
| style | 格式（不改逻辑） |
| refactor | 重构 |
| perf | 性能 |
| test | 测试 |
| build | 构建/依赖 |
| ci | CI 配置 |
| chore | 杂务 |
| revert | 回滚 |

## 破坏性变更
两种写法：
- 标题加 `!`：`feat(api)!: 重构认证返回结构`
- 脚注：标题下方正文写 `BREAKING CHANGE: 原字段 token 改为 accessToken`

## scope
取受影响模块/包名，如 `auth`、`api`、`ui`；不确定时省略。

## emoji 前缀（可选）
feat ✨ / fix 🐛 / docs 📝 / refactor ♻️ / perf ⚡ / test ✅ / chore 🔧。

使用演示：在某仓库改完代码并 git add 后，对 Claude 说：

帮我生成这次提交信息，中文，要 emoji。

Claude 会跑只读 git 命令，然后输出类似：

✨ feat(auth): 新增刷新令牌接口

- 旧 access_token 到期前 5 分钟自动刷新
- 复用现有 TokenDao，避免新增表

整个交互，Skill 正文全程未占你额外记忆，只在需要那一刻被加载进来。

七、测试、触发与迭代

Skill 写完不算完，要验证它在 自动触发 和 手动调用 两种模式下都正常。

测试步骤：

手动调用：会话里输入 /commit-message，应能直接进入流程（手动调用不依赖 description 匹配）。
自动触发：新建一个仓库改点东西，然后自然地说"这次改动怎么写提交信息比较好"——看 Claude 是否自动加载本 Skill。没触发就去改 description 的关键词。
权限收敛：故意让它"直接帮我提交"，确认它无法执行 git commit（因为 allowed-tools 没给），只能引导你复制信息自行提交。这是安全设计生效的证明。

迭代心法：每发现一次"生成质量不达预期"，就回正文加一条更具体的约束。Skill 是活的文档，越用越准。

常见问题：

Skill 始终不触发 → description 缺场景关键词，或 name 与目录名不符。
触发后乱跑命令 → allowed-tools 没收敛，把不该给的权限撤掉。
生成信息风格漂移 → 正文约束不够硬，加"≤50 字""祈使句"等明确规则。

工作流程图

flowchart TD
    A[用户: 帮我写提交信息] --> B{description 匹配?}
    B -->|是| C[加载 SKILL.md 正文]
    B -->|否, 手动 /commit-message| C
    C --> D[只读采集 git diff/status]
    D --> E{type 是否存疑?}
    E -->|是| F[加载 references/commit-convention.md]
    F --> G[分类 type + 提取 scope]
    E -->|否| G
    G --> H[组装规范信息]
    H --> I[询问语言/emoji 偏好]
    I --> J[输出建议信息]
    J --> K{用户要代提交?}
    K -->|是, 但无权限| L[引导用户自行复制提交]
    K -->|否| M[结束]

这张图正好对应渐进式披露的三层：正文常驻、references 按需、权限受限。

训练营适用性评估

适合的训练营类型：AI 工程化实战营、研发效能提升营、开发者工具链训练营。本教程从痛点切入、到落地、再到测试迭代，是一条完整的"把经验固化为可复用能力"的闭环，能直接迁移到任何"重复操作 → Skill"的场景。
预计教学时长：约 90–120 分钟。其中 frontmatter 与 description 写作（含试错调试触发）约占 40 分钟，正文流程设计约占 30 分钟，实战案例与测试约占 40 分钟。
学员产出：每人带走一个可立即在自己项目里跑起来的 commit-message Skill，并掌握"需求 → Skill → 测试触发 → 迭代"的方法论。
延伸作业建议：让学员用同一套方法，再造一个 release-notes（读 git log 生成发版说明）或 code-review-checklist（按语言出审查清单）Skill，检验举一反三的能力。

参考来源

Extend Claude with skills — Claude Code 官方文档 — Skill 创建、管理、分发的权威说明，含目录结构与 frontmatter。
Skill authoring best practices — Claude Platform Docs — 官方给出的 Skill 写作最佳实践，重点讲 description 与渐进式披露。
SKILL.md frontmatter reference — claudskills.com — 逐字段解释 name / description / allowed-tools / disable-model-invocation 等 YAML 选项。
Conventional Commits 1.0.0 规范 — 本教程所采用的提交信息规范，type、scope、breaking change 标记的出处。
Claude Code Skills 2026 — Progressive Disclosure 深度解析 — 三层渐进式披露架构与工程团队标准化实践的详解。

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

51学通信知识星球海报-扫码加入

概述