Hook Factory v2.0

生成生产就绪的 Claude Code 钩子，通过交互式问答、自动安装和增强验证。支持10个模板跨7种事件类型，全面覆盖工作流自动化。

这个技能做什么

Hook Factory v2.0 是一个全面钩子生成系统，包含三种模式：

交互模式（全新！） - 7个问题的引导流程，智能默认值
自然语言 - 用普通英语描述你想要的
模板模式 - 直接从10个生产模板生成

主要特点：

交互式问答 - 7个问题带有验证和智能默认值
自动安装 - Python和Bash安装程序，带有备份/回滚
增强验证 - 检测秘密、事件特定规则、命令验证
10个模板 - 覆盖7种事件类型（PostToolUse, SubagentStop, SessionStart, PreToolUse, UserPromptSubmit, Stop, PrePush）
全面安全 - 工具检测、静默失败、原子操作
macOS/Linux支持 - 适用于Unix环境的生产就绪

何时使用这个技能

当你想要：

编辑后自动格式化代码
使用git自动暂存文件
代理完成时运行测试
会话开始时加载项目上下文
创建自定义工作流自动化
通过示例学习钩子的工作原理

能力

三种生成模式

1. 交互模式（推荐）

python3 hook_factory.py -i

7个问题的引导流程
基于事件类型的智能默认值
输入验证和安全警告
可选自动安装

2. 自然语言模式

python3 hook_factory.py -r "编辑后自动格式化Python文件"

简单的关键词匹配
快速生成常见模式

3. 模板模式（高级）

python3 hook_factory.py -t post_tool_use_format -l python

直接选择模板
全定制控制

支持的钩子模板（共10个）

格式化和代码质量：

post_tool_use_format - 编辑后自动格式化（Python, JS, TS, Rust, Go）
post_tool_use_git_add - 使用git自动暂存文件

测试和验证： 3. subagent_stop_test_runner - 代理完成时运行测试 4. pre_tool_use_validation - 执行工具前验证 5. pre_push_validation - git推送前检查

会话管理： 6. session_start_load_context - 会话开始时加载上下文 7. stop_session_cleanup - 会话结束时清理

用户交互： 8. user_prompt_submit_preprocessor - 预处理用户提示 9. notify_user_desktop - 桌面通知（macOS/Linux）

安全： 10. security_scan_code - 使用semgrep/bandit进行安全扫描

支持的语言

Python（black格式化器，pytest）
JavaScript（prettier, jest）
TypeScript（prettier, jest）
Rust（rustfmt, cargo test）
Go（gofmt, go test）

增强验证（v2.0）

4层验证系统：

结构验证 - JSON语法，必填字段，类型
安全验证 - 无破坏性操作，工具检测，静默失败
匹配器验证 - 有效的glob模式，工具名称，文件路径
事件特定验证 - 每种事件类型的规则（PreToolUse, SessionStart等）

v2.0中的新功能：

✅ 秘密检测 - AWS密钥，JWT令牌，API密钥，私钥（20+模式）
✅ 事件特定规则 - PreToolUse必须有工具匹配器，SessionStart只读等。
✅ 命令验证 - Bash语法，Unix命令，路径验证，危险操作
✅ macOS/Linux验证 - 平台特定的命令检查

安全特性

每个生成的钩子都包括：

✅ 工具检测（检查是否安装了所需的工具）
✅ 静默失败模式（永远不会中断你的工作流）
✅ 适当的超时设置（基于事件类型5s-120s）
✅ 无破坏性操作
✅ 生成前的全面验证
✅ 清晰的文档和故障排除指南
✅ 安装期间自动备份

如何调用

自然语言请求

简单描述钩子要做什么：

"编辑后自动格式化Python文件"
"创建一个代理完成时运行测试的钩子"
"编辑后自动将文件添加到git"
"会话开始时加载我的TODO.md"

明确模板选择

如果你知道你想要的模板：

"为JavaScript生成一个使用post_tool_use_format模板的钩子"
"为Rust创建一个测试运行器钩子"

列出可用模板

"显示所有可用的钩子模板"
"列出钩子模板"

示例交互

示例1：自动格式化Python

你： “我需要一个钩子，在编辑后自动格式化我的Python代码”

Hook Factory：

检测模板：post_tool_use_format
检测语言：Python
生成带有black格式化器的钩子
验证配置
保存到generated-hooks/auto-format-code-after-editing-python/
创建hook.json和README.md

示例2：Git自动添加

你： “当我编辑它们时，自动使用git暂存文件”

Hook Factory：

检测模板：post_tool_use_git_add
生成git自动添加钩子
验证git命令
保存到generated-hooks/auto-add-files-to-git-after-editing/

示例3：测试运行器

你： “代理完成编码后运行我的JavaScript测试”

Hook Factory：

检测模板：subagent_stop_test_runner
检测语言：JavaScript
配置jest/npm测试
保存到generated-hooks/run-tests-when-agent-completes-javascript/

输出结构

对于每个钩子，Hook Factory创建：

generated-hooks/
└── [钩子名称]/
    ├── hook.json        # 完整的钩子配置（已验证）
    └── README.md        # 安装指南，使用说明，故障排除

hook.json

有效的JSON配置，准备复制到你的Claude Code设置中：

{
  "matcher": {
    "tool_names": ["Write", "Edit"]
  },
  "hooks": [
    {
      "type": "command",
      "command": "if ! command -v black &> /dev/null; then
    exit 0
fi

if [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.py ]]; then
    black \"$CLAUDE_TOOL_FILE_PATH\" || exit 0
fi",
      "timeout": 60
    }
  ]
}

README.md

全面的文档包括：

概述及其工作原理
先决条件
安装说明（手动）
配置选项
安全注意事项
故障排除指南
高级自定义提示

安装生成的钩子

自动安装（v2.0中的新功能！）

使用Python安装程序：

cd generated-skills/hook-factory

# 安装到用户级别（~/.claude/settings.json）
python3 installer.py install generated-hooks/[钩子名称] user

# 安装到项目级别（.claude/settings.json）
python3 installer.py install generated-hooks/[钩子名称] project

# 卸载
python3 installer.py uninstall [钩子名称] user

# 列出已安装的钩子
python3 installer.py list user

使用Bash脚本（macOS/Linux）：

cd generated-skills/hook-factory

# 安装
./install-hook.sh generated-hooks/[钩子名称] user

# 特性：
# - 自动备份并带有时间戳
# - JSON验证前后
# - 原子写操作
# - 失败时回滚
# - 保留最后5个备份

从交互模式自动安装：

回答Q7（自动安装）为’y’
钩子自动安装
无需手动步骤

手动安装（遗留）

审查生成的文件

cd generated-hooks/[钩子名称]
cat README.md
cat hook.json

手动安装
- 打开.claude/settings.json（项目）或~/.claude/settings.json（用户）
- 从hook.json复制钩子配置
- 添加到适当的事件类型数组
- 保存并重启Claude Code
验证
- 检查Claude Code日志：~/.claude/logs/
- 通过执行触发动作来测试钩子

验证

每个钩子都经过验证：

JSON语法：有效，可解析的JSON
结构：必填字段存在且类型正确
安全：无破坏性操作（rm -rf等）
工具检测：外部工具有检测检查
静默失败：命令不会中断工作流
超时：适合事件类型
匹配器：有效的glob模式和工具名称

最佳实践

从简单开始：使用自然语言请求常见模式
安装前审查：始终阅读生成的README.md
在隔离中测试：首先在测试项目中尝试钩子
逐步自定义：从默认值开始，稍后自定义
监控日志：如果钩子不起作用，请检查~/.claude/logs/

限制

平台支持：

✅ macOS和Linux完全支持
❌ Windows不支持（Unix命令，bash特定语法）

自定义：

交互模式提供智能默认值，但深度自定义有限
高级用户应使用模板模式+手动编辑
无GUI - 仅限CLI

模板系统：

10个模板覆盖常见模式
自定义模板需要手动添加到templates.json
尚未组合多个模式（组合多个模式）

技术细节

此技能中的文件

核心文件：

SKILL.md - 此清单文件
hook_factory.py - 主要协调器，带CLI界面（687行）
generator.py - 模板替换和钩子生成
validator.py - 增强验证引擎（700+行）
templates.json - 10个生产钩子模板
README.md - 技能使用指南和示例

v2.0中的新功能：

installer.py - 自动安装系统（536行）
install-hook.sh - Bash安装脚本（148行）
examples/ - 10个参考示例（10个文件夹×2个文件）

依赖关系

Python 3.7+
标准库（无外部依赖）

架构（v2.0）

交互模式流程：

用户：python3 hook_factory.py -i
    ↓
[7个问题的流程，带有智能默认值]
    ↓
[模板选择]
    ↓
[变量替换]
    ↓
[4层验证]
    ↓
[文件生成]
    ↓
[可选：通过installer.py自动安装]
    ↓
生成的钩子在generated-hooks/ + 安装

自然语言流程：

用户请求
    ↓
[关键词匹配]
    ↓
[模板选择]
    ↓
[变量替换]
    ↓
[4层验证]
    ↓
[文件生成]
    ↓
生成的钩子在generated-hooks/

安装流程：

钩子文件夹
    ↓
[installer.py或install-hook.sh]
    ↓
[备份settings.json]
    ↓
[加载+验证JSON]
    ↓
[合并钩子]
    ↓
[原子写入（临时→重命名）]
    ↓
[验证结果]
    ↓
✅ 安装（或❌ 回滚）

故障排除

“无法从请求中确定钩子类型”

使用更具体的关键词（格式化，测试，git添加，加载）
或使用明确的模板选择
或列出模板以查看可用内容

生成的钩子不起作用

检查Claude Code日志
验证所需工具是否已安装
在终端手动测试命令
查看README.md故障排除部分

验证错误

查看错误消息和修复建议
常见问题：缺少工具检测，破坏性命令
如有需要，修改模板

示例目录

examples/目录包含参考实现：

examples/
├── auto-format-python/      # PostToolUse格式化示例
├── git-auto-add/            # PostToolUse git示例
├── test-runner/             # SubagentStop测试示例
└── load-context/            # SessionStart上下文示例

每个示例包括工作的hook.json和README.md文件，你可以直接复制。

贡献

要添加新的钩子模式：

添加模板到templates.json
更新generator.py中的关键词匹配
在examples/中添加示例
更新此SKILL.md

版本历史

1.0.0 （2025-10-30）：初始发布
- 4个核心钩子模式
- 自然语言生成
- 全面验证
- 简单的关键词匹配

支持

文档：请参阅技能目录中的README.md
示例：请参阅examples/目录
验证问题：检查validator.py输出
Claude Code Hooks：https://docs.claude.com/en/docs/claude-code/hooks

由Claude Code Skills Factory生成 最后更新： 2025-10-30