메뉴
当用户提到'提交'、'commit'、'原子提交'、'代码提交'、'提交变更'、'git commit'、'保存更改'时，必须使用此技能。提供Git原子化提交规范执行能力：检查变更（三查暂存法）→预提交验证→构建提交信息→执行提交→验证结果。遵循Conventional Commits规范，确保单次提交单一职责。不要直接git commit——本Skill封装了预检查、三查暂存验证、提交信息格式和验证流程。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
当用户提到'CI检查'、'提交前检查'、'综合检查'、'ci-check'、'流水线检查'、'提交门禁'、'全量检查'、'跑一下CI'、'pre-commit'、'预检'、'检查所有'时，必须使用此技能。提供项目CI/CD综合检查能力，按标准流水线顺序执行10项核心检查：仓库合规→链接检查→Spec一致性→模式成熟度→文档生成→重复代码检测→阶段守卫日志→SG仪表盘→文件放置校验→.temp生命周期检查。提交前必跑，确保代码符合项目规范。不要手动逐个执行检查脚本——本Skill已按正确顺序编排，并处理了跨平台兼容（Windows用.ps1，Linux/Mac用.sh）。
当用户提到'链接检查'、'检查链接'、'断链'、'链接修复'、'fix links'、'check links'、'验证链接'、'死链'、'链接有效性'、'提交前检查'时，必须使用此技能。提供Markdown链接有效性检查与自动修复能力：本地文件引用验证、外部URL可达性检测、file:///绝对路径转相对路径、相对路径层级自动校正。不要手动查找断链——本Skill封装了缓存机制、并发检测、自动修复和dry-run预览，是提交前质量门禁的核心工具。
当用户提到'原子化收尾'、'finalize atomization'、'文档拆分完成'、'文件移动后处理'、'断链修复导航更新'、'一键收尾'、'重构完成后整理'时，必须使用此技能。原子化/文件移动/目录重构后的一键收尾工具：自动断链修复→导航表更新→Spec看板刷新→验证摘要。不要手动逐个执行后处理步骤——本Skill封装了正确的执行顺序和dry-run预览机制，是文档原子化工作流的标准最后一步。
当用户提到'萃取'、'extraction'、'模式沉淀'、'萃取模式'、'模式入库'、'沉淀为模式'、'可复用模式'、'更新模式库'、'生成模式文档'时，必须使用此技能。提供标准化的模式萃取流程：案例收集→本质抽象→结构化模板→反模式提炼→迁移验证→入库。不要手动组织萃取流程——本Skill封装了六步标准萃取法、反模式对等原则和可迁移性验证。替代旧的pattern-extraction-cmd（v1.0.0）。
当用户提到'知识图谱'、'knowledge graph'、'概念关系可视化'、'交互式知识图谱'、'节点关系网络'、'生成知识图谱'、'可视化知识库'、'概念网络'、'knowledge graph config'时，必须使用此技能。从结构化Markdown文档集（术语表/文档索引/时间线等）自动提取节点和关系，生成交互式vis-network HTML知识图谱。支持TOML声明式配置和Python API两种方式，内置节点去重、孤立节点检测、类型筛选、可信度分级显示。不要手动拼接vis-network代码——本Skill封装了表格解析、关系构建、HTML模板渲染和自包含输出，确保产出质量可预测。
当用户提到'mermaid'、'流程图'、'时序图'、'状态图'、'画个图'、'图表'、'架构图'、'思维导图'、'ER图'、'类图'、'甘特图'、'饼图'、'UML图'、'可视化流程'、'画流程图'、'mermaid图'、'可视化'、'流程可视化'时，必须使用此技能。提供标准化的Mermaid图表创建、检查、修复流程，引导完成从设计→编码→检查→修复→验证→交付的完整闭环。不要手写Mermaid代码绕过本Skill——本Skill封装了安全编码六规则、模板选择、自动检查修复流程，确保图表质量可预测。
| name | git-commit-helper |
| version | 1.1.0 |
| description | 当用户提到'提交'、'commit'、'原子提交'、'代码提交'、'提交变更'、'git commit'、'保存更改'时，必须使用此技能。提供Git原子化提交规范执行能力：检查变更（三查暂存法）→预提交验证→构建提交信息→执行提交→验证结果。遵循Conventional Commits规范，确保单次提交单一职责。不要直接git commit——本Skill封装了预检查、三查暂存验证、提交信息格式和验证流程。 |
| argument-hint | [--dry-run] [--type <type>] [--scope <scope>] |
| user-invocable | true |
| paths | [".agents/skills/git-commit-helper/scripts/validate_commit.py",".agents/skills/git-commit-helper/references/conventional-commits.md"] |
| title | Git 原子提交助手 Skill |
| x-toml-ref | ../../../.meta/toml/.agents/skills/git-commit-helper/SKILL.toml |
本Skill遵循渐进式披露三层架构：
- L0：本文件（SKILL.md）——触发条件+核心流程+安全清单，<200行
- L1：references/conventional-commits.md——Conventional Commits规范详解（按需加载）
- L2：scripts/validate_commit.py——提交信息验证脚本（可执行工具）
git-commit-helper
按照 Conventional Commits 规范生成原子化 Git 提交，确保每次提交遵循"单一职责"原则：
| 特性 | 说明 |
|---|---|
| 三查暂存法 | 查工作区状态 → 查暂存区差异 → 查最近提交记录，确保提交范围正确 |
| 类型自动推断 | 根据变更文件自动推断 commit type（feat/fix/docs/refactor/test/chore等） |
| 格式校验 | 验证提交信息符合 <type>(<scope>): <subject> 格式 |
| 中文描述 | subject 使用中文清晰描述变更目的（为什么改，不是改了什么） |
| 提交前预览 | 默认展示完整提交信息供用户确认后再执行 |
| 操作性质 | ✏️ 写操作，但所有破坏性操作前需用户确认 |
为什么要用原子提交而不是直接 git commit？ 直接 commit 容易犯三个错误：一是把不相关的改动混在一起提交（一个commit既有bugfix又有新功能），导致回滚时牵连无辜；二是提交信息模糊（"更新代码""fix bug"），三个月后看log完全不知道改了什么；三是忘记检查工作区状态，误把调试代码/临时文件提交上去。本Skill通过"三查暂存法"和格式校验，确保每个commit都是可回溯、可回滚、语义清晰的原子单元。
严格按以下5步执行，不要跳过任何步骤：
步骤1: 三查暂存（必做，只读检查）
├─ 1a. git status --short → 查看工作区和暂存区状态
├─ 1b. git diff --staged → 查看已暂存的变更内容
└─ 1c. git log --oneline -5 → 查看最近5条提交记录（了解提交风格）
步骤2: 变更分析
├─ 识别变更文件列表
├─ 根据文件路径推断 commit type（见§5类型映射表）
├─ 根据主要变更模块推断 scope
└─ 提炼 subject：用一句话描述"为什么改"（中文，祈使句，不加句号）
步骤3: 构建提交信息
├─ 格式：<type>(<scope>): <subject>
├─ 如有破坏性变更，追加 ! 和 BREAKING CHANGE 脚注
├─ 运行验证脚本检查格式：python scripts/validate_commit.py "<message>"
└─ 修复验证发现的问题
步骤4: 提交预览与确认
├─ 向用户展示：变更文件列表 + 提交信息 + 变更统计
├─ 等待用户明确确认（"提交"/"确认"/"yes"）
└─ 用户要求修改则回到步骤2调整
步骤5: 执行提交并验证
├─ git add <相关文件>（精确add，不要git add -A）
├─ git commit -m "<message>"（使用HEREDOC传递含特殊字符的信息）
└─ git log --oneline -1 → 验证提交结果
| Type | 适用场景 | 文件模式示例 |
|---|---|---|
| feat | 新功能、新特性 | *.ts新增组件、apps/新增页面 |
| fix | Bug修复 | 修复逻辑错误、异常处理 |
| docs | 文档更新 | *.md、注释、README |
| style | 代码格式（不影响逻辑） | 空格、格式化、分号 |
| refactor | 重构（非feat非fix） | 重命名、提取函数、结构调整 |
| perf | 性能优化 | 缓存、懒加载、算法优化 |
| test | 测试相关 | *test*、*spec*、新增测试用例 |
| chore | 构建/工具/依赖 | package.json、CI配置、脚本 |
| ci | CI/CD变更 | .github/workflows/、流水线配置 |
| revert | 回滚提交 | git revert 操作 |
auth、utils、docs）core、cli、web）<type>: <subject>| 规则 | ✅ 好的示例 | ❌ 坏的示例 |
|---|---|---|
| 使用中文，祈使句 | "修复登录态过期跳转问题" | "fixed login bug"、"修复了一个问题" |
| 描述"为什么改"而非"改了什么" | "为列表页添加分页支持" | "修改了list.tsx文件" |
| 不加句号结尾 | "重构用户服务依赖注入" | "重构用户服务。" |
| 长度≤50字 | "优化首屏加载时间减少300ms" | "做了一些优化和调整还有bug修复" |
| 一个commit只说一件事 | "修复日期选择器跨年选择异常" | "修复日期选择器bug并优化表格样式" |
为什么subject要写"为什么改"？ 因为
git diff已经告诉你"改了什么"（具体代码变更），commit message的价值在于解释变更背后的意图。三个月后你看到一行被修改的代码，通过diff能看到改了什么，但你需要commit message告诉你当时为什么做这个改变。
git add <file> 精确添加，未使用 git add -A 或 git add .（避免误提交临时文件）[prevent: test-case]、[prevent: check-script]、[prevent: rule-update]、[prevent: trivial-exempt]）或引用跟踪Issuegit log -1 确认提交成功| 问题 | 原因 | 处理方式 |
|---|---|---|
| 提交信息格式验证失败 | type/scope/subject不符合规范 | 根据验证脚本提示修正，参考§5类型表和§6编写规范 |
| 工作区有未暂存变更 | git add 不完整 | 检查 git status，确认是否需要 add 或者 stash |
| 变更范围太大 | 一次改了太多东西 | 建议拆分提交：先提交A功能，再提交B修复 |
| 误提交了敏感文件 | add了不该提交的文件 | git reset HEAD <file> 取消暂存，检查 .gitignore |
<<'EOF' HEREDOC语法，会报"Missing file specification after redirection operator"错误。PowerShell环境下直接使用双引号传递提交信息即可：git commit -m "docs(spec): 基于第一性原理提炼通用PRD模板"；如使用Git Bash/WSL则可使用HEREDOC语法git commit -m "$(cat <<'EOF'<message>EOF)"git add .：这个命令会把所有修改（包括调试打印、临时文件、.env）都加入暂存，必须精确指定要提交的文件git commit --amend 只用于修改最近一次且未push的提交，不要习惯性amend，已push的commit禁止amend（会破坏其他人的历史）--no-verify，hook报错说明代码有问题，应该修复问题而非跳过检查# 1. 三查
git status --short
git diff --staged
git log --oneline -5
# 2. 精确暂存
git add <file1> <file2>
# 3. 验证提交信息格式
python .agents/skills/git-commit-helper/scripts/validate_commit.py "feat(auth): 添加JWT令牌刷新机制"
# 4. 提交（使用HEREDOC避免编码问题）
git commit -m "$(cat <<'EOF'
feat(auth): 添加JWT令牌刷新机制
EOF
)"
# 5. 验证
git log --oneline -1
# 验证提交信息格式
python .agents/skills/git-commit-helper/scripts/validate_commit.py "fix(login): 修复登录态过期跳转问题"
# 干跑模式（只分析当前变更，不提交）
python .agents/skills/git-commit-helper/scripts/validate_commit.py --dry-run