graph LR
    A["第1层：frontmatter<br/>~100 tokens · 始终常驻"] -->|触发匹配成功| B["第2层：SKILL.md 正文<br/>建议 < 5000 tokens · 触发时加载"]
    B -->|需要细则时| C["第3层：scripts/ references/<br/>无上限 · 按需读取"]
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9

mkdir -p .claude/skills/conv-commit/scripts
mkdir -p .claude/skills/conv-commit/references

---
name: conv-commit
description: Analyzes the staged git diff and produces a Conventional Commits message (feat/fix/docs/refactor/perf/test/build/ci/chore), then commits. Use when the user wants to commit changes, says "提交" / "commit" / "写提交信息" / "整理这次的改动", or asks for a 规范化的 commit message.
---

# Conventional Commits 提交助手

## 工作流

1. 运行 `python3 scripts/analyze_diff.py`，拿到暂存区变更的结构化事实（JSON）。
   - 若 `has_staged` 为 false，先提示用户 `git add` 暂存相关文件，不要自动全量 `git add -A`。
2. 读取 `references/type_mapping.md`，依据事实判定 `type` / `scope` / `breaking` / `description`。
3. 组装提交信息并调用 `scripts/render_commit.sh <type> <scope> <breaking> <description> [body_file]` 完成提交。

## description 写作规则

- 主体 ≤ 50 字符，祈使句，小写开头，句末不加句号。
- 仅当改动确实聚焦于一个模块时才写 scope。
- breaking=true 时给 header 加 `!`，并在 body 中以 `BREAKING CHANGE: <原因>` 说明。

## 自由度

本 Skill 的语义判断（选 type、写描述）交给模型；格式化、行数统计、文件归类交给脚本——后者必须 100% 可复现。

#!/usr/bin/env python3
"""analyze_diff.py — 把暂存区 diff 解析成机器可读的变更事实。
仅做确定性提取，不做 type 判断。输出 JSON 供模型消费。"""
import subprocess, json, os, sys
from collections import defaultdict

def git(*args):
    return subprocess.run(["git", *args], capture_output=True, text=True).stdout

def classify(path):
    """按路径启发式分桶，给模型一个粗粒度的归类信号。"""
    base = os.path.basename(path).lower()
    if (base.startswith("test") or ".test." in base or ".spec." in base
            or "__test__" in path or "/tests/" in path or "/test/" in path):
        return "tests"
    if base in {"package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
                "go.mod", "go.sum", "requirements.txt", "pyproject.toml",
                "cargo.toml", "cargo.lock", "pom.xml", "gemfile", "gemfile.lock"}:
        return "deps"
    if base.endswith((".md", ".rst")) or "/docs/" in path or "/doc/" in path:
        return "docs"
    if base.endswith((".yml", ".yaml")) and ("/.github/" in path or "ci" in path):
        return "ci"
    if base.startswith("dockerfile") or base.endswith((".dockerfile", "makefile")) or base == "cmakelists.txt":
        return "build"
    return "source"

def main():
    name_status = git("diff", "--cached", "--name-status")
    numstat = git("diff", "--cached", "--numstat")

    added = deleted = 0
    for line in numstat.splitlines():
        p = line.split("\t")
        if len(p) == 3 and p[0].lstrip("-").isdigit():
            added += int(p[0]); deleted += int(p[1])

    files, buckets = [], defaultdict(int)
    for line in name_status.splitlines():
        if not line.strip():
            continue
        code, _, path = line.partition("\t")
        status = code[0]  # A=新增 M=修改 D=删除 R=重命名 ...
        files.append({"status": status, "path": path})
        buckets[classify(path)] += 1

    result = {
        "has_staged": len(files) > 0,
        "file_count": len(files),
        "added_lines": added,
        "deleted_lines": deleted,
        "buckets": dict(buckets),   # 例如 {"source": 2, "tests": 1}
        "files": files,
    }
    print(json.dumps(result, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

python3 .claude/skills/conv-commit/scripts/analyze_diff.py

{
  "has_staged": true,
  "file_count": 3,
  "added_lines": 47,
  "deleted_lines": 9,
  "buckets": { "source": 2, "tests": 1 },
  "files": [
    { "status": "M", "path": "src/auth/token.py" },
    { "status": "M", "path": "src/auth/session.py" },
    { "status": "A", "path": "tests/auth/test_token_expire.py" }
  ]
}

#!/usr/bin/env bash
# render_commit.sh — 组装 Conventional Commits 头并提交。不做事语义判断。
set -euo pipefail

type="${1:?usage: render_commit.sh <type> <scope> <breaking> <description> [body_file]}"
scope="${2:-}"
breaking="${3:-false}"
description="${4:?description required}"
body_file="${5:-}"

scope_part=""; [[ -n "$scope" ]] && scope_part="($scope)"
bang=""; [[ "$breaking" == "true" ]] && bang="!"
header="${type}${scope_part}${bang}: ${description}"

if [[ -n "$body_file" && -f "$body_file" ]]; then
  git commit -m "$header" -F "$body_file"
else
  git commit -m "$header"
fi
echo "✓ committed: $header"

chmod +x .claude/skills/conv-commit/scripts/render_commit.sh

# Commit Type 判定规则（基于 @commitlint/config-angular）

## 类型清单
feat 新功能（→ SemVer MINOR）
fix  修 bug（→ SemVer PATCH）
docs  仅文档
style 不影响代码含义（空格/格式）
refactor 既非修 bug 也非加功能
perf  提升性能
test  补/改测试
build 构建系统/外部依赖（webpack/npm/go.mod 等）
ci   CI 配置（.github/workflows、GitLab CI）
chore 杂务（不修 bug 也不加功能的琐事，如改 .gitignore）
revert 回滚某个提交

## 判定优先级（结合 analyze_diff.py 的 buckets）
1. buckets 只含 docs         → docs
2. buckets 只含/主导 tests    → test（除非连源码一起改，则以源码为准）
3. buckets 只含 deps/build/ci → build / ci
4. source 中含全新公开能力
   （新增导出符号、新路由、新页面、新 CLI 命令）→ feat
5. source 改动针对已知缺陷
   （加边界判断、修空指针、纠正逻辑）→ fix
6. 仅结构调整、无行为变化    → refactor
7. 命中性能优化（缓存、算法）→ perf

## Breaking Change 信号（→ 加 !，并在 body 写 BREAKING CHANGE:）
- 删除或重命名公开导出符号
- 函数签名参数变化/移除
- 配置项被移除
- 文件迁移导致 import 路径变化
- 数据库 schema 的不可逆迁移

## scope 写法
- 仅当改动聚焦单一模块时使用，取模块/包名：feat(auth):、fix(parser):
- 跨多模块的大改不要硬凑 scope，留空更诚实

graph TD
    R["conv-commit/"] --> S["SKILL.md<br/>frontmatter + 工作流"]
    R --> D["scripts/"]
    R --> E["references/"]
    D --> D1["analyze_diff.py<br/>确定性事实提取"]
    D --> D2["render_commit.sh<br/>格式化并提交"]
    E --> E1["type_mapping.md<br/>归类规则资料"]
    style S fill:#fff3e0
    style D fill:#e8f5e9
    style E fill:#e1f5fe

mkdir demo && cd demo && git init
cat > app.py <<'EOF'
def auth(user, token):
    return user == "admin" and token != ""
EOF
git add app.py && git commit -m "init"

cat > app.py <<'EOF'
def auth(user, token):
    if not token:
        return False
    return user == "admin"
EOF
cat > test_app.py <<'EOF'
def test_empty_token_rejected():
    assert auth("admin", "") is False
EOF
git add app.py test_app.py

fix(auth): reject empty token in auth check

if command -v commitlint >/dev/null 2>&1; then
  echo "$header" | commitlint || { echo "✗ commitlint 拒绝，请修正"; exit 1; }
fi