skillhub-169-writing-hookify-rules/SKILL.md

name, description, version

name	description	version
Writing Hookify Rules	当用户要求「创建 hookify 规则」「编写 hook 规则」「配置 hookify」「添加 hookify 规则」或需要了解 hookify 规则语法与模式方面的指导时，应使用本技能。	0.1.0

编写 Hookify 规则

概述

Hookify 规则是带有 YAML frontmatter 的 markdown 文件，用于定义需要监控的模式以及在匹配到这些模式时显示的消息。规则存储在 .claude/hookify.{rule-name}.local.md 文件中。

规则文件格式

基本结构

---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---

当此规则触发时向 Claude 显示的消息。
可以包含 markdown 格式、警告、建议等内容。

Frontmatter 字段

name（必填）：规则的唯一标识符

• 使用 kebab-case 命名：warn-dangerous-rm、block-console-log
• 应具有描述性且面向操作
• 以动词开头：warn、prevent、block、require、check

enabled（必填）：用于激活/停用的布尔值

• true：规则处于活动状态
• false：规则被禁用（不会触发）
• 可在不删除规则的情况下切换

event（必填）：触发哪个 hook 事件

• bash：Bash 工具命令
• file：Edit、Write、MultiEdit 工具
• stop：当代理要停止时
• prompt：当用户提交提示时
• all：所有事件

action（可选）：规则匹配时执行的操作

• warn：显示消息但允许操作（默认值）
• block：阻止操作（PreToolUse）或停止会话（Stop 事件）
• 如果省略，默认值为 warn

pattern（简单格式）：要匹配的正则表达式模式

• 用于简单的单条件规则
• 针对命令（bash）或新文本（file）进行匹配
• 使用 Python 正则表达式语法

示例：

event: bash
pattern: rm\s+-rf

高级格式（多条件）

适用于包含多个条件的复杂规则：

---
name: warn-env-file-edits
enabled: true
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.env$
  - field: new_text
    operator: contains
    pattern: API_KEY
---

你正在向 .env 文件添加 API 密钥。请确保此文件已在 .gitignore 中！

条件字段：

• field：要检查的字段
  • 对于 bash：command
  • 对于 file：file_path、new_text、old_text、content
• operator：匹配方式
  • regex_match：正则表达式模式匹配
  • contains：子字符串检查
  • equals：精确匹配
  • not_contains：子字符串不得出现
  • starts_with：前缀检查
  • ends_with：后缀检查
• pattern：要匹配的模式或字符串

所有条件必须同时满足，规则才会触发。

消息正文

frontmatter 之后的 markdown 内容将在规则触发时显示给 Claude。

良好的消息：

• 说明检测到了什么
• 解释为什么有问题
• 建议替代方案或最佳实践
• 使用格式提高清晰度（加粗、列表等）

示例：

⚠️ **检测到 Console.log！**

你正在向生产代码中添加 console.log。

**为什么这很重要：**
- 调试日志不应发布到生产环境
- Console.log 可能暴露敏感数据
- 影响浏览器性能

**替代方案：**
- 使用合适的日志库
- 在提交前删除
- 使用条件调试构建

事件类型指南

bash 事件

匹配 Bash 命令模式：

---
event: bash
pattern: sudo\s+|rm\s+-rf|chmod\s+777
---

检测到危险命令！

常见模式：

• 危险命令：rm\s+-rf、dd\s+if=、mkfs
• 权限提升：sudo\s+、su\s+
• 权限问题：chmod\s+777、chown\s+root

file 事件

匹配 Edit/Write/MultiEdit 操作：

---
event: file
pattern: console\.log\(|eval\(|innerHTML\s*=
---

检测到可能有问题的代码模式！

在不同字段上匹配：

---
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.tsx?$
  - field: new_text
    operator: regex_match
    pattern: console\.log\(
---

TypeScript 文件中的 Console.log！

常见模式：

• 调试代码：console\.log\(、debugger、print\(
• 安全风险：eval\(、innerHTML\s*=、dangerouslySetInnerHTML
• 敏感文件：\.env$、credentials、\.pem$
• 生成的文件：node_modules/、dist/、build/

stop 事件

匹配代理要停止时（完成检查）：

---
event: stop
pattern: .*
---

停止前，请确认：
- [ ] 测试已运行
- [ ] 构建成功
- [ ] 文档已更新

适用场景：

• 关于必需步骤的提醒
• 完成检查清单
• 流程强制执行

prompt 事件

匹配用户提示内容（高级用法）：

---
event: prompt
conditions:
  - field: user_prompt
    operator: contains
    pattern: deploy to production
---

生产环境部署检查清单：
- [ ] 测试通过？
- [ ] 团队审核通过？
- [ ] 监控已就绪？

模式编写技巧

正则表达式基础

字面字符： 大多数字符匹配自身

• rm 匹配 "rm"
• console.log 匹配 "console.log"

特殊字符需要转义：

• .（任意字符）→ \.（字面点号）
• ( ) → \( \)（字面括号）
• [ ] → \[ \]（字面方括号）

常用元字符：

• \s — 空白字符（空格、制表符、换行符）
• \d — 数字（0-9）
• \w — 单词字符（a-z、A-Z、0-9、_）
• . — 任意字符
• + — 一个或多个
• * — 零个或多个
• ? — 零个或一个
• | — 逻辑或

示例：

rm\s+-rf         匹配：rm -rf、rm  -rf
console\.log\(   匹配：console.log(
(eval|exec)\(    匹配：eval( 或 exec(
chmod\s+777      匹配：chmod 777、chmod  777
API_KEY\s*=      匹配：API_KEY=、API_KEY =

测试模式

在使用前测试正则表达式模式：

python3 -c "import re; print(re.search(r'your_pattern', 'test text'))"

或使用在线正则表达式测试工具（使用 Python 语法的 regex101.com）。

常见陷阱

过于宽泛：

pattern: log    # 会匹配 "log"、"login"、"dialog"、"catalog"

更好的写法：console\.log\(|logger\.

过于具体：

pattern: rm -rf /tmp  # 只匹配精确路径

更好的写法：rm\s+-rf

转义问题：

• YAML 带引号字符串："pattern" 需要使用双反斜杠 \\s
• YAML 不带引号：pattern: \s 直接使用即可
• 建议： 在 YAML 中使用不带引号的模式

文件组织

存放位置： 所有规则放在 .claude/ 目录下 命名规范： .claude/hookify.{描述性名称}.local.md Gitignore： 将 .claude/*.local.md 添加到 .gitignore

良好的命名：

• hookify.dangerous-rm.local.md
• hookify.console-log.local.md
• hookify.require-tests.local.md
• hookify.sensitive-files.local.md

不良的命名：

• hookify.rule1.local.md（缺乏描述性）
• hookify.md（缺少 .local）
• danger.local.md（缺少 hookify 前缀）

工作流程

创建规则

1. 识别需要禁止的行为
2. 确定涉及哪个工具（Bash、Edit 等）
3. 选择事件类型（bash、file、stop 等）
4. 编写正则表达式模式
5. 在项目根目录创建 .claude/hookify.{名称}.local.md 文件
6. 立即测试——规则会在下次使用工具时动态读取

优化规则

1. 编辑 .local.md 文件
2. 调整模式或消息
3. 立即测试——更改会在下次使用工具时生效

禁用规则

临时禁用： 在 frontmatter 中设置 enabled: false 永久删除： 删除 .local.md 文件

示例

请参阅 ${CLAUDE_PLUGIN_ROOT}/examples/ 获取完整示例：

• dangerous-rm.local.md — 阻止危险的 rm 命令
• console-log-warning.local.md — 警告 console.log
• sensitive-files-warning.local.md — 警告编辑 .env 文件

快速参考

最简可行规则：

---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---

此处为警告消息

带条件的规则：

---
name: my-rule
enabled: true
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.ts$
  - field: new_text
    operator: contains
    pattern: any
---

警告消息

事件类型：

• bash — Bash 命令
• file — 文件编辑
• stop — 完成检查
• prompt — 用户输入
• all — 所有事件

字段选项：

• Bash：command
• File：file_path、new_text、old_text、content
• Prompt：user_prompt

运算符：

• regex_match、contains、equals、not_contains、starts_with、ends_with