| name | hook-updater |
| description | Research-backed hook refresh workflow for updating existing hooks with TDD checkpoints and settings.json registration validation. |
| version | 1.0.0 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Write","Edit","Glob","Grep","Bash","Skill","MemoryRecord"] |
| args | --hook <name-or-path> [--trigger reflection|evolve|manual|stale] [--mode plan|execute] |
| error_handling | graceful |
| streaming | supported |
| verified | true |
| lastVerifiedAt | 2026-04-07 |
| dependencies | ["research-synthesis"] |
| category | framework-management |
| tags | ["hooks","updater","maintenance","framework"] |
| aliases | ["update-hook","refresh-hook"] |
| source | builtin |
| trust_score | 100 |
| provenance_sha | 88c33a7109c17122 |
Hook Updater
Overview
Use this skill to refresh an existing hook safely: research current best practices, compare against current implementation, generate a TDD patch backlog, apply updates, and verify ecosystem integration including settings.json registration.
When to Use
- Reflection flags stale or malfunctioning hook behavior
- EVOLVE determines hook capability exists but quality is outdated
- User asks to audit/refresh an existing hook
- Hook exit code or stdin protocol issues detected
The Iron Law
Never update a hook blindly. Every refresh must be evidence-backed, TDD-gated, and integration-validated.
Workflow
Step 0: Evaluate Current State
- Read the hook file and understand its purpose
- Check settings.json registration (which events, which matchers)
- Run existing tests if they exist
- Identify issues: wrong API pattern, missing registration, broken requires
Step 1: Research Best Practices
- Read
.claude/hooks/CLAUDE.md for hook conventions
- Review similar hooks in the same category for patterns
- Check
.claude/rules/hooks.md for hook rules
- Use
Skill({ skill: 'research-synthesis' }) if external research needed
Step 2: Generate Patch Backlog
- List specific changes needed (TDD-style: test first, then implement)
- Prioritize by risk: registration fixes > exit code fixes > logic improvements
- Estimate scope: <30 lines = auto-apply, >30 lines = plan mode
Step 3: Apply Updates
- Write or update tests first (RED phase)
- Apply hook changes (GREEN phase)
- Refactor for clarity (REFACTOR phase)
- Use
Edit tool — never rewrite the entire file
Step 4: Verify Integration
- Confirm hook is registered in
.claude/settings.json for correct events
- Verify hook exit codes: 0=allow, 2=block, 1=error (SE-03)
- Verify stdin JSON parsing follows the standard protocol
- Run
pnpm lint:fix && pnpm format
- Run hook-specific tests
Step 5: Record
- Log changes via
MemoryRecord if significant
- Update CHANGELOG.md entry
Domain-Specific Validation
- Hook MUST be registered in settings.json under appropriate event
