git-commit-message

Name: git-commit-message
Author: vasilyu1983

github.com/vasilyu1983开发84 次安装

代码仓库

关于 git-commit-message

分析已暂存的 Git 差异并建议 Conventional Commits 提交信息的技能。它会分类变更、推断范围，并按三个层级调整信息详略，还支持验证和提供备选建议。

主要功能

01分析已暂存文件变更与差异
02按提交类型分类变更
03根据路径和模式推断范围
04生成分层的 Conventional Commits 信息
05验证信息格式与约束

适用场景

01提交已暂存变更前起草信息
02根据差异选择提交类型和范围
03按仓库规则检查拟定的信息
04比较多个提交信息备选方案

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vasilyu1983/ai-agents-public --skill git-commit-message

安装后在 Claude Code 中输入/git-commit-message确认已加载。

详细介绍

Git 提交信息生成器

根据 git 差异自动生成符合 Conventional Commits 规范、并通过分级格式约束的提交信息

用途

分析已暂存的 git 更改，并根据分级 Conventional Commits 规范生成简洁且有意义的提交信息。此技能会检查文件的修改、新增和删除，以推断更改的类型和范围，并根据更改的重要性生成相应的提交信息——从针对关键功能的详细说明，到针对次要更新的简短信息。

核心创新：三级格式系统，在关键提交（feat、fix、security）的详尽性与常规更改（docs、chore、style）的高效性之间取得平衡。

此技能的触发时机

调用 /commit-msg 命令时
从 commit-msg/prepare-commit-msg hook 调用时（如果已安装）
用户请求提供提交信息建议时
创建提交前分析更改时

核心能力

1. 差异分析

解析 git diff --staged 输出
识别已修改、新增和删除的文件
分析代码更改（新增、删除、修改）
检测多个文件之间的模式

2. 更改分类

根据更改确定提交类型：
- feat：新功能或新特性
- fix：错误修复
- security：安全修复或加固
- refactor：重构代码，不改变行为
- docs：文档更改
- style：格式、空白字符、代码风格
- test：新增或修改测试
- chore：构建流程、依赖项、工具
- perf：性能改进
- ci：CI/CD 配置更改
- build：构建系统更改
- revert：撤销之前的提交

3. 范围检测

根据文件路径和模式推断范围：
- 目录名称（例如 api、auth、ui）
- 文件名模式（例如 *.test.js → tests）
- 框架惯例（例如 components/、services/）

4. 信息生成

格式：type(scope): description
限定各级长度：第 1 级摘要最多 50 个字符；第 2/3 级摘要最多 72 个字符（理想长度为 50 个字符）
使用祈使语气（“add”而非“added”）
聚焦于“是什么”和“为什么”，而非“如何做”
提供 2-3 个备选建议

分级系统：智能格式约束

此技能使用三级格式系统，根据提交的重要性匹配信息的详细程度：

第 1 级：关键提交（feat、fix、perf、security）

要求：详细说明并陈述影响

格式：

type(scope): summary line (max 50 chars)

- Detailed description point 1
- Detailed description point 2
- Detailed description point 3

This change [impact statement describing user-facing benefit or risk addressed].

Affected files/components:
- path/to/file1
- path/to/file2

原因：功能、修复和性能更改会直接影响用户，需要详尽说明，以便日后查阅和生成变更日志。

第 2 级：常规提交（refactor、test、build、ci）

要求：简要说明背景并列出文件

格式：

type(scope): summary line (max 72 chars)

Brief explanation of what changed and why (1-2 sentences).

Files: path/to/file1, path/to/file2

原因：内部改进需要提供背景信息以便维护，但不需要详尽说明。

第 3 级：次要提交（docs、style、chore）

要求：摘要行，可选说明

格式：

type(scope): summary line (max 72 chars)

[Optional: Additional context if helpful]

原因：从差异本身即可看出文档和常规维护的内容；冗长的信息只会增加干扰。

工作流程

0. Pre-staging typecheck (if project uses TypeScript):
   - Run `tsc --noEmit` on changed files before staging
   - Fix type errors before committing (avoids pre-commit hook retry loops)
1. Get staged changes (staged only, not working tree):
   - git diff --staged --name-status
   - git diff --staged --stat
   - git diff --staged
2. Load config → frameworks/shared-skills/skills/git-commit-message/config.yaml
3. Analyze changes:
   - Count files modified/added/deleted
   - Identify primary change type using analysis patterns
   - Detect scope from project structure (config.yaml)
   - Determine tier (1/2/3) based on commit type
   - Extract key modifications
4. Generate commit messages:
   - Apply tier-appropriate format
   - Primary suggestion (best match)
   - Alternative 1 (different scope/angle)
   - Alternative 2 (broader/narrower focus)
5. Validate against rules:
   - Check forbidden patterns
   - Verify required elements present
   - Ensure length limits
6. Present to user with explanation and tier info

可选模式（如果调用方支持）

--validate "<message>"：验证提交信息，不生成建议（检查格式/类型/范围/长度/禁止模式；随后报告缺失的第 1/2/3 级必需元素）。
--tier <1|2|3>：强制使用指定级别的格式（覆盖自动检测）。
--interactive 或 -i：最终输出前，询问用户确认类型、范围和摘要。

输出格式

[NOTE] Suggested Commit Messages (based on X files changed)

PRIMARY:
feat(api): add user authentication endpoints

ALTERNATIVES:
1. feat(auth): implement JWT token validation
2. feat: add user authentication system

ANALYSIS:
- 3 files modified in src/api/
- New functions: authenticateUser, generateToken
- Primary change: new feature (authentication)
- Scope detected: api/auth

Conventional Commits 快速参考

类型指南：

feat：面向用户的功能或 API 新增
fix：修正错误行为
refactor：改进代码但不改变行为
docs：README、注释、文档文件
style：仅格式调整（prettier、eslint --fix）
test：测试文件或测试工具
chore：构建脚本、软件包更新、配置
perf：可衡量的性能改进
ci：GitHub Actions、CircleCI、构建流水线

范围指南：

使用小写
明确具体，但不要过于狭窄
与项目的模块结构保持一致
如果更改涉及多个互不相关的区域，则省略范围

描述指南：

以小写动词开头
末尾不加句号
明确具体且简洁
对于 feat 和 fix，重点说明对用户的影响

边缘情况

多个互不相关的更改：

建议拆分为多个独立提交
如果必须合并，则使用更宽泛的范围或省略范围

破坏性更改：

在类型/范围后添加感叹号（示例：feat(api)!: change auth flow）
在正文中加入 BREAKING CHANGE（由用户处理）

WIP 或实验性更改：

使用 chore(wip): description 或 feat(experimental): description

没有有意义的更改：

检测并警告："未检测到已暂存的更改"
建议使用 git add 命令

集成点

Pre-commit 钩子：在提交前触发（如果已安装/配置） 斜杠命令：通过 /commit-msg 手动调用 直接调用技能：通过其他技能或工具调用

最佳实践

分析上下文：查看文件路径、函数名称、导入语句
优先考虑清晰度：选择直观的描述，而不是巧妙的说法
遵循约定：如果检测到项目已有的提交模式，则遵循该模式
避免臆测：只描述差异中实际包含的内容
简洁明了：首行以 50 个字符为佳，最多 72 个字符
暂存指定文件：使用 git add <file1> <file2>，而不是 git add -A 或 git add .，以避免包含无关更改或敏感文件
在沙箱 Shell 中避免使用 heredoc：沙箱环境可能会阻止为 here-document 创建临时文件。使用 git commit -m "$(cat <<'EOF'\nmessage\nEOF\n)"，或直接传入 -m "message"
提交前进行类型检查：在提交前对已暂存的代码范围运行 tsc --noEmit，以便尽早发现类型错误，避免因 pre-commit 钩子而反复重试

分析示例

场景 1：新建 React 组件

Files: src/components/UserProfile.tsx, src/components/UserProfile.test.tsx
Changes: +120 lines, component definition, props interface, tests
Message: feat(components): add UserProfile component

场景 2：修复 API 中的错误

Files: src/api/auth.ts
Changes: -5 +8 lines, fix token expiration check
Message: fix(auth): correct token expiration validation

场景 3：更新文档

Files: README.md, docs/api.md
Changes: +45 lines documentation
Message: docs: update API documentation and README

场景 4：更新依赖项

Files: package.json, package-lock.json
Changes: version bumps for eslint, typescript
Message: chore(deps): update eslint and typescript

分析模式：智能类型检测

此技能使用模式匹配，根据差异智能检测提交类型：

feat 检测

创建新文件（尤其是在 src/、components/、api/ 中）
导出新函数/类（export function、export class）
新增 API 路由（app.get、router.post 等）
新增资源/技能（在 .claude/、custom-gpt/ 等目录中）
阈值：通常新增 20 行以上表示新增功能

fix 检测

测试文件更改（通常表示复现错误）
新增条件判断（修复验证逻辑）
新增错误处理（try、catch、throw）
输入验证（validate、sanitize、check）
提交消息提示：诸如 "bug"、"issue"、"error"、"crash" 等词语

refactor 检测

增删平衡的更改（新增和删除行数相近）
函数重命名/移动（逻辑相同，位置不同）
没有新增功能或修复
测试覆盖率不变
关键词："extract"、"move"、"rename"、"reorganize"

docs 检测

文件模式：.md、.txt、README、CHANGELOG、/docs/
纯文档更改（没有代码修改）
代码与文档混合更改：优先使用代码类型，并在描述中注明文档更改

test 检测

文件模式：test.js、spec.ts、__tests__/、/tests/
测试框架模式：describe、it、test、expect、assert

style 类型检测

CSS/样式文件：.css、.scss、.sass、.less
格式化工具配置：prettier、eslint
仅涉及空白字符的更改
关键词："formatting"、"indent"、"whitespace"

chore 类型检测

依赖文件：package.json、requirements.txt、Gemfile
锁定文件：package-lock.json、yarn.lock
配置文件：.gitignore、.env
关键词："dependency"、"deps"、"upgrade"、"bump"

配置

从 config.yaml 加载项目专属配置：

作用域映射：将目录模式映射到作用域名称（例如，frameworks/claude-code-kit/** → claude-kit）
级别规则：定义哪些提交类型需要哪种级别格式
禁止模式：阻止使用通用消息或助手/工具署名的提交
分析模式：为你的代码库自定义类型检测逻辑
验证模式：strict（阻止）、warning（警告）或 disabled（禁用）

禁止模式（验证）

此技能会自动阻止包含以下模式的提交：

通用/模糊消息

[FAIL] "Update files" → [OK] "docs: update API reference"
[FAIL] "Fix stuff" → [OK] "fix(auth): correct token validation"
[FAIL] "Change code" → [OK] "refactor(utils): simplify date formatting"

助手/工具署名（遵循仓库政策）

[FAIL] "Generated with Claude Code"
[FAIL] "Co-Authored-By: Claude [email protected]"
[FAIL] 提交消息中的任何助手/工具署名

正在进行的工作标记

[WARNING] "WIP: feature"（警告——合并前应压缩提交）
[WARNING] "temp: quick fix"（警告——应压缩提交）

缺少类型

[FAIL] 未添加类型前缀（feat、fix、docs 等）的提交

错误处理

没有暂存的更改：运行 git status，并指导用户使用 git add 添加文件
仅包含二进制文件：提示提交消息应说明文件类型
合并冲突：检测冲突并建议使用 chore: resolve merge conflicts
Git 不可用：妥善处理失败，并显示有帮助的错误消息
检测到禁止模式：显示错误和示例，并阻止提交（严格模式）
缺少必需元素：根据级别要求列出缺少的内容
超出长度限制：显示字符数并建议缩短

与仓库的集成

此技能遵循 AI-Agents 仓库规范：

CLAUDE.md 参考：提交前必须使用此技能
config.yaml：项目专属作用域映射和规则
提交前钩子：在 Git 提交前自动激活
CONTRIBUTING.md：贡献者的提交指南

提交消息模板

assets/template-commit-message.md — 可复制粘贴的模板，以及正反示例。

使用此模板规范 type(scope): summary 格式的消息，并使提交历史便于自动化处理。

安全敏感型提交

assets/template-security-commits.md — 处理安全敏感型更改的指南。

主要章节

提交前安全检查清单 — 检测机密信息、禁止模式
安全相关提交类型 — 安全修复、增强、配置
意外提交机密信息 — 立即响应、轮换、清理历史记录
敏感文件模式 — .gitignore 模板、绝不应提交的文件
审计跟踪要求 — 安全提交的 CVE、CVSS、CWE 元数据

应做/避免事项

不良示例：避免

“暂时”提交机密信息
在测试中使用硬编码凭据
在示例文件中存储真实凭据
以为删除的机密信息就是安全的
在机密信息扫描完成前提交
为安全修复使用笼统的提交消息

反模式

反模式	问题	修复方法
“以后再添加机密信息”	意外提交机密信息	从一开始就使用环境变量
测试中包含机密信息	仓库中存在真实凭据	使用模拟对象／测试凭据
强制推送以掩盖问题	历史记录仍可恢复	轮换凭据并记录
含糊的安全提交	缺少审计记录	包含 CVE/CVSS
没有提交前扫描	机密信息被推送到远程仓库	安装 gitleaks 钩子

可选：AI／自动化

注意：AI 建议应保留人的意图。

提交消息建议 — 根据差异分析起草
类型检测 — 基于模式推断提交类型
范围检测 — 根据变更路径自动检测

有限承诺

AI 生成的消息需要人工审核和修改
自动类型检测可能会遗漏上下文
安全提交始终需要人工判断

资源

资源	用途
references/conventional-commits-guide.md	Conventional Commits 规范和工具
references/commit-message-antipatterns.md	常见不良模式、检测和代码检查
references/monorepo-commit-conventions.md	多包仓库的范围策略
references/changelog-generation-guide.md	变更日志工具配置、CI 集成
data/sources.json	精选外部来源

版本：2.1.1 最后更新：2026-01-26 仓库：AI-Agents（文档仓库） Conventional Commits 规范：https://www.conventionalcommits.org/

支持 Markdown

登录后评论

基本信息

作者: vasilyu1983
仓库: vasilyu1983/ai-agents-public
分类: 开发
安装次数: 84

报告问题