Claude Code Skill机制深潜：渐进披露到Hook闭环

sequenceDiagram
    participant User as 用户输入
    participant CC as Claude Code运行时
    participant FS as 文件系统
    participant LLM as Claude LLM

    Note over CC: 阶段一：元数据扫描（启动时）
    CC->>FS: 扫描 skills/ 目录
    FS-->>CC: 返回所有 SKILL.md 的 frontmatter
    CC->>LLM: 注入 <available_skills> 列表（仅name+description）

    Note over CC: 阶段二：按需加载（触发时）
    User->>CC: "帮我创建一个React组件"
    CC->>LLM: 匹配可用Skill
    LLM-->>CC: 选择 frontend-design Skill
    CC->>FS: 读取完整 SKILL.md + 辅助文件
    FS-->>CC: 返回完整指令内容
    CC->>LLM: 注入完整Skill上下文
    LLM-->>User: 按Skill指令执行任务

my-skill/
├── SKILL.md              # 主指令文件（必须）
├── helpers/              # 辅助脚本（可选）
│   ├── validate.sh       # 验证脚本
│   └── generate.py       # 生成脚本
├── templates/            # 模板文件（可选）
│   └── component.tsx.tpl # 代码模板
└── examples/             # 示例文件（可选）
    └── output-sample.ts  # 预期输出样例

---
name: react-component-gen
description: >
  Generates production-ready React components with TypeScript,
  proper prop typing, and follows the team's design system.
  Use when the user asks to create, scaffold, or generate React
  components or UI elements.
trigger: 
  - "create react component"
  - "new react component"
  - "generate component"
  - "scaffold component"
---

# React Component Generator

## Instructions

You are a React component generator following our team conventions.

### Step 1: Analyze Requirements
- Parse the user's component description
- Identify required and optional props
- Determine if it needs state management

### Step 2: Generate Component
- Use TypeScript with strict typing
- Follow the template in templates/component.tsx.tpl
- Include proper JSDoc comments

### Step 3: Validate
- Run helpers/validate.sh to check the output
- Ensure all props are typed
- Verify naming conventions match `PascalCase`

✅ 好：Generates production-ready React components with TypeScript.
     Use when creating or scaffolding React UI elements.

❌ 差：A skill for React.（过于宽泛，会在任何 React 相关对话中触发）

❌ 差：Creates a Button component with primary color variant.（过于具体，
     只有完全匹配的请求才会触发）

# 在用户级 Skill 目录创建
mkdir -p ~/.claude/skills/commit-guard
cd ~/.claude/skills/commit-guard

---
name: commit-guard
description: >
  Enforces Conventional Commits specification for all git commits.
  Validates commit messages against type(scope): description format.
  Automatically activates when user asks to commit code or create
  a git commit message.
trigger:
  - "commit"
  - "git commit"
  - "create commit"
  - "commit message"
  - "make a commit"
hooks:
  PreToolUse:
    - match: "Bash"
      command: "echo 'Commit guard active: will validate message format'"
---

# Commit Guard — Conventional Commits Enforcer

## Overview

This skill ensures all commit messages follow the Conventional Commits
specification (v1.0.0). It validates messages before they are committed
and provides corrective suggestions when messages don't conform.

## Commit Message Format

All commit messages MUST follow this format:

## Allowed Types

| Type | Usage |
|------|-------|
| `feat` | A new feature |
| `fix` | A bug fix |
| `docs` | Documentation only changes |
| `style` | Changes that don't affect code meaning |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or correcting tests |
| `chore` | Build process or auxiliary tool changes |
| `ci` | CI/CD configuration changes |

## Validation Rules

When the user asks to commit, apply these checks IN ORDER:

1. **Format check**: Message matches `<type>(<scope>): <description>` pattern
2. **Type check**: Type is one of the allowed types listed above
3. **Case check**: Description starts with lowercase, no trailing period
4. **Length check**: First line is 72 characters or fewer
5. **Body check** (if present): Blank line separates subject from body

## Instructions

When creating or reviewing a commit message:

1. Analyze the staged changes using `git diff --staged`
2. Determine the most appropriate type based on the nature of changes
3. Auto-detect scope from affected file paths (e.g., `auth`, `api`, `ui`)
4. Generate a commit message following the format above
5. If the user provides their own message, validate it against all rules
6. If validation fails, explain the specific rule violated and suggest a fix
7. Never proceed with a non-conforming commit message

## Examples

### Valid commits:

### Invalid commits (do NOT allow):

> 帮我提交代码

[commit-guard skill activated]

Analyzing staged changes...
- modified: src/auth/oauth.ts (+45, -3)
- modified: src/auth/types.ts (+12, -0)
- new file: tests/auth/oauth.test.ts (+87, -0)

Suggested commit message:
  feat(auth): add OAuth2 login support with PKCE flow

Changes include:
- OAuth2 authorization code flow with PKCE
- Token refresh mechanism
- Unit tests for auth module

flowchart LR
    A[用户请求] --> B[Claude Code 解析]
    B --> C{匹配到 Skill?}
    C -->|Yes| D[加载 Skill 指令]
    D --> E[LLM 决定调用工具]
    E --> F{工具匹配 Hook?}
    F -->|PreToolUse| G[执行前置 Hook]
    G --> H[执行工具]
    H --> I{PostToolUse Hook?}
    I -->|Yes| J[执行后置 Hook]
    J --> K[返回结果给 LLM]
    F -->|No| H
    I -->|No| K
    C -->|No| L[正常处理]

---
name: commit-guard
description: >
  Enforces Conventional Commits specification for all git commits.
  Validates commit messages and prevents non-conforming commits.
  Automatically activates when user commits code or writes commit messages.
trigger:
  - "commit"
  - "git commit"
  - "create commit"
  - "commit message"
hooks:
  PreToolUse:
    - match: "Bash"
      command: |
        # 拦截 git commit 命令并校验消息格式
        INPUT="$CLAUDE_TOOL_INPUT"
        if echo "$INPUT" | grep -q "git commit"; then
          MSG=$(echo "$INPUT" | grep -oP '(?<=-m\s["\x27])[^\x27"]*' | head -1)
          if [ -n "$MSG" ]; then
            # 校验 Conventional Commits 格式
            if ! echo "$MSG" | grep -qP '^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\(.+\))?:\s.{1,72}'; then
              echo "BLOCK: Commit message does not follow Conventional Commits format."
              echo "Expected: <type>(<scope>): <description>"
              echo "Got: $MSG"
              exit 2
            fi
          fi
        fi
---

# <type>(<scope>): <short summary>
# 
# <longer description if needed>
#
# Allowed types: feat, fix, docs, style, refactor, perf, test, chore, ci
# Scope: module or component name (optional)
# Subject: lowercase, imperative mood, no period, ≤72 chars
# 
# Breaking changes: add BREAKING CHANGE: in footer
# Issues: add Refs: #123 in footer

#!/usr/bin/env bash
# validate-commit.sh — 校验 commit message 是否符合 Conventional Commits 规范
set -euo pipefail

MSG="${1:?Usage: validate-commit.sh <commit-message>}"
ALLOWED_TYPES="feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert"

# 规则1: 格式检查
if ! echo "$MSG" | head -1 | grep -qP "^($ALLOWED_TYPES)(\([^)]+\))?:\s.+"; then
  echo "FAIL: Invalid format. Expected <type>(<scope>): <description>"
  echo "  Allowed types: $ALLOWED_TYPES"
  exit 1
fi

# 规则2: 长度检查
FIRST_LINE=$(echo "$MSG" | head -1)
if [ ${#FIRST_LINE} -gt 72 ]; then
  echo "FAIL: First line exceeds 72 characters (${#FIRST_LINE} chars)"
  exit 1
fi

# 规则3: 大小写检查
DESC=$(echo "$MSG" | head -1 | sed 's/^[^:]*:\s*//')
if echo "$DESC" | grep -qP '^[A-Z]'; then
  echo "WARN: Description starts with uppercase (convention: lowercase)"
fi

if echo "$DESC" | grep -qP '\.$'; then
  echo "WARN: Description ends with period (convention: no trailing period)"
fi

echo "PASS: Commit message conforms to Conventional Commits v1.0.0"

## Validation Process

After generating a commit message, validate it by running:

\`\`\`bash
bash ~/.claude/skills/commit-guard/helpers/validate-commit.sh "<message>"
\`\`\`

Use the template at `~/.claude/skills/commit-guard/templates/commit-msg.tpl`
as the starting point for interactive commit message editing.

{
  "skill": "commit-guard",
  "evals": [
    {
      "name": "valid-feat-commit",
      "user_message": "commit these changes - I added a new login page",
      "expected_behavior": "Generates a commit message starting with 'feat' type",
      "should_trigger": true
    },
    {
      "name": "valid-fix-commit",
      "user_message": "fix the null pointer exception in user service",
      "expected_behavior": "Generates a commit message starting with 'fix' type",
      "should_trigger": true
    },
    {
      "name": "reject-bad-format",
      "user_message": "commit with message: added new feature",
      "expected_behavior": "Rejects the message and suggests Conventional Commits format",
      "should_trigger": true
    },
    {
      "name": "no-trigger-unrelated",
      "user_message": "explain how React hooks work",
      "expected_behavior": "Does NOT activate commit-guard skill",
      "should_trigger": false
    },
    {
      "name": "scope-detection",
      "user_message": "commit the auth module changes",
      "expected_behavior": "Includes 'auth' scope in commit message like feat(auth):",
      "should_trigger": true
    }
  ]
}

# 方法1：通过 Skill Creator 运行
claude "Use the skill-creator skill to evaluate commit-guard"

# 方法2：通过 /skill-creator 斜杠命令
# 在 Claude Code 交互模式中：
# /skill-creator evaluate commit-guard

flowchart TD
    A[编写初始 Skill] --> B[创建 Eval 测试集]
    B --> C[运行 Eval]
    C --> D{通过率 ≥ 90%?}
    D -->|No| E[分析失败案例]
    E --> F[优化 description / trigger / 指令]
    F --> C
    D -->|Yes| G[发布 Skill]
    G --> H[收集用户反馈]
    H --> I{有回归或新需求?}
    I -->|Yes| B
    I -->|No| J[维护模式]

# 创建仓库
mkdir commit-guard-skill && cd commit-guard-skill
git init
# 复制 Skill 文件
cp -r ~/.claude/skills/commit-guard/* .
git add . && git commit -m "feat: initial commit-guard skill"
git remote add origin https://github.com/YOUR_USERNAME/commit-guard-skill.git
git push -u origin main

# 克隆到本地 skills 目录
git clone https://github.com/YOUR_USERNAME/commit-guard-skill.git \
  ~/.claude/skills/commit-guard

{
  "name": "my-team-skills",
  "description": "Team skills for project XYZ",
  "skills": [
    {
      "name": "commit-guard",
      "source": "git+https://github.com/YOUR_USERNAME/commit-guard-skill.git",
      "path": "/"
    }
  ]
}

{
  "sources": [
    {
      "type": "git",
      "url": "https://github.com/YOUR_TEAM/skill-marketplace.git"
    }
  ]
}

{
  "name": "@your-org/claude-skill-commit-guard",
  "version": "1.0.0",
  "description": "Conventional Commits enforcement skill for Claude Code",
  "main": "SKILL.md",
  "files": ["SKILL.md", "helpers/**", "templates/**"],
  "keywords": ["claude-code", "skill", "conventional-commits", "git"]
}

npm install @your-org/claude-skill-commit-guard --prefix ~/.claude/skills/commit-guard

flowchart TB
    subgraph 设计阶段
        A[确定 Skill 功能边界] --> B[编写 description + trigger]
        B --> C[设计 frontmatter 元数据]
    end

    subgraph 开发阶段
        C --> D[编写 SKILL.md 指令]
        D --> E[创建辅助文件]
        E --> F[集成 Hook 自动化]
    end

    subgraph 测试阶段
        F --> G[编写 Eval 测试集]
        G --> H[运行 Eval 评估]
        H --> I{通过率达标?}
        I -->|No| J[分析失败→优化 Skill]
        J --> H
        I -->|Yes| K[准备发布]
    end

    subgraph 发布阶段
        K --> L{分发方式?}
        L -->|GitHub| M[推送到仓库]
        L -->|Marketplace| N[创建 marketplace.json]
        L -->|npm| O[发布 npm 包]
    end

    subgraph 维护阶段
        M --> P[收集反馈]
        N --> P
        O --> P
        P --> Q{需要更新?}
        Q -->|Yes| G
        Q -->|No| R[稳定运行]
    end

description: >
  [功能] Enforces Conventional Commits for git commits.
  [技术] Validates against type(scope): description format with 
         configurable allowed types.
  [触发] Use when committing code or writing commit messages.
         Do NOT use for git operations other than committing.

---
name: commit-guard
description: Enforces Conventional Commits.
---

<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task,
skip this skill and proceed with the task directly.
</SUBAGENT-STOP>

# Main Skill Instructions...

# 优先级高（精确匹配）
description: >
  Generates React Native mobile components. Use ONLY when the user
  explicitly mentions React Native or mobile app UI.

# 优先级低（宽泛匹配）
description: >
  Generates React components for web applications. Use when creating
  any React component not specifically for React Native.

## Reference Documentation

When working with authentication flows, refer to:
- OAuth2 spec: `~/.claude/skills/auth-guard/ref/oauth2-flows.md`
- Team conventions: `~/.claude/skills/auth-guard/ref/team-auth-standards.md`

Load these files ONLY when the specific topic is relevant to the task.

commit-guard/
├── SKILL.md                          # 主指令文件
├── helpers/
│   └── validate-commit.sh            # 格式校验脚本
├── templates/
│   └── commit-msg.tpl                # Commit 消息模板
├── examples/
│   ├── valid-commits.txt             # 有效 commit 示例
│   └── invalid-commits.txt           # 无效 commit 示例（附说明）
├── evals/
│   └── evals.json                    # Eval 测试集
└── README.md                         # 安装说明（可选）

# 1. 复制到 skills 目录
cp -r commit-guard ~/.claude/skills/

# 2. 重启 Claude Code 或新开对话
claude

# 3. 测试手动激活
> /commit-guard

# 4. 测试自动激活
> 帮我提交当前的代码变更
# 预期：Skill 自动激活，生成 Conventional Commits 格式的消息

# 5. 测试 Hook 拦截
> 用 git commit -m "added new feature" 提交
# 预期：Hook 拦截，提示格式不正确