<!-- title: 造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 这样写：

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

三个字段的作用与坑：

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

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

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

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

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

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

```markdown
# 生成规范提交信息

## 工作流程

### 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` 正文里加一句引导：

```markdown
> 如对 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` 完整内容**：

```markdown
---
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. 组装
```
<type>(<scope>): <描述，祈使句，≤50字>

- 要点1（说 Why）
- 要点2
```

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

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

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

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

```markdown
# 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 写完不算完，要验证它在 **自动触发** 和 **手动调用** 两种模式下都正常。

**测试步骤**：

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

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

**常见问题**：

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

## 工作流程图

```mermaid
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 按需、权限受限。

## 延伸阅读

- **Conventional Commits 官方规范**：`conventionalcommits.org`，所有 type、scope、breaking change 标记的权威出处。
- **Claude Code 官方 Skills 文档**：`code.claude.com/docs/en/skills`，目录结构、frontmatter、分发方式的官方说明。
- **Anthropic Skill 作者最佳实践**：`platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices`，专门讲如何写出 Claude 能稳定发现并正确使用的 Skill。
- **内置 skill-creator**：Claude Code 自带的 `/skill-creator` 命令，能通过对话半自动生成 Skill 骨架，适合不想从零手写时起步。

## 训练营适用性评估

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

## 参考来源

1. [Extend Claude with skills — Claude Code 官方文档](https://code.claude.com/docs/en/skills) — Skill 创建、管理、分发的权威说明，含目录结构与 frontmatter。
2. [Skill authoring best practices — Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — 官方给出的 Skill 写作最佳实践，重点讲 description 与渐进式披露。
3. [SKILL.md frontmatter reference — claudskills.com](https://claudskills.com/learn/skill-md-frontmatter-reference/) — 逐字段解释 name / description / allowed-tools / disable-model-invocation 等 YAML 选项。
4. [Conventional Commits 1.0.0 规范](https://www.conventionalcommits.org/zh-hans/v1.0.0/) — 本教程所采用的提交信息规范，type、scope、breaking change 标记的出处。
5. [Claude Code Skills 2026 — Progressive Disclosure 深度解析](https://anhtu.dev/claude-code-skills-2026-progressive-disclosure-and-how-to-standardise-workflow-for-engineering-teams-1062) — 三层渐进式披露架构与工程团队标准化实践的详解。

> [!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学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)