动态注入 + 脚本校验：从零打造提交守卫 Skill

commit-guard/
├── SKILL.md                 # 主指令（必需）
├── reference.md             # 规范细则（按需加载）
└── scripts/
    └── validate-commit-msg.sh   # 确定性校验脚本（执行，不读入上下文）

mkdir -p ~/.claude/skills/commit-guard/scripts

---
description: Generate a Conventional Commits message from staged changes and validate it before committing. Use when the user wants to commit, write a commit message, or says "提交"/"commit"/"帮我提交". disable-model-invocation is set, so invoke manually via /commit-guard.
disable-model-invocation: true
allowed-tools:
  - Bash(git diff *)
  - Bash(git commit *)
  - Bash(git status *)
---

## Staged changes

Current branch: !`git rev-parse --abbrev-ref HEAD`
Staged diff:
```!git diff --staged --stat
git diff --staged

**执行机制要点**（容易踩坑）：

1. 每个 `` !`cmd` `` 在 Claude 看到任何内容前**立即执行一次**，输出替换占位符——这是**预处理**，不是 Claude 执行的。
2. 替换**只跑一遍**：命令输出以纯文本插入，**不会被再次扫描**占位符，因此一个命令无法「吐出」一个供下一轮展开的占位符。
3. 行内形式 `` !`cmd` `` 仅在 `!` 出现在**行首**或**紧跟空白**时才被识别。写成 `KEY=!`cmd`` 这种紧贴形式，会被当作字面文本、**不执行**。
4. 多行命令用 ``` ```! ``` 围栏代码块（如上例），比行内形式更适合 `git diff` 这类多行输出。

**常见问题**：命令报错（比如暂存区为空）时，输出区会显示错误信息。可在第 5 步的校验脚本里前置判空，或直接让 Claude 读到空 diff 后提示用户先 `git add`。

> 如需在受控环境禁用此特性，可在 settings 设 `"disableSkillShellExecution": true`，每条命令会被替换成 `[shell command execution disabled by policy]`（bundled/managed skill 不受影响）。

## 第 4 步：`${CLAUDE_SKILL_DIR}` 让脚本工程化

LLM 生成的提交信息天生「不靠谱」——它会拼错类型名、超长、漏冒号。**确定性校验必须交给脚本**，而不是寄望于提示词约束。Skill 支持用 `${CLAUDE_SKILL_DIR}` 引用自身 `SKILL.md` 所在目录，从而在动态注入里调用自带的脚本，**无论当前工作目录在哪**都能找到。

先写校验脚本 `scripts/validate-commit-msg.sh`：

```bash
#!/usr/bin/env bash
# 校验 Conventional Commits 提交信息。用法: validate-commit-msg.sh "<message>"
set -euo pipefail
msg="$1"

# 1) 类型白名单 + 必须有冒号
regex='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9_-]+\))?(!)?: .{1,72}$'
header=$(printf '%s' "$msg" | head -n1)
if ! printf '%s' "$header" | grep -Eq "$regex"; then
  echo "FAIL: 首行不符合 Conventional Commits 规范。"
  echo "  期望: type(scope)!: subject（subject ≤72 字符）"
  echo "  实际: $header"
  exit 1
fi

# 2) subject 长度（中文按字符计）
subj_len=${#header}
if [ "$subj_len" -gt 80 ]; then
  echo "FAIL: 首行过长（$subj_len 字符 > 80）。"
  exit 1
fi

echo "PASS: $header"

chmod +x ~/.claude/skills/commit-guard/scripts/validate-commit-msg.sh

## 提交信息生成规则

严格遵循 Conventional Commits：`type(scope)!: subject`。
- type ∈ feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert
- scope 可选，小写；`!` 表示 breaking change
- subject ≤ 72 字符，祈使句、句末不加句号
- 仅基于上方 **Staged changes**，不得包含未暂存改动

## 落笔前必做：确定性校验

在 `git commit` 之前，用下方脚本校验你草拟的**首行**。若返回 FAIL，按提示修正后重试，**严禁**跳过校验直接提交：

```!msg=$(printf 'feat(api): add /health endpoint')
"${CLAUDE_SKILL_DIR}/scripts/validate-commit-msg.sh" "$msg" || echo "(替换为真实首行后再次运行)"

**为什么这样设计**：`${CLAUDE_SKILL_DIR}` 是 Skill 的「自指」锚点，让脚本随 Skill 一起分发、路径无关。校验脚本返回非零退出码时，配合「严禁跳过」的指令，构成一道**确定性护栏**——这是提示词无法保证的。这也是为什么官方把 scripts 定义为「**执行而不读入上下文**」的文件：它消耗的是 CPU 不是 token。

**常见问题**：Windows 用户若未启用 PowerShell 工具，`${CLAUDE_SKILL_DIR}` 下的 `.sh` 无法直接跑。两种解法：① 在 WSL 里用 Claude Code；② 把脚本改写为 `.ps1` 并在 frontmatter 设 `shell: powershell`（需 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`）。

## 第 5 步：参数化与多行提交（可选增强）

若你想 `/commit-guard` 时附加「关联的 issue 号」等参数，Skill 支持位置与命名参数替换。在 frontmatter 加：

```yaml
arguments: [ticket]

~/.claude/skills/commit-guard/scripts/validate-commit-msg.sh "feat: ok"
# 输出: PASS: feat: ok

~/.claude/skills/commit-guard/scripts/validate-commit-msg.sh "updated stuff"
# 输出: FAIL: 首行不符合 Conventional Commits 规范。

---
description: Generate a Conventional Commits message from staged changes and validate it before committing. Use when the user wants to commit, write a commit message, or says "提交"/"commit"/"帮我提交". Invoked manually via /commit-guard.
disable-model-invocation: true
allowed-tools:
  - Bash(git diff *)
  - Bash(git commit *)
  - Bash(git status *)
arguments: [ticket]
---

## Staged changes

Branch: !`git rev-parse --abbrev-ref HEAD`
Diff stat:
```!git diff --staged --stat

Unstaged (context only, do NOT commit): !`git status --short`

## 生成规则

遵循 Conventional Commits `type(scope)!: subject`：
- type ∈ feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert
- subject ≤ 72 字符，祈使句，句末无句号
- 仅基于上方 staged diff；若 diff 为空，提示用户先 `git add` 后停止
- 若提供了 $ticket，在正文后追加空行 + `Refs #$ticket`

## 落笔前确定性校验（严禁跳过）

把生成的真实首行传入脚本校验，FAIL 则修正重试：

```!"${CLAUDE_SKILL_DIR}/scripts/validate-commit-msg.sh "<你的真实首行>"```

PASS 后再用多行 `git commit` 提交（首行 + 空行 + 正文 + footer）。完成。

# Conventional Commits 完整规范摘要
- breaking change: type 后加 `!`，footer 写 `BREAKING CHANGE: <说明>`
- revert: `revert: <原首行>`，footer 写 `This reverts commit <hash>.`
- 多 scope 用 `/` 分隔，如 `feat(api/parser): ...`

flowchart TD
    A[输入 /commit-guard ticket] --> B[动态注入执行<br/>git diff --staged]
    B --> C{暂存区为空?}
    C -- 是 --> Z[提示先 git add, 停止]
    C -- 否 --> D[Claude 读到真实 diff<br/>按规则生成首行+正文]
    D --> E[调用 SKILL_DIR 校验脚本]
    E --> F{PASS?}
    F -- 否 --> G[按报错修正首行] --> E
    F -- 是 --> H[git commit 多行提交]
    H --> I[完成规范提交]
    style B fill:#e1f5ff
    style E fill:#fff4e1
    style F fill:#ffe1e1