name: hook-management description: 该存储库中Claude Code钩子管理的中枢权威。通过钩子自动化执行关键存储库规则。在添加钩子、管理钩子、配置钩子、故障排除钩子或理解钩子行为时使用。委托给docs-management技能以获取官方钩子文档。提供组织特定模式、配置管理和工作流指导。 user-invocable: false allowed-tools: Read, Glob, Grep, Skill

钩子元技能

🚨 强制：首先调用docs-management

停止 - 在提供任何关于Claude Code钩子的响应之前：

调用 docs-management 技能

查询使用关键词：钩子、PreToolUse、PostToolUse、钩子事件、钩子配置或相关主题

基于所有响应仅基于加载的官方文档

跳过此步骤将导致过时或错误的信息。

验证检查点

在响应之前，验证：

[ ] 我是否调用了docs-management技能？
[ ] 官方文档是否加载？
[ ] 我的响应是否仅基于官方文档？

如果有任何复选框未选中，停止并首先调用docs-management。

概述

该存储库中Claude Code钩子管理的中枢权威。自动化执行先前在CLAUDE.md中手动完成的关键存储库规则。

架构： 垂直切片组织，具有外部化配置、多语言支持、即时配置重新加载和全面测试。

何时使用此技能

关键词： 钩子、钩子管理、自动化、验证、执行、PreToolUse、PostToolUse、SessionStart、SessionEnd、Setup钩子、钩子配置、插件钩子、本地钩子、CLAUDE_HOOK_ENABLED、钩子环境变量、启用钩子、禁用钩子、–init、–init-only、–maintenance

在以下情况下使用此技能：

向存储库添加新钩子
修改现有钩子行为
故障排除钩子问题
禁用/启用钩子
理解哪些钩子处于活动状态
配置钩子执行级别

🚨 关键：官方钩子文档

对于所有Claude Code钩子功能、配置模式和语法，必须使用docs-management技能。

委托给docs-management的内容

⚠️ 过时警告： 不要硬编码钩子事件名称、决策值或环境变量。始终查询docs-management以获取权威的钩子功能列表。

官方钩子文档查询模式：

主题	查询模式	您将找到的内容
钩子事件类型	“hooks.md 钩子事件”、“钩子事件类型”	可用事件的完整列表
钩子配置	“hooks.md 配置语法”	JSON结构和必需字段
匹配器	“hooks.md 匹配器工具名称”	工具匹配模式
决策控制	“hooks.md 决策控制”、“钩子返回值”	有效的决策值和行为
退出代码	“hooks.md 退出代码”	退出代码含义
JSON输出	“hooks.md JSON输出模式”	钩子响应的输出模式
环境变量	“hooks.md 环境变量”	钩子中可用的环境变量
命令与提示钩子	“hooks.md 命令提示基于”	钩子类型差异
插件钩子	“hooks.md 插件钩子集成”	插件特定模式

示例查询：

docs-management: "hooks.md 钩子事件类型"
docs-management: "hooks.md 决策控制值"
docs-management: "hooks.md 可用环境变量"

Frontmatter钩子（v2.1.x）：

关键词：frontmatter钩子、技能钩子、代理钩子、命令钩子、once true
用例：在技能/代理/命令YAML frontmatter中定义钩子（不仅仅是.claude/hooks/）

SessionStart钩子输入（v2.1.2+）：

关键词：SessionStart、agent_type、--agent 标志
用例：当使用--agent CLI标志调用时，SessionStart钩子接收agent_type字段
注意：此字段在CHANGELOG v2.1.2中记录，但可能尚未在官方hooks.md中 - 查询docs-management以获取当前状态

PreToolUse additionalContext返回（v2.1.9+）：

关键词：PreToolUse、additionalContext、钩子返回、上下文注入
用例：PreToolUse钩子可以返回additionalContext字段以向模型提供额外上下文
查询模式：docs-management: "hooks.md PreToolUse additionalContext 返回"

Setup钩子事件（v2.1.10+）：

关键词：Setup钩子、Setup事件、--init、--init-only、--maintenance、存储库设置
用例：Setup钩子在通过CLI标志进行存储库初始化/维护期间运行
触发器：--init、--init-only或--maintenance CLI标志
查询模式：docs-management: "hooks.md Setup钩子事件"

此技能提供的内容

组织特定实现：

目录结构和约定
配置管理模式
共享实用程序（json、path、git、config助手）
活动钩子清单
多语言实现策略
此存储库钩子的故障排除

快速决策树

您想做什么？

理解设计原则 → 参见设计原则
查看活动钩子 → 参见活动钩子
管理钩子生命周期（启用/禁用/修改）→ 参见钩子生命周期
配置钩子 → 参见配置指南
创建新钩子 → 参见创建钩子工作流
测试钩子 → 参见测试指南
遵循最佳实践 → 参见最佳实践
故障排除问题 → 参见常见问题
调试钩子 → 参见调试指南
官方钩子文档 → 使用docs-management技能及上述关键词
创建/配置插件钩子 → 使用plugin-development技能（见下文）

插件钩子委托

如果您正在处理插件钩子（捆绑在Claude Code插件中的钩子），请使用plugin-development技能代替。插件钩子使用不同的配置模式：

方面	本地钩子（此技能）	插件钩子
位置	`.claude/hooks/` 目录	插件 `hooks/hooks.json`
配置	YAML文件（`config.yaml`）	环境变量
消费者控制	直接编辑配置文件	通过`settings.json` `env`部分

对于插件钩子： 调用plugin-development技能并参见插件钩子配置部分。

参考加载指南

此技能中的所有参考均为条件加载 - 仅根据需要基于您遵循的工作流加载。

何时加载每个参考

架构参考（理解设计时加载）：

references/architecture/design-principles.md → 当理解垂直切片、DRY、配置优于硬编码原则时
references/architecture/multi-language-strategy.md → 当实现或迁移到Python/TypeScript时

清单参考（处理钩子时加载）：

references/inventory/active-hooks.md → 当审查哪些钩子处于活动状态及其配置时
references/inventory/hook-lifecycle.md → 当启用/禁用钩子或更改执行模式时

配置参考（配置时加载）：

references/configuration/hook-config-guide.md → 当修改global.yaml或config.yaml文件时

开发参考（创建/测试时加载）：

references/development/creating-hooks-workflow.md → 当从头创建新钩子时
references/development/testing-guide.md → 当为钩子编写测试时
references/development/best-practices.md → 当确保代码质量和遵循模式时

故障排除参考（调试时加载）：

references/troubleshooting/common-issues.md → 当遇到问题时（钩子未运行、配置未应用等）
references/troubleshooting/debugging-guide.md → 当执行高级调试或性能分析时

渐进披露策略

第一层：始终在上下文中

SKILL.md（此文件） - 导航中心和决策树

第二层：按需加载

基于特定工作流或任务的参考文件

第三层：外部委托

通过docs-management技能查询的官方文档（始终）

此架构确保在保持全面指导覆盖的同时实现最佳令牌效率。

活动钩子摘要

完整详情，参见活动钩子参考。

PreToolUse钩子（执行前验证）

prevent-backup-files - 阻止git跟踪内容的.bak/.backup文件创建
require-gpg-signing - 阻止使用–no-gpg-sign标志的git提交
require-explicit-commit - 询问直接git提交的批准（鼓励使用git-commit技能）
block-absolute-paths - 阻止markdown文件中的绝对路径以确保可移植性

PostToolUse钩子（执行后自动修复）

markdown-lint - 使用markdownlint-cli2自动修复markdown文件

配置快速参考

所有钩子使用环境变量进行配置。完整详情参见配置指南。

快速操作：

启用钩子：在.claude/settings.json的env部分设置CLAUDE_HOOK_{NAME}_ENABLED=1
禁用钩子：设置CLAUDE_HOOK_{NAME}_ENABLED=0或删除变量
更改执行：设置CLAUDE_HOOK_ENFORCEMENT_{NAME}为block、warn或log
启用调试模式：设置CLAUDE_HOOK_DEBUG=1

在.claude/settings.json中的示例配置：

{
  "env": {
    "CLAUDE_HOOK_MARKDOWN_LINT_ENABLED": "1",
    "CLAUDE_HOOK_LOG_EVENTS_ENABLED": "1"
  }
}

对于环境变量模式、默认状态和遗留YAML配置，参见配置参考。

目录结构（垂直切片）

.claude/hooks/
├── config/
│   └── global.yaml                 # 共享配置
├── shared/                         # 共享实用程序（所有钩子）
│   ├── json-utils.sh               # JSON解析助手
│   ├── path-utils.sh               # 路径操作实用程序
│   ├── config-utils.sh             # 配置加载实用程序
│   └── test-helpers.sh             # 测试断言框架
├── prevent-backup-files/           # 垂直切片：钩子1
│   ├── bash/                       # 语言特定实现
│   ├── config.yaml                 # 用户配置（启用、执行）
│   ├── hook.yaml                   # 钩子元数据（名称、版本、描述）
│   ├── README.md                   # 钩子文档
│   └── tests/                      # 此钩子的测试
├── require-gpg-signing/            # 垂直切片：钩子2
│   ├── bash/
│   ├── config.yaml
│   ├── hook.yaml
│   ├── README.md
│   └── tests/
├── <其他钩子>/                  # 附加钩子遵循相同模式
├── test-runner.sh                  # 发现并运行所有*.test.sh文件
└── README.md                       # 快速参考

关键原则：

高内聚： 所有钩子代码、配置、文档和测试在一个目录中
低耦合： 钩子不相互依赖
易于修改： 更改隔离到单个目录
清晰所有权： 一个目录 = 一个功能

完整架构详情，参见设计原则。

共享实用程序快速参考

所有钩子都可以访问.claude/hooks/shared/中的共享助手函数。使用示例参见最佳实践。

注意： Bash实用程序为遗留兼容性维护。新钩子应使用Python的pathlib以支持跨平台。

常见工作流

快速操作

临时禁用所有钩子：

# 编辑 .claude/hooks/config/global.yaml
enabled: false

查看钩子活动：

# 编辑 .claude/hooks/config/global.yaml
log_level: debug

运行所有测试：

bash .claude/hooks/test-runner.sh

测试特定钩子：

bash .claude/hooks/<hook-name>/tests/integration.test.sh

手动测试：

echo '{"tool": "Write", "file_path": "test.txt"}' | \
  bash .claude/hooks/<hook-name>/bash/<hook-name>.sh

完整工作流指导，参见钩子生命周期。

与存储库集成

CLAUDE.md引用钩子进行自动执行。自动化的规则完整列表参见活动钩子。

下一步

首次用户

回顾活动钩子以了解执行的内容
阅读配置指南以学习如何自定义
检查常见问题以获取故障排除提示

钩子开发者

阅读设计原则以理解架构
遵循创建钩子工作流以创建新钩子
研究最佳实践以获取代码质量
使用测试指南以进行全面测试

故障排除

检查常见问题以获取已知问题
使用调试指南以进行高级技术
查询docs-management技能以获取官方文档

审计钩子

此技能提供hook-auditor代理进行正式审计时使用的验证标准。

审计资源

资源	位置	目的
审计框架	`references/audit-framework.md`	查询指导和评分标准

评分类别

类别	分数	关键标准
配置结构	25	有效的hooks.json、必需字段、有效事件类型
钩子脚本	20	脚本存在、正确结构、退出代码
匹配器	20	适当的工具/路径匹配器
环境变量	15	遵循命名约定、有文档
测试	20	有测试、测试通过、覆盖充分

阈值： 85+ = 通过，70-84 = 通过带警告，<70 = 失败

外部技术验证

当审计使用外部技术（脚本、包、运行时）的钩子时，审计员必须在使用MCP服务器验证声明之前标记发现。

需要MCP验证的技术：

.NET/C#脚本：使用microsoft-learn + perplexity验证
Node.js/npm包：使用context7 + perplexity验证
Python脚本/包：使用context7 + perplexity验证
Shell脚本：使用perplexity验证
任何版本特定声明：始终使用perplexity验证

验证规则：

在未首先验证的情况下，切勿将技术使用标记为不正确：

查询适当的MCP服务器以获取当前文档
使用perplexity验证最近变化（尤其是.NET 10+）
在发现中记录MCP来源

过时数据警告：

microsoft-learn可能返回缓存/过时文档
始终配对microsoft-learn与perplexity进行版本验证
相信perplexity获取版本号和最近发布的功能

参考

详细文档：

设计原则 - 垂直切片、DRY、配置优于硬编码
多语言策略 - Bash、Python、TypeScript实现模式
活动钩子 - 活动钩子的完整列表及描述
钩子生命周期 - 启用/禁用/修改钩子
配置指南 - 全局和每个钩子配置
创建钩子工作流 - 逐步创建钩子
测试指南 - 全面测试模式
最佳实践 - 代码质量和模式
常见问题 - 已知问题和解决方案
调试指南 - 高级调试技术

快速访问：

钩子目录： .claude/hooks/
共享实用程序： .claude/hooks/shared/（包括单元测试）
全局配置： .claude/hooks/config/global.yaml
快速参考： .claude/hooks/README.md
测试运行器： .claude/hooks/test-runner.sh
官方钩子文档： 通过docs-management技能（关键词：“钩子”、“PreToolUse”、“PostToolUse”）

测试场景

场景1：直接激活

查询：“使用hook-management技能添加新钩子”

预期行为：

技能在关键词"hook-management"、“add”、"hook"上激活
加载SKILL.md作为导航中心
将用户指向创建钩子工作流参考
委托官方钩子文档给docs-management技能

成功标准：用户接收到钩子创建的逐步指导

场景2：故障排除请求

查询：“我的钩子未运行，帮我调试它”

预期行为：

技能在关键词"hook"、"debug"上激活
加载常见问题或调试指南参考
提供钩子执行问题的诊断步骤
如果需要，委托官方钩子事件文档给docs-management

成功标准：用户识别并解决钩子执行问题

场景3：配置更改

查询：“如何禁用GPG签名钩子？”

预期行为：

技能在关键词"disable"、“hook”、"GPG"上激活
提供配置快速参考部分的快速参考
指向钩子生命周期参考以获取详细指导
显示确切的配置文件路径和YAML语法

成功标准：用户成功禁用特定钩子

场景4：架构理解

查询：“解释钩子目录结构”

预期行为：

技能在关键词"hooks"、“directory”、"structure"上激活
提供SKILL.md中的目录结构部分
链接到设计原则参考以深入理解
解释垂直切片架构模式

成功标准：用户理解钩子组织原则

场景5：官方文档委托

查询：“Claude Code中有哪些钩子事件可用？”

预期行为：

技能在关键词"hook events"、"Claude Code"上激活
识别此需要官方文档
委托给docs-management技能并带有适当关键词
不提供硬编码的钩子事件列表（可能过时）

成功标准：用户通过docs-management接收当前官方文档

版本历史

v1.4.3 (2026-01-16)：添加Setup钩子事件关键词（v2.1.10）
- 添加"Setup钩子事件（v2.1.10+）"关键词部分
- 关键词：Setup钩子、Setup事件、–init、–init-only、–maintenance、存储库设置
- 触发器：–init、–init-only或–maintenance CLI标志
- 启用存储库初始化/维护钩子的发现
v1.4.2 (2026-01-16)：添加PreToolUse additionalContext关键词（v2.1.9）
- 添加"PreToolUse additionalContext返回（v2.1.9+）"关键词部分
- 关键词：PreToolUse、additionalContext、钩子返回、上下文注入
- 启用通过PreToolUse钩子返回的上下文注入发现
v1.4.1 (2026-01-12)：添加SessionStart agent_type关键词（v2.1.2）
- 添加"SessionStart钩子输入（v2.1.2+）"关键词部分用于agent_type字段
- 关键词：SessionStart、agent_type、–agent标志
- 当使用–agent CLI标志时记录可用字段
v1.4.0 (2026-01-09)：添加v2.1.x frontmatter钩子关键词注册项
- 添加"Frontmatter钩子（v2.1.x）"关键词部分用于技能/代理/命令钩子
- 关键词：frontmatter钩子、技能钩子、代理钩子、命令钩子、once true
- 通过docs-management启用v2.1.x frontmatter钩子功能的发现
v1.3.0 (2025-12-01)：环境变量标准化
- 标准化所有钩子环境变量到CLAUDE_HOOK_{NAME}_ENABLED模式
- 添加权威的"环境变量约定"部分作为单一真相源
- 记录钩子默认状态（Essential=启用、Opt-in=禁用、Log Events=禁用）
- 记录日志事件特殊逻辑（主开关+单独开关）
- 添加关键词：CLAUDE_HOOK_ENABLED、钩子环境变量、启用钩子、禁用钩子
- 适当标记遗留YAML配置部分
v1.2.2 (2025-11-30)：插件钩子委托
- 为插件钩子添加决策树条目（委托给plugin-development技能）
- 添加插件钩子委托部分及比较表
- 添加"插件钩子"、"本地钩子"关键词
- 澄清范围：此技能用于本地钩子（.claude/hooks/），插件钩子使用不同模式
v1.2.1 (2025-11-25)：审计改进
- 为激活测试添加测试场景部分
- 向元数据添加上次审计跟踪
- 更新上次验证日期
- 基于全面审计的次要文档改进
v1.2.0 (2025-11-24)：配置架构澄清
- 澄清config.yaml（用户配置）和hook.yaml（元数据）之间的分离
- 更新文档以引用config.yaml用于运行时配置
- 更新目录结构以显示两个配置文件
- 使用双文件配置模式更新hook-config-guide.md
- 使用config.yaml创建步骤更新creating-hooks-workflow.md
- 基于2025-11-24的全面钩子审计
v1.1.0 (2025-11-18)：渐进披露重构
- 提取详细内容到references/目录（10个参考文件）
- 将SKILL.md从1014行减少到约350行（减少65%）
- 为常见查询提高约55%的令牌效率
- 添加参考加载指南以显式条件加载
- 具有清晰决策树和导航的中心架构
- 基于2025-11-18技能审计的审计建议
v1.0.0 (2025-11-18)：初始发布
- 集中钩子管理文档
- 委托模式给docs-management
- 活动钩子清单
- 多语言支持架构
- 垂直切片组织
- 全面共享实用程序
- 测试框架

最后更新

日期： 2026-01-16 模型： claude-opus-4-5-20251101

钩子元技能

🚨 强制：首先调用docs-management

验证检查点

概述

何时使用此技能

🚨 关键：官方钩子文档

委托给docs-management的内容

此技能提供的内容

快速决策树

插件钩子委托

参考加载指南

何时加载每个参考

渐进披露策略

第一层：始终在上下文中

第二层：按需加载

第三层：外部委托

活动钩子摘要

PreToolUse钩子（执行前验证）

PostToolUse钩子（执行后自动修复）

配置快速参考

目录结构（垂直切片）

共享实用程序快速参考

常见工作流

快速操作

与存储库集成

下一步

首次用户

钩子开发者

故障排除

审计钩子

审计资源

评分类别

相关代理

外部技术验证

参考

测试场景

场景1：直接激活

场景2：故障排除请求

场景3：配置更改

场景4：架构理解

场景5：官方文档委托

版本历史

最后更新