Git Batch Commit

智能工具根据已暂存文件类型自动分类并生成多条逻辑清晰的 Git 提交，保持标准化和聚焦的提交历史。

Security Scan

The skill mostly does what it claims (group staged files and create focused commits), but there are surprising implementation details — notably a hardcoded absolute path and a documented 'ClawHub sync' behaviour that can modify repo metadata — that warrant review before use.

Purpose & Capability

Name/description match the delivered artifacts: scripts analyze staged files, group by type, generate conventional commit messages, and create commits. Requesting no credentials and no external binaries is proportional. However, the SKILL.md also documents a post-commit 'ClawHub sync' flow that can add entries to a sync whitelist and run publish steps — this goes beyond simple commit-splitting and increases potential impact on repository metadata and release workflows.

Instruction Scope

Runtime instructions and bundled scripts operate on the local git repository (reading diffs, creating commits) which is expected. Concerns: (1) SKILL.md specifies a silent check that will 'do nothing' if skills/clawhub-sync/ is absent — silent behavior can hide branching logic; (2) SKILL.md describes modifying sync-allowlist.yaml and executing prepare-publish/publish when the user confirms — these are repository-modifying actions outside pure commit creation and should be visible and audited; (3) the code contains a hardcoded absolute cwd in is_new_skill_being_added (subprocess.run uses a path under /Users/maoking/...), which is non-portable and unexpected for a general-purpose tool and could cause accidental information probing or misbehavior on hosts where that path exists.

Install Mechanism

No install spec (instruction-only plus bundled scripts). This is low risk in terms of automatic installation since nothing is being downloaded or extracted. The tool executes local git and Python scripts — expected for this purpose.

Credentials

The skill requests no environment variables or credentials, which is appropriate. It does rely on git being available and on local filesystem access to repository files (SKILL.md, skills/*), which is necessary for the stated function.

Persistence & Privilege

The skill is not marked always:true and is user-invocable — normal. However, SKILL.md documents optional post-commit actions that will edit repository files (e.g., adding to sync-allowlist.yaml) and invoke publish workflows if the user consents; that increases the scope of changes the tool may make to the repo and to any downstream publish process, so users should audit those steps and confirm consent before enabling them.

Scan Findings in Context

[ABSOLUTE_CWD_HARDCODE] unexpected: generate_commit_message.py:is_new_skill_being_added calls git cat-file with cwd set to '/Users/maoking/Library/Application Support/maoscripts/skills/legal-skills'. A git helper should operate relative to the current repo, not a hardcoded user path. This is non-portable and may cause unexpected probing or errors on different hosts.

[GIT_SUBPROCESS_EXEC] expected: Scripts use subprocess.run to invoke git (diff, diff --cached, commit, reset, cat-file). This is expected for a tool that analyzes staged changes and creates commits.

[DOCUMENTED_AUTOMATED_SYNC] unexpected: SKILL.md documents automatically adding entries to sync-allowlist.yaml and running prepare-publish/publish when the user confirms a ClawHub sync. The provided scripts do not appear to implement that full flow; the documentation implies repository metadata edits and automated publishing which have broader side effects and require careful user consent and audit.

What to consider before installing

This skill appears to implement the batch-commit functionality it advertises, but there are a few red flags to check before installing or running it on important repositories: 1) Inspect and remove/fix the hardcoded absolute path in generate_commit_message.py (is_new_skill_being_added) — it should operate relative to the repository, not a fixed user directory. 2) Run the tool first with --dry-run to see grouping output and verify it won't modify files you didn't expect. 3) Do not use --yes (automatic confirmation) until you trust the behavior; confirm interactively so you can review each commit. 4) Review SKILL.md's 'ClawHub sync' section: if you have a skills/clawhub-sync/ directory, understand exactly what changes the tool will make (it may add lines to whitelist files and trigger publish scripts). If you do not want any repo metadata edits or publishing, remove or disable that step. 5) If you plan to run this in CI or automated contexts, test it first in a disposable clone or container. If you're not comfortable auditing Python, ask a colleague to review the two functions that call external commands and any code path that can write to repository files.

Git 批量提交工具

概述

将混合的修改自动拆分为多个聚焦的、逻辑清晰的提交。而不是创建一个包含"更新各种文件"的大提交，而是创建多个清晰的提交，如"docs: 更新 README"、"chore: 更新依赖"、"license: 更新 license 文件"。

使用场景

• 用户暂存的文件来自多个类别（文档 + 代码 + 配置）
• 用户希望保持清晰、标准化的提交历史
• 用户提到"批量提交"、"拆分提交"或"整理提交"
• 用户修改了许多文件，希望按逻辑分组

快速开始

方式一：使用交互式脚本

# 首先暂存你的文件
git add file1.py file2.md package.json

# 运行交互式批量提交工具（需要确认）
python3 skills/git-batch-commit/scripts/interactive_commit.py

# 或使用 --yes 参数自动确认（适用于非交互式环境）
python3 skills/git-batch-commit/scripts/interactive_commit.py --yes

# 使用 --dry-run 仅查看分组，不实际提交
python3 skills/git-batch-commit/scripts/interactive_commit.py --dry-run

脚本将：

1. 分析已暂存的文件
2. 按类别分组
3. 显示提议的提交和提交信息
4. 请求确认（使用 --yes 可跳过）
5. 创建提交

命令行参数：

• --yes, -y：跳过交互式确认，自动创建提交（适用于 CI/CD 或 AI 助手等非交互式环境）
• --dry-run：仅显示分组建议，不实际创建提交

方式二：手动分类

# 查看变更如何被分类
python3 skills/git-batch-commit/scripts/categorize_changes.py

# 或以 JSON 格式输出
python3 skills/git-batch-commit/scripts/categorize_changes.py --json

提交分类

类型	描述	示例文件
docs	文档变更	*.md、README*、CHANGELOG*、docs/
feat	新功能	添加了新内容的源文件
fix	Bug 修复	包含修复关键字的源文件
refactor	代码重构	删除内容多于添加的源文件
style	代码风格	格式化或小改动的源文件
chore	依赖和工具	package.json、Makefile、.github/
license	License 更新	LICENSE、LICENSE.txt
config	配置文件	*.env.*、*.yaml、config/
test	测试变更	test_*.py、*_test.go、test/

⚠️ 技能核心文件的特殊处理

重要规则：SKILL.md 虽然是 Markdown 格式，但它是技能的核心功能文件，不应归类为 docs 类型。

文件类型	正确分类	理由
SKILL.md	feat/style/fix	技能核心文件，修改它相当于修改功能/代码
AGENTS.md	docs	项目协作规范，属于文档
DECISIONS.md	docs	决策记录，属于文档
CHANGELOG.md	docs	变更日志，属于文档
TASKS.md	docs	任务列表，属于文档

判断依据：

• 如果修改的是定义行为/功能的文件（如 SKILL.md、.py、.ts），视为代码变更
• 如果修改的是记录/说明性质的文件（如 README.md、CHANGELOG.md），视为文档变更

提交信息格式

所有提交遵循格式：<类型>: <描述>

使用英文前缀加中文内容，确保 GitHub 能识别并显示彩色标签。

单一项目仓库

对于只包含一个项目的仓库：

docs: 更新 README 文档
feat: 添加用户认证功能
fix: 修复解析器内存泄漏
chore: 更新依赖
license: 更新 license 文件
refactor: 简化数据层
config: 更新环境配置
test: 添加解析器单元测试

Multi-Module/Multi-Skill 仓库

对于包含多个独立模块或技能的仓库（如 skills 仓库），描述中应包含模块名称以确保聚焦：

docs: course-generator 更新 CHANGELOG
fix: skill-manager 修复符号链接创建位置问题
docs: legal-proposal-generator 优化模板文档
fix: svg-article-illustrator 修复 PNG 导出问题

重要规则：

• 如果一次修改涉及多个模块，必须按模块分别提交
• 每个提交只包含一个模块的变更
• 描述中的模块名称使用原始英文名称，不要翻译

工作流程

1. 暂存文件 - 使用 git add 正常暂存
2. 运行交互式脚本 - 查看分类结果
3. 审核 - 检查提议的提交分组
4. 确认 - 创建提交或取消以调整
5. ClawHub 同步检查 - 检查本次提交是否需要同步到 ClawHub（详见下方「提交后检查：ClawHub 同步」章节）
   • 前置条件：仅在项目目录下存在 skills/clawhub-sync/ 时才执行此步骤
   • 如果 skills/clawhub-sync/ 不存在，直接跳到第6步，不提示、不输出任何信息
   • 存在时：按触发条件检查，如有需要同步的 skill 则提示用户
6. 完成 - 获得清晰历史的聚焦提交

实现说明

分类使用两遍扫描方法：

1. 文件模式匹配 - 文件按路径和扩展名模式分类
2. Diff 内容分析 - 对于源代码，分析实际的 git diff 以区分功能、修复、重构和风格变更

检测规则：

• Fix: diff 中包含 "fix"、"bug"、"error" 等关键字
• Feat: diff 中包含 "add"、"new"、"implement" 等关键字且添加多于删除
• Refactor: 删除多于添加
• Style: 添加和删除平衡（源文件默认）

资源文件

scripts/

• categorize_changes.py - 分析 git diff 并按类别分组文件
• generate_commit_message.py - 生成约定式提交信息
• interactive_commit.py - 批量提交的主交互式工具

references/

• commit-types.md - 详细的类别定义和检测逻辑
• conventional-commits.md - 提交信息规范

使用示例

$ git add *.py *.md requirements.txt
$ python3 skills/git-batch-commit/scripts/interactive_commit.py

Git 批量提交工具
============================================================
发现 5 个已暂存文件

============================================================
提议的提交分组
============================================================

[分组 1] chore: 更新 Python 依赖
类别: deps
文件 (1):
  - requirements.txt

[分组 2] docs: 更新 README 文档
类别: docs
文件 (1):
  - README.md

[分组 3] feat: 添加新功能
类别: feat
文件 (3):
  - src/parser.py
  - src/utils.py
  - tests/test_parser.py

============================================================

选项:
  y - 是，创建这些提交
  n - 否，取消
  e - 编辑分组（手动模式）

是否继续创建这些提交？ [y/n/e]: y

正在创建提交...

  → chore: 更新 Python 依赖
    ✓ 已提交 1 个文件

  → docs: 更新 README 文档
    ✓ 已提交 1 个文件

  → feat: 添加新功能
    ✓ 已提交 3 个文件

============================================================
批量提交完成：3/3 个提交已创建
============================================================

工作流第5步参考：ClawHub 同步检查

本节是工作流第5步的详细参考。核心规则：仅当项目目录下存在 skills/clawhub-sync/ 时才执行——不存在则静默跳过，不输出任何提示。

完成 Git 提交后，执行以下检查。

触发条件

完成提交后，依次执行以下三类检测。任一命中即提示用户是否同步。

检测 A：已有技能版本升级

全部满足时触发：

1. 本地存在 clawhub-sync 技能

   • 检查 skills/clawhub-sync/ 目录是否存在
   • 不存在则静默跳过，不提示用户

2. 提交涉及 skills 目录

   • 提交的文件中包含 skills/<skill-name>/ 下的文件

3. 版本号有更新

   • 读取 skills/<skill-name>/SKILL.md 的 frontmatter 中的 version 字段
   • 比较 skills/clawhub-sync/config/sync-records.yaml 中记录的版本
   • 如果新版本 > 已记录版本（或记录中无版本），则需要同步

4. 在白名单中

   • 检查 skills/clawhub-sync/config/sync-allowlist.yaml
   • skill 必须在白名单中（未被 # 注释）

检测 B：新增 MIT 技能首次同步

当提交新增了 skills/<skill-name>/ 目录时触发：

1. 识别新增技能：检查提交中是否有 skills/<skill-name>/SKILL.md 为新文件（untracked → committed）

2. 许可证为 MIT：读取新技能 SKILL.md frontmatter 中的 license 字段，判断是否为 MIT

3. 未在白名单中：sync-allowlist.yaml 中无此 skill 的条目（无论是否被注释）

4. 未在同步记录中：sync-records.yaml 中无此 skill 的条目

满足全部条件时，向用户提示：

🆕 发现新增 MIT 技能：<skill-name>
该技能尚未加入 ClawHub 同步白名单。是否将其加入白名单并同步到 ClawHub？

选项：
  y - 加入白名单并同步
  n - 跳过，暂不发布
  s - 加入白名单但暂不同步

用户选择 y 时：

• 在 sync-allowlist.yaml 中添加该 skill（添加到对应分类区域）
• 执行 prepare-publish → publish → 更新 sync-records 流程
• 注意：发布前检查临时目录，确保不含 .env、密钥等敏感文件

用户选择 s 时：

• 仅在 sync-allowlist.yaml 中添加该 skill（被注释），下次版本更新时再同步

检测 C：白名单新增但未同步

当白名单中有未被注释的 skill，但 sync-records.yaml 中没有对应记录时：

1. 遍历 sync-allowlist.yaml 中未被注释的 skill
2. 检查 sync-records.yaml 中是否有该 skill 的记录
3. 如果白名单有但记录中没有，且 SKILL.md 存在，提示用户执行首次同步

执行步骤

对于每个需要同步的 skill，按照 clawhub-sync 的"单个 Skill 同步工作流"执行：

步骤 1：准备发布目录

bash skills/clawhub-sync/scripts/prepare-publish.sh skills/<skill-name>

步骤 2：执行发布（使用 publish 命令）

clawhub publish /tmp/clawhub-publish-<skill-name> \
  --slug <skill-name> \
  --name "<Display Name>" \
  --version "<新版本号>" \
  --changelog "<变更说明>"

⚠️ 必须指定 --slug 和 --name

• 临时目录名可能包含前缀，使用 --slug 确保正确的 skill 标识符
• 使用 --name 确保 ClawHub 上显示正确的名称

为什么用 publish 而不是 sync？

• clawhub sync 会扫描所有目录的 skills，可能遇到 slug 冲突
• clawhub publish <path> 只发布指定路径的单个 skill，更精确

步骤 3：更新同步记录

更新 skills/clawhub-sync/config/sync-records.yaml：

• 更新 version 为新版本号
• 更新 last_sync 为当前时间
• 更新 git_hash 为当前 commit hash
• 更新 status 为 synced
• 添加 url 和 publish_id（从命令输出获取）

失败处理

• 同步失败时仅显示警告信息
• 不影响 Git 提交结果
• 继续处理其他 skills

版本比较逻辑

new_version = SKILL.md frontmatter 中的 version（如 "1.2.0"）
recorded_version = sync-records.yaml 中记录的版本（如 "1.1.0"）

if new_version > recorded_version:
    执行同步

版本号按语义化版本规则比较（major.minor.patch）。

示例场景

场景	版本变化	白名单	同步记录	结果
版本升级（检测A）	"1.0.0" → "1.1.0"	在白名单	有记录	✅ 执行同步
无版本变化（检测A）	"1.1.0" → "1.1.0"	在白名单	有记录	❌ 跳过
不在白名单（检测A）	任意	被注释	-	❌ 跳过
白名单内首次发布（检测A/C）	"1.0.0"	在白名单	无记录	✅ 执行同步
新增 MIT 技能（检测B）	"0.1.0"	无条目	无记录	✅ 提示用户选择
新增 CC 技能（检测B）	"0.1.0"	无条目	无记录	❌ 非 MIT 跳过
clawhub-sync 不存在	-	-	-	❌ 静默跳过整个工作流