SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场claude-hook-writer

claude-hook-writer

编程与开发

查看项目

更新于 10-15 18:31

技能介绍

用途

claude-hook-writer 是一份面向 Claude Code hooks 的编写指导技能，主要用于在新设计 hook、审查既有 hook 代码、调试 hook 失败、优化慢 hook、保护处理敏感数据的 hook，以及将 hook 作为 PRPM 包发布时提供专家级建议。它强调验证设计决策、强制最佳实践并防止常见陷阱。

核心原则

  1. 安全不可妥协：hook 以用户权限自动执行，可读取、修改或删除用户可访问的任何文件。必须校验和净化所有输入，hook 通过 stdin 接收 JSON，绝不能盲目信任。
  2. 可靠性优先于功能：99% 可用的 hook 就是坏的 hook。Unicode 文件名、路径空格、缺失工具等边界情况都会发生，部署前需用边界情况测试。
  3. 性能很重要：hook 会阻塞操作，5 秒的 hook 意味着 Claude 要等待 5 秒。保持 hook 快速，重操作放到后台运行。
  4. 优雅失败：依赖缺失、输入畸形、磁盘错误都可能发生，需显式处理错误、记录失败并返回有意义的退出码。

主要能力与设计要点

技能提供 hook 设计清单，先回答：目标事件是什么（PreToolUse、PostToolUse、UserPromptSubmit、SessionStart、SessionEnd、Notification、Stop / SubagentStop、PreCompact），由哪些工具触发（matcher 要具体，如 "Write"、"Edit|Write"、"Bash"、"mcp__github__"；"" 仅在日志/指标场景使用），需要哪些输入字段（如 file_path、command、old_string、new_string，并在使用前校验字段存在），应使用命令 hook 还是 prompt hook（命令 hook 快且确定，适合格式化、日志、文件检查；prompt hook 慢、上下文感知，适合复杂校验、安全分析、意图识别；除非需要 LLM 推理否则用命令 hook），以及用哪个退出码表达成功/失败（exit 0 成功继续；exit 2 阻塞操作并向 Claude 显示错误；exit 1 或其他为非阻塞错误，记录后继续）。PreToolUse 中 exit 2 阻止工具运行，exit 0 允许运行（可修改输入）；PostToolUse 中退出码不阻塞，用 exit 0 成功、1 记录错误。

常见陷阱

  1. 变量未加引号：未加引号的变量会按空白拆分，导致带空格或特殊字符的文件名出错；应写成 cat "$FILE"、prettier --write "$FILE"、rm "$FILE"。
  2. 不校验就信任输入：可能对恶意或畸形输入执行操作；应使用 jq -r '... // empty' 校验、检查路径非空、限定在 CLAUDE_PROJECT_DIR 内、拒绝包含 .. 的路径，防止路径穿越并保护项目外文件。
  3. 阻塞操作过久：同步运行测试或构建会阻塞 Claude 30 秒以上；应改为后台运行并立即 exit 0，目标 PreToolUse < 100ms、PostToolUse < 500ms。
  4. 阻塞时用错退出码：PreToolUse 中用 exit 1 只记录错误但不阻塞，必须用 exit 2 才能真正阻止。
  5. 假设工具已存在：未检查依赖会导致 hook 崩溃；应先用 command -v prettier 检查，缺失时跳过并以 exit 0 优雅降级。

使用方式

技能按需加载 6 个参考文件：security-requirements.md（输入校验、路径净化、屏蔽敏感文件）、reliability-performance.md（错误处理、超时、性能优化）、code-templates.md（可用 hook 示例，如保存即格式化、屏蔽敏感文件、日志记录）、quick-reference.md（快速语法查阅：退出码、jq 模式、环境变量）、testing-debugging.md（测试模式、边界情况、调试技巧）、publishing-guide.md（PRPM 打包、高级配置、README 模板）。技能列出了各参考文件的加载触发条件，并给出发布前检查清单，包括用 jq 校验 stdin、给变量加引号、脚本用绝对路径、屏蔽 .env 与密钥、优雅处理缺失工具、设置合理超时、错误输出到 stderr 或文件、用边界情况测试、在真实会话中测试、文档化依赖、语义化版本和清晰描述标签。

适用场景

适用于设计新 Claude Code hook、审查和调试 hook、优化 hook 性能、保护处理敏感数据的 hook，以及将 hook 发布为 PRPM 包。

限制

本技能为编写与审查 hook 的指导性内容，未提供独立的收费、价格或平台支持信息，官方文档与 PRPM 包链接见其资源部分。具体功能实现需结合自身项目环境与资料中提供的参考文件。