Hookify规则编写技能Skill WritingHookifyRules

---

name: 编写Hookify规则 description: 当用户要求“创建hookify规则”、“编写钩子规则”、“配置hookify”、“添加hookify规则”或需要关于hookify规则语法和模式的指导时，应使用此技能。 version: 0.1.0

编写Hookify规则

概述

Hookify规则是带有YAML frontmatter的markdown文件，用于定义要监视的模式和匹配时显示的消息。规则存储在.claude/hookify.{规则名称}.local.md文件中。

规则文件格式

基本结构

---
name: 规则标识符
enabled: true
event: bash|file|stop|prompt|all
pattern: 正则表达式模式
---

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

Frontmatter字段

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

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

enabled（必需）：布尔值以激活/停用

• true：规则活跃
• false：规则禁用（不会触发）
• 可在不删除规则的情况下切换

event（必需）：触发哪个钩子事件

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

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

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

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

• 用于简单的单条件规则
• 匹配命令（bash）或new_text（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'))"

或使用在线正则表达式测试器（如regex101.com，选择Python风格）。

常见陷阱

太宽泛：

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