Writing Hookify Rules

anthropics/claude-plugins-official/plugins/hookify/skills/writing-rules

作者 anthropicsb78ac49cdc6b無授權條款47K 個星標收錄於 2026年11月20日更新於 2026年11月20日儲存庫今天更新

This skill should be used when the user asks to "create a hookify rule", "write a hook rule", "configure hookify", "add a hookify rule", or needs guidance on hookify rule syntax and patterns.

精選僅含說明AI 與代理程式
AI 產生的概覽

指導撰寫 hookify 規則:帶 YAML frontmatter 的 Markdown 檔案,用來比對樣式並向 Claude 顯示提示訊息。

功能
說明存放於 .claude/hookify.{rule-name}.local.md 的 hookify 規則檔案格式,包含必填的 frontmatter 欄位(name、enabled、event、pattern)與選用的 action。介紹多條件的高階寫法,涉及欄位、運算子與比對樣式,並說明規則觸發時顯示的訊息內容該如何撰寫。另提供正規表示式技巧、常見陷阱、檔案命名慣例,以及建立、調整、停用規則的流程。
適用情境
當使用者要求建立、撰寫或設定 hookify 規則,或需要了解 hookify 規則語法、事件類型、條件與正規表示式樣式時使用。
執行需求
沒有指令碼,僅為說明文件。文中提到可用 python3 測試正規表示式,並參考外掛根目錄下的範例檔案,但除代理程式外不需其他相依項目。

Writing Hookify Rules

Overview

Hookify rules are markdown files with YAML frontmatter that define patterns to watch for and messages to show when those patterns match. Rules are stored in .claude/hookify.{rule-name}.local.md files.

Rule File Format

Basic Structure

markdown
---name: rule-identifierenabled: trueevent: bash|file|stop|prompt|allpattern: regex-pattern-here---
Message to show Claude when this rule triggers.Can include markdown formatting, warnings, suggestions, etc.

Frontmatter Fields

name (required): Unique identifier for the rule

  • Use kebab-case: warn-dangerous-rm, block-console-log
  • Be descriptive and action-oriented
  • Start with verb: warn, prevent, block, require, check

enabled (required): Boolean to activate/deactivate

  • true: Rule is active
  • false: Rule is disabled (won't trigger)
  • Can toggle without deleting rule

event (required): Which hook event to trigger on

  • bash: Bash tool commands
  • file: Edit, Write, MultiEdit tools
  • stop: When agent wants to stop
  • prompt: When user submits a prompt
  • all: All events

action (optional): What to do when rule matches

  • warn: Show message but allow operation (default)
  • block: Prevent operation (PreToolUse) or stop session (Stop events)
  • If omitted, defaults to warn

pattern (simple format): Regex pattern to match

  • Used for simple single-condition rules
  • Matches against command (bash) or new_text (file)
  • Python regex syntax

Example:

yaml
event: bashpattern: rm\s+-rf

Advanced Format (Multiple Conditions)

For complex rules with multiple conditions:

markdown
---name: warn-env-file-editsenabled: trueevent: fileconditions:  - field: file_path    operator: regex_match    pattern: \.env$  - field: new_text    operator: contains    pattern: API_KEY---
You're adding an API key to a .env file. Ensure this file is in .gitignore!

Condition fields:

  • field: Which field to check
    • For bash: command
    • For file: file_path, new_text, old_text, content
  • operator: How to match
    • regex_match: Regex pattern matching
    • contains: Substring check
    • equals: Exact match
    • not_contains: Substring must NOT be present
    • starts_with: Prefix check
    • ends_with: Suffix check
  • pattern: Pattern or string to match

All conditions must match for rule to trigger.

Message Body

The markdown content after frontmatter is shown to Claude when the rule triggers.

Good messages:

  • Explain what was detected
  • Explain why it's problematic
  • Suggest alternatives or best practices
  • Use formatting for clarity (bold, lists, etc.)

Example:

markdown
⚠️ **Console.log detected!**
You're adding console.log to production code.
**Why this matters:**- Debug logs shouldn't ship to production- Console.log can expose sensitive data- Impacts browser performance
**Alternatives:**- Use a proper logging library- Remove before committing- Use conditional debug builds

Event Type Guide

bash Events

Match Bash command patterns:

markdown
---event: bashpattern: sudo\s+|rm\s+-rf|chmod\s+777---
Dangerous command detected!

Common patterns:

  • Dangerous commands: rm\s+-rf, dd\s+if=, mkfs
  • Privilege escalation: sudo\s+, su\s+
  • Permission issues: chmod\s+777, chown\s+root

file Events

Match Edit/Write/MultiEdit operations:

markdown
---event: filepattern: console\.log\(|eval\(|innerHTML\s*=---
Potentially problematic code pattern detected!

Match on different fields:

markdown
---event: fileconditions:  - field: file_path    operator: regex_match    pattern: \.tsx?$  - field: new_text    operator: regex_match    pattern: console\.log\(---
Console.log in TypeScript file!

Common patterns:

  • Debug code: console\.log\(, debugger, print\(
  • Security risks: eval\(, innerHTML\s*=, dangerouslySetInnerHTML
  • Sensitive files: \.env$, credentials, \.pem$
  • Generated files: node_modules/, dist/, build/

stop Events

Match when agent wants to stop (completion checks):

markdown
---event: stoppattern: .*---
Before stopping, verify:- [ ] Tests were run- [ ] Build succeeded- [ ] Documentation updated

Use for:

  • Reminders about required steps
  • Completion checklists
  • Process enforcement

prompt Events

Match user prompt content (advanced):

markdown
---event: promptconditions:  - field: user_prompt    operator: contains    pattern: deploy to production---
Production deployment checklist:- [ ] Tests passing?- [ ] Reviewed by team?- [ ] Monitoring ready?

Pattern Writing Tips

Regex Basics

Literal characters: Most characters match themselves

  • rm matches "rm"
  • console.log matches "console.log"

Special characters need escaping:

  • . (any char) → \. (literal dot)
  • ( ) → \( \) (literal parens)
  • [ ] → \[ \] (literal brackets)

Common metacharacters:

  • \s - whitespace (space, tab, newline)
  • \d - digit (0-9)
  • \w - word character (a-z, A-Z, 0-9, _)
  • . - any character
  • + - one or more
  • * - zero or more
  • ? - zero or one
  • | - OR

Examples:

rm\s+-rf         Matches: rm -rf, rm  -rfconsole\.log\(   Matches: console.log((eval|exec)\(    Matches: eval( or exec(chmod\s+777      Matches: chmod 777, chmod  777API_KEY\s*=      Matches: API_KEY=, API_KEY =

Testing Patterns

Test regex patterns before using:

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

Or use online regex testers (regex101.com with Python flavor).

Common Pitfalls

Too broad:

yaml
pattern: log    # Matches "log", "login", "dialog", "catalog"

Better: console\.log\(|logger\.

Too specific:

yaml
pattern: rm -rf /tmp  # Only matches exact path

Better: rm\s+-rf

Escaping issues:

  • YAML quoted strings: "pattern" requires double backslashes \\s
  • YAML unquoted: pattern: \s works as-is
  • Recommendation: Use unquoted patterns in YAML

File Organization

Location: All rules in .claude/ directory Naming: .claude/hookify.{descriptive-name}.local.md Gitignore: Add .claude/*.local.md to .gitignore

Good names:

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

Bad names:

  • hookify.rule1.local.md (not descriptive)
  • hookify.md (missing .local)
  • danger.local.md (missing hookify prefix)

Workflow

Creating a Rule

  1. Identify unwanted behavior
  2. Determine which tool is involved (Bash, Edit, etc.)
  3. Choose event type (bash, file, stop, etc.)
  4. Write regex pattern
  5. Create .claude/hookify.{name}.local.md file in project root
  6. Test immediately - rules are read dynamically on next tool use

Refining a Rule

  1. Edit the .local.md file
  2. Adjust pattern or message
  3. Test immediately - changes take effect on next tool use

Disabling a Rule

Temporary: Set enabled: false in frontmatter Permanent: Delete the .local.md file

Examples

See ${CLAUDE_PLUGIN_ROOT}/examples/ for complete examples:

  • dangerous-rm.local.md - Block dangerous rm commands
  • console-log-warning.local.md - Warn about console.log
  • sensitive-files-warning.local.md - Warn about editing .env files

Quick Reference

Minimum viable rule:

markdown
---name: my-ruleenabled: trueevent: bashpattern: dangerous_command---
Warning message here

Rule with conditions:

markdown
---name: my-ruleenabled: trueevent: fileconditions:  - field: file_path    operator: regex_match    pattern: \.ts$  - field: new_text    operator: contains    pattern: any---
Warning message

Event types:

  • bash - Bash commands
  • file - File edits
  • stop - Completion checks
  • prompt - User input
  • all - All events

Field options:

  • Bash: command
  • File: file_path, new_text, old_text, content
  • Prompt: user_prompt

Operators:

  • regex_match, contains, equals, not_contains, starts_with, ends_with

來源與署名

來源:anthropics/claude-plugins-official位於plugins/hookify/skills/writing-rules提交b78ac49

授權條款: 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

在 README 中新增徽章

向讀者展示該技能已收錄於 SourceWeft,徽章連結到本頁。

「Listed on SourceWeft」徽章預覽
[![Listed on SourceWeft](https://sourceweft.com/badge/skills/gh-anthropics-claude-plugins-official-writing-hookify-rules.svg)](https://sourceweft.com/skills/gh-anthropics-claude-plugins-official-writing-hookify-rules?utm_source=readme&utm_medium=badge)

檢舉或申請下架