# Hook Design

> Design PreToolUse/PostToolUse hooks for standards enforcement

- Skill: `sethdford/hook-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sethdford/hook-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sethdford/hook-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sethdford (https://skillmd.com/u/sethdford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sethdford/hook-design

---


# Hook Design Skill

Integrate standards enforcement into your development workflow via hooks that trigger at specific events.

## Context

Hooks are event handlers that run at key moments in the development cycle. PreToolUse hooks run before you execute a tool (write a file, run a command). PostToolUse hooks run after. This skill teaches you to design hooks that provide real-time standards feedback without being intrusive.

## Domain Context

Hooks in claude-standards can be:

1. **Command hooks** — Shell scripts that run and report output
2. **Prompt hooks** — LLM evaluation with yes/no decisions
3. **Agent hooks** — Multi-turn verification with tool access

The most useful enforcement hooks are Agent hooks that run the Standards Enforcer against changed files.

Reference: `levels/L3-enforcement/hooks/` and CLAUDE.md hook documentation

## Instructions

1. **Identify which tool events matter** — What triggers should fire enforcement?
   - **PreToolUse on Edit/Write** — Before file changes saved
   - **PostToolUse on Edit/Write** — After file changes saved
   - **PreToolUse on Bash** — Before running shell commands
   - **PostToolUse on Bash** — After running commands
   - Think about: Which events represent "code work"? When is feedback most useful?
   - Deliverable: List of tool events to hook

2. **Choose hook type** — Command, prompt, or agent?
   - **Command hook:** Simple, fast, no context needed (e.g., run linter)
   - **Prompt hook:** Decision-making, yes/no answer (e.g., "Does this look right?")
   - **Agent hook:** Complex analysis, tool access (e.g., run Standards Enforcer)
   - For standards enforcement, Agent hooks are usually best
   - Deliverable: Hook type decision + justification

3. **Write hook configuration** — Define the hook in JSON or YAML
   - Event: PreToolUse or PostToolUse
   - Tool matcher: Edit, Write, Bash, etc.
   - Hook type: command, prompt, or agent
   - If agent: reference the Standards Enforcer agent
   - If command: shell script to run
   - Deliverable: Hook configuration file

4. **Design trigger logic** — When should hook actually fire?
   - Should it fire on every file change? (Can be too noisy)
   - Should it fire only on certain file patterns? (More focused)
   - Should it fire before or after change? (Before = prevention, after = detection)
   - Consider: Performance impact, signal-to-noise ratio
   - Deliverable: Hook trigger rules

5. **Test with examples** — Verify hook works as designed
   - Scenario 1: Compliant code → Hook should pass silently
   - Scenario 2: Code with WARNING → Hook should report and allow
   - Scenario 3: Code with ERROR → Hook should report and ask for confirmation
   - Run test scenarios
   - Deliverable: Test results showing hook works

6. **Define escalation** — What happens if hook finds violations?
   - Can user ignore (INFO level)? Yes
   - Can user override (WARN level)? With confirmation
   - Can user skip (ERROR level)? No, blocked
   - Document the user experience
   - Deliverable: Escalation policy document

## Anti-Patterns

1. **Hooks that fire on every operation** — Productivity killer
   - Wrong: Hook on every Bash command (including cd, ls, etc.)
   - Right: Hook only on tool use that matters (Edit, Write, specific commands)
   - Impact: Hook fires 100x per session → user disables it
   - Guard: Test hook on realistic workflow; should fire <5 times per session

2. **Hooks generating false positives** — Creates distrust
   - Happens when: Standard rules are ambiguous or agent misunderstands
   - Example: Hook reports "unknown type found" for valid `unknown` type
   - Impact: User learns to ignore hook warnings
   - Guard: Test hook on many real code examples before deploying

3. **Enforcement without standards to back it up** — Rules seem arbitrary
   - Wrong: Hook enforces "max function length 30 lines" but no standard documents this
   - Right: Hook enforces rule from docs/standards/engineering/code-quality.md
   - Impact: User can't understand why hook is blocking them
   - Guard: Every hook check must cite a standard; user can read it

4. **Hooks that slow down development** — Performance regression
   - Happens when: Agent hook makes expensive analysis calls
   - Example: Hook runs full enforcement agent on every keystroke
   - Impact: Development becomes noticeably slower
   - Guard: Test hook performance on large code files; should complete <2 seconds

## Further Reading

- `levels/L3-enforcement/hooks/` — Reference hook configurations
- `levels/L3-enforcement/agents/standards-enforcer.md` — Enforcement agent to use with hooks
- CLAUDE.md section on hooks — Hook configuration format and options