enhance-hooks

用途

enhance-hooks 用于审查 Claude Code 钩子（hooks）的定义与脚本，检查其安全性、正确性与最佳实践。当需要审查钩子的安全性、超时设置以及 frontmatter 是否正确时使用。

主要能力

该技能分析钩子定义与脚本，内置完整的钩子知识参考，包括：

• 钩子生命周期事件：SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、SubagentStart、SubagentStop、Stop、PreCompact、SessionEnd、Notification，并标注各事件是否需要 matcher。
• 钩子类型：command 类型（执行 bash 命令，支持全部事件）与 prompt 类型（使用 LLM 评估，仅支持 Stop 和 SubagentStop 事件）。
• 配置位置：用户设置（~/.claude/settings.json）、项目设置（.claude/settings.json）、本地设置（.claude/settings.local.json）。
• 配置结构、matcher 语法、输入 JSON schema、退出码行为、输出 schema、环境变量（CLAUDE_PROJECT_DIR、CLAUDE_CODE_REMOTE、CLAUDE_ENV_FILE、CLAUDE_FILE_PATHS）以及实用钩子示例（安全防火墙、自动格式化、命令日志、工作流编排）。

检测模式共 33 项，分为九类：

1. Frontmatter 校验（HIGH 确定性）：要求 YAML frontmatter 使用 --- 分隔符，包含 name 与 description 字段；建议为 command 钩子设置 timeout（默认 30 秒）并指定钩子类型。
2. 脚本安全（HIGH 确定性）：要求脚本开头使用 set -euo pipefail、对 jq/JSON 解析进行错误处理、正确引用变量；标记危险模式如 rm -rf、git reset --hard、curl | sh、eval "$input"（HIGH），以及 rm -r、git push --force（MEDIUM）。
3. 退出码处理（HIGH 确定性）：检查成功路径是否缺少 exit 0、是否用 exit 1 而非 exit 2 表示阻塞、脚本末尾是否缺少退出码。
4. 钩子类型适配性（HIGH 确定性）：检查钩子类型是否匹配事件，标记在非 Stop/SubagentStop 事件上使用 prompt 钩子、缺少类型说明。
5. 生命周期事件适配性（MEDIUM 确定性）：标记 PostToolUse 钩子尝试阻塞操作（为时已晚）、PreToolUse 钩子执行繁重处理（应快速）、在不支持的事件上使用 prompt 钩子。
6. 超时配置（MEDIUM 确定性）：标记网络操作缺少超时、外部服务调用缺少超时、无正当理由的超长超时（>60 秒）。
7. 输出格式（MEDIUM 确定性）：检查 PreToolUse 输出字段 permissionDecision（allow/deny/ask）、permissionDecisionReason、updatedInput、additionalContext；标记无效的 permissionDecision 值、deny 决策缺少原因、JSON 输出格式错误。
8. Matcher 模式（MEDIUM 确定性）：检查 matcher 语法有效性，标记无效正则、过宽的 matcher（无正当理由的 *）、在不支持 matcher 的事件（Stop、SubagentStop）上使用 matcher。
9. 反模式（LOW 确定性）：钩子中逻辑过于复杂、缺少文档/注释、硬编码路径（应使用 $CLAUDE_PROJECT_DIR）、网络调用缺少错误处理、钩子脚本中包含密钥/凭据。

使用方式

工作流程：

1. Discover：查找钩子文件（.md、.sh、.json）。
2. Classify：识别钩子类型与事件。
3. Parse：提取 frontmatter 与脚本内容。
4. Check：针对内置知识运行所有模式检查。
5. Filter：应用确定性过滤。
6. Report：生成 Markdown 输出。
7. Fix：若存在 --fix 标志则应用自动修复。

参数解析：

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

自动修复实现（仅针对 HIGH 确定性问题的 6 项）：

1. 缺少安全头：添加 #!/usr/bin/env bash 与 set -euo pipefail。
2. 缺少退出码：在脚本末尾添加 exit 0。
3. 缺少 frontmatter 字段：补充 name、description、timeout。
4. 错误的阻塞退出码：将阻塞错误的 exit 1 替换为 exit 2。

输出格式为 Markdown，包含钩子名称、文件路径、类型、事件、摘要（HIGH/MEDIUM 问题计数），以及按 Frontmatter、Safety、Exit Code、Lifecycle、Output Format 分类的问题表格。

适用场景

• 审查 Claude Code 钩子脚本的安全性，识别危险命令模式。
• 校验钩子 frontmatter 是否完整、超时是否合理。
• 检查钩子类型与生命周期事件是否匹配。
• 检查退出码使用是否正确（尤其是阻塞场景应使用 exit 2）。
• 检查输出 schema 与 matcher 语法是否符合规范。
• 在带 --fix 参数时自动修复高确定性问题。

限制

• 仅对 HIGH 确定性问题应用自动修复。
• 对安全模式保持谨慎，假阴性比假阳性更严重。
• 从不删除内容，只建议改进。
• 依据内置知识参考进行校验。
• 关于收费、价格、平台支持范围等事实暂未提供。