⚡

Git提交规范技能Skill git-commit

这个技能提供了一个全面的Git提交工作流程，使用Conventional Commits格式，包括安全协议、属性要求和完整的工作流程指导。适用于创建提交、草拟消息、处理钩子、创建拉取请求等场景，确保版本控制的最佳实践和安全性。关键词：Git提交，版本控制，Conventional Commits，安全协议，工作流程，提交消息，预提交钩子，拉取请求

DevOps 0 次安装 0 次浏览 更新于 3/11/2026

name: git-commit description: 使用Conventional Commits格式的全面Git提交工作流程，包含安全协议。遵循最佳实践创建、验证和执行提交。在创建提交、草拟提交消息、处理预提交钩子、创建拉取请求，或不确定提交安全性、时机或消息格式时使用。关键 - 在任何提交操作前始终调用 - 包含NEVER规则、属性要求和正确的消息格式化。 allowed-tools: Read, Bash, Glob, Grep

Git提交

实现Conventional Commits规范的全面Git提交协议，包含严格的安全规则、正确的属性和完整的工作流程指导。

目录

概述

此技能提供所有Git提交操作的权威协议，包括：

  • Conventional Commits格式，包含必需的属性页脚
  • 智能暂存决策，处理混合暂存/未暂存场景
  • 安全规则，防止破坏性操作
  • 4步提交工作流程，确保正确执行
  • 预提交钩子处理，用于自动化工具失败
  • 拉取请求创建，包含完整上下文
  • 系统变更验证，在提交前进行

关键：必须在任何提交操作前调用此技能，以确保符合安全协议和消息格式化要求。

何时使用此技能

此技能应在以下情况使用：

  • 创建任何Git提交（常规、初始、合并）
  • 草拟遵循Conventional Commits的提交消息
  • 处理预提交钩子失败或修改
  • 使用gh pr create创建拉取请求
  • 不确定提交时机（何时提交 vs 何时等待）
  • 验证提交安全性（检查机密、绝对路径等）
  • 修正提交（罕见 - 需要安全检查）
  • 验证系统变更文档在提交前

重要：仅当用户明确请求时创建提交。如果不清楚，请先询问。

关键安全规则 (NEVER)

这些规则不可协商，必须遵循：

NEVER规则

  1. NEVER更新git配置 - 配置变更必须是有意且用户批准的
  2. NEVER运行破坏性命令 - 无git push --force、git reset --hard等，除非用户明确请求
  3. NEVER跳过钩子 - 无--no-verify或--no-gpg-sign标志，除非用户明确请求
  4. NEVER强制推送到main/master - 如果用户请求此操作，发出警告
  5. NEVER使用git commit --amend - 仅在以下情况允许：
    • 用户明确请求修正，或
    • 预提交钩子修改了文件（需要安全检查 - 见钩子处理）
  6. NEVER未经用户明确请求提交 - 这非常重要 - 仅在用户要求时提交
  7. NEVER提交机密文件 - 不提交.env、credentials.json等 - 如果用户请求，发出警告
  8. NEVER使用交互式git命令 - 无-i标志（git rebase -i、git add -i）- 在非交互环境中不支持

提交前安全检查

在执行任何提交前：

  • ✅ 检查机密 - 扫描暂存文件中的常见机密模式
  • ✅ 检查绝对路径 - 确保无机器特定路径（如D:\repos\...、/home/user/...）
  • ✅ 验证SYSTEM-CHANGES.md - 如果修改了仓库外任何文件（配置、密钥等），确保已记录
  • ✅ 确认用户意图 - 如果不清楚是否提交，请先询问用户

Conventional Commits格式

所有提交消息必须遵循Conventional Commits规范，并包含必需的Claude Code属性。

基本结构

<类型>[可选范围]: <描述>

[可选正文]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

提交类型

使用这些标准化类型：

  • feat：新功能（与SemVer中的MINOR相关）
  • fix：错误修复（与SemVer中的PATCH相关）
  • docs：仅文档变更
  • style：代码风格变更（格式化、缺少分号，无逻辑变更）
  • refactor：代码重构（既不修复错误也不添加功能）
  • perf：性能改进
  • test：添加或更新测试
  • chore：维护任务（依赖项、工具、配置）
  • ci：CI/CD配置变更
  • build：构建系统或外部依赖项变更

破坏性变更

使用以下任一方式指示破坏性变更：

  1. 感叹号在冒号前：feat!: 更改API响应格式
  2. BREAKING CHANGE页脚：在消息正文中包含BREAKING CHANGE: <描述>

范围（可选）

添加范围以提供关于代码库受影响区域的上下文：

feat(api): 添加用户认证端点
fix(database): 解决连接超时问题
docs(readme): 更新安装说明

消息指南

  • 描述：以小写开头，末尾无句点，最大约50字符
  • 关注为什么，而非什么：解释意图和原因，而不仅仅是变更
  • 简洁：如需，正文中1-2句
  • 使用命令语气：“添加功能"而非"已添加功能"或"添加功能”

完整消息示例

git commit -m "$(cat <<'EOF'
feat(auth): 添加JWT令牌刷新机制

实现自动令牌刷新以改善用户体验
并减少不必要的重新认证。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

提交工作流程 (4步)

为每次提交操作遵循此完整工作流程。

步骤1: 收集信息（并行）

并行运行这些命令以了解当前状态：

# 查看所有暂存和未暂存变更
git status

# 查看确切修改（暂存和未暂存）
git diff
git diff --staged

# 审查最近提交以理解消息风格
git log --oneline -10

为何并行：这些是独立的只读操作 - 彼此无依赖。

步骤2: 确定暂存策略和草拟消息

基于收集的信息，首先确定提交什么，然后草拟消息。

2.1: 分析暂存状态

从git status计算每个类别的文件数：

  • 暂存文件："Changes to be committed"部分中的文件
  • 修改文件："Changes not staged for commit"部分中的文件（已跟踪文件被修改）
  • 未跟踪文件："Untracked files"部分中的文件

2.2: 应用暂存决策逻辑

场景A: 无内容可提交（暂存=0，修改=0，未跟踪=0）
工作树干净 - 无内容可提交。

优雅退出。无需提交。

场景B: 文件已暂存，无修改（暂存>0，修改=0）

直接进行提交。用户已暂存他们想要的内容。

场景C: 无暂存，但存在变更（暂存=0，修改>0 或 未跟踪>0）

使用AskUserQuestion询问用户提交什么：

"我看到{N}个修改文件但无内容暂存。您想提交什么？"

选项：
1. "暂存并提交所有修改文件" → `git add -u`（暂存所有跟踪文件）
2. "让我先暂存特定文件" → 退出，让用户手动暂存，然后重新运行/commit

如果用户选择选项1，则使用所有修改文件进行。 如果用户选择选项2，则退出并告知他们运行git add <文件>然后再次/commit。

场景D: 混合暂存（暂存>0，修改>0）

使用AskUserQuestion询问用户：

"我看到{N}个文件暂存和{M}个文件修改但未暂存。您想提交什么？"

选项：
1. "仅提交暂存文件" → 仅处理暂存文件
2. "暂存并提交所有内容" → `git add -u`然后提交所有

尊重用户选择。

2.3: 草拟提交消息

确认将要提交的内容后：

  1. 审查所有将要提交的变更
  2. 确定提交类型 - feat、fix、docs、refactor、style等
  3. 草拟简洁消息，遵循Conventional Commits格式
  4. 验证无机密 - 检查.env、credentials.json、API密钥、令牌
  5. 验证无绝对路径 - 确保提交内容中无D:\repos\...、/home/user/...
  6. 检查SYSTEM-CHANGES.md - 如果触及任何系统文件，验证已记录

消息草拟检查表：

  • [ ] 正确类型（feat/fix/docs等）
  • [ ] 可选范围（如适用）
  • [ ] 命令语气描述
  • [ ] 正文段落（如需）（解释为什么）
  • [ ] 包含属性页脚
  • [ ] 如适用，破坏性变更标记

步骤3: 执行提交（顺序）

按顺序运行这些命令（存在依赖）：

# 如需要，暂存文件（基于步骤2决策）
# - 如果用户选择"暂存所有"：git add -u
# - 如果文件已暂存：跳过此步
# - 如果用户正在暂存特定文件：他们应在运行/commit前进行

# 使用HEREDOC格式创建提交（必需）
git commit -m "$(cat <<'EOF'
<类型>[范围]: <描述>

[可选正文]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

# 验证提交成功
git status

为何顺序：每个操作依赖于前一个成功完成。

关键：始终使用HEREDOC格式与$(cat <<'EOF' ... EOF)以确保正确格式化并避免shell转义问题。

暂存命令参考：

  • git add -u - 暂存所有跟踪修改文件（不包括新未跟踪文件）
  • git add -A - 暂存所有内容（跟踪 + 未跟踪，修改 + 删除）
  • git add <文件> - 暂存特定文件

步骤4: 处理预提交钩子失败

如果提交因预提交钩子（linter、formatter等）失败：

如果钩子修改了文件，重试一次：

# 检查钩子是否修改了文件
git diff

# 如存在修改，检查是否安全修正
git log -1 --format='%an %ae'  # 检查作者身份（必须是您）
git status                      # 检查未推送（必须显示"ahead of"）

# 如两项检查均通过，修正提交：
git add .
git commit --amend --no-edit

# 如任一项检查失败，创建新提交：
git add .
git commit -m "$(cat <<'EOF'
chore: 应用自动化linting修复

预提交钩子应用了自动格式化变更。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

修正安全协议：

  • ✅ 先检查作者身份：git log -1 --format='%an %ae' - 仅修正您的提交
  • ✅ 检查未推送：git status必须显示"Your branch is ahead"（未推送到远程）
  • ✅ 仅如两项均通过：则修正安全
  • ❌ 如任一项失败：创建新提交 - 永不修正他人的提交或已推送提交

何时跳过重试：

  • 钩子失败并有错误（不仅警告）
  • 钩子未修改文件
  • 安全检查失败（非您的提交或已推送）

拉取请求创建

当用户请求创建拉取请求时，遵循此工作流程。

步骤1: 理解分支上下文（并行）

# 查看当前分支状态
git status

# 查看自基分支分歧以来的所有变更
git diff main...HEAD    # 或其他基分支
git log main...HEAD     # 将在PR中的所有提交

# 检查远程跟踪状态
git branch -vv

步骤2: 分析所有提交

审查将包含在PR中的所有提交（不仅仅是最近提交）：

  • 读取所有提交消息
  • 理解变更的完整范围
  • 草拟涵盖整个分支的全面PR摘要

步骤3: 创建拉取请求（顺序）

# 如需要，创建新分支
git checkout -b 功能分支名称

# 推送到远程并跟踪
git push -u origin 功能分支名称

# 使用HEREDOC作为正文创建PR
gh pr create --title "feat: 简短PR标题" --body "$(cat <<'EOF'
## 摘要
- 变更的要点摘要
- 关键功能或修复
- 如适用，破坏性变更

## 测试计划
- [ ] 手动测试步骤
- [ ] 添加/更新的自动化测试
- [ ] 更新的文档

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

返回PR URL当完成时，以便用户查看。

除非用户明确请求PR创建或推送，否则不推送到远程。

何时提交

仅在以下情况创建提交：

  • ✅ 用户明确请求：“创建提交”、“提交这些变更”、"进行提交"等
  • ✅ 用户在询问澄清时确认
  • ✅ 完成任务，其中提交是明确要求的一部分

不提交当：

  • ❌ 用户要求"保存"或"更新"而未提及提交/git
  • ❌ 完成编辑而无明确提交请求
  • ❌ 不确定用户意图
  • ❌ 多个逻辑变更应分开提交

如不清楚，询问：“您希望我用这些变更创建提交吗？”

系统变更文档

关键要求：在提交前，验证所有系统级变更已记录。

需要记录的内容

任何此仓库外所做的变更：

  • 配置文件（~/.gitconfig、~/.ssh/config等）
  • 系统级密钥或凭据（GPG密钥、SSH密钥）
  • 云资源（GitHub Secrets、环境变量）
  • 已安装包或工具
  • 环境变量修改

验证过程

在执行提交前：

  1. 问自己：“我修改了此仓库外的任何文件吗？”
  2. 如是的：检查SYSTEM-CHANGES.md已更新
  3. 如否：进行提交

见仓库文档中的SYSTEM-CHANGES.md格式要求。

示例

对于常见提交场景的具体示例，见references/examples.md：

  • 具有适当范围的简单功能添加
  • 带有详细解释的错误修复
  • 具有正确标记的破坏性变更
  • 仅文档提交
  • 多文件重构示例

所有示例遵循Conventional Commits规范并包含必需的Claude Code属性。

资源

此技能包含全面参考文档：

references/

故障排除

对于常见Git提交问题的解决方案，见references/troubleshooting.md：

  • GPG签名失败
  • 预提交钩子问题
  • 提交类型选择指导
  • 混合暂存状态处理
  • 修正安全检查失败

所有故障排除解决方案遵循安全协议且不跳过钩子或GPG签名。

最佳实践

  • ✅ 始终使用HEREDOC格式作为提交消息 - 确保正确格式化
  • ✅ 提交前审查变更 - 先运行git diff和git status
  • ✅ 提交逻辑相关的变更在一起 - 不混合无关编辑
  • ✅ 编写描述性提交消息 - 关注为什么，而非仅仅什么
  • ✅ 一致使用范围 - 选择范围名称并在所有提交中坚持使用
  • ✅ 调用git-commit技能 - 在提交前始终使用此技能以确保符合
  • ✅ 验证系统变更已记录 - 提交前检查SYSTEM-CHANGES.md
  • ✅ 遵循安全协议 - 永不跳过钩子或绕过GPG签名
  • ❌ 永不提交机密 - 添加.env、credentials.json到.gitignore
  • ❌ 永不提交绝对路径 - 使用相对路径或占位符
  • ❌ 未经明确请求永不提交 - 仅在用户要求时提交

测试

对于全面测试场景和多模型测试指导，见references/testing.md：

  • 六个详细测试场景覆盖常见用例
  • 多模型测试说明（Sonnet、Haiku、Opus）
  • 每个场景的预期行为和成功标准
  • 技能质量评估标准

当前测试状态：使用Sonnet验证。Haiku和Opus测试待定。

版本历史

  • v1.3.1 (2025-11-25): 审计改进 - 标准化模型引用以使用模型家族（Sonnet、Haiku、Opus）而非特定版本，为examples.md、troubleshooting.md和testing.md添加Last Verified日期以保持一致性
  • v1.3.0 (2025-11-17): 优化SKILL.md以提升令牌效率 - 将示例、故障排除和测试移至单独参考文件；删除空的assets/和scripts/目录；改进渐进披露模式
  • v1.2.0 (2025-11-13): 添加测试场景和多模型测试文档，为描述添加执行动词，从scripts/和assets/目录中删除未使用的模板文件
  • v1.1.0 (2025-11-13): 添加智能暂存决策逻辑 - 处理混合暂存/未暂存场景，当模糊时询问用户意图，优雅检测"无内容可提交"
  • v1.0.0 (2025-11-13): 初始发布 - 全面的git提交技能，包含Conventional Commits规范、安全协议和完整工作流程指导

最后更新

日期: 2025-11-28 模型: claude-opus-4-5-20251101