hooks-manager

name	hooks-manager
description	Manage Claude Code hooks for workflow automation. Create, configure, test, and debug hooks that execute at various lifecycle points. Supports all hook events (PreToolUse, PostToolUse, SessionStart, etc.) with examples and best practices.
version	1.0.0

Hooks Manager

Manage Claude Code hooks for deterministic workflow automation.

When to Use

• Creating or modifying hooks for workflow automation
• Testing hook configurations before deployment
• Debugging hook execution issues
• Understanding hook event types and matchers
• Implementing security-aware hook patterns
• Managing project or user-level hook configurations

What This Skill Does

Guides you through Claude Code hook management:

• Hook Creation: Generate hook configurations with proper syntax
• Event Types: Understand all 9 hook events and when they trigger
• Security: Implement hooks with proper security considerations
• Testing: Validate hooks before deployment
• Examples: Access common hook patterns and implementations
• Debugging: Troubleshoot hook execution issues

🎯 Core Principle: Hook Lifecycle

Hooks execute at 9 lifecycle points:

Event	Timing	Can Block? (Exit 2)
PreToolUse	Before tool execution	✅ Yes (blocks tool)
PostToolUse	After tool completion	⚠️ Partial (tool already ran, feeds stderr to Claude)
UserPromptSubmit	Before AI processing	✅ Yes (erases prompt)
SessionStart	Session begins/resumes	❌ No
SessionEnd	Session terminates	❌ No
Stop	Claude finishes responding	✅ Yes (blocks stoppage)
SubagentStop	Subagent completes	✅ Yes (blocks stoppage)
PreCompact	Before memory compaction	✅ Yes (blocks compaction)
Notification	Claude sends notification	❌ No

Exit Codes:

• 0: Success (stdout visible in transcript mode)
• 2: Blocking error (stderr fed to Claude or shown to user)
• Other: Non-blocking error (stderr shown to user)

→ Complete Event Types Reference - Detailed documentation with examples

Plugin Hooks Configuration

PRISM uses plugin-level hooks configured in hooks/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/my-hook.py"
          }
        ]
      }
    ]
  }
}

Critical: Use ${CLAUDE_PLUGIN_ROOT} for all plugin paths (not relative paths)

→ Complete Configuration Reference for full schema

Quick Start

Create Your First Hook (Recommended)

1. Read the event table above (30 seconds)
2. Browse examples: *hook-examples (2 min)
3. Create hook: *create-hook (guided setup)
4. Test hook: *test-hook [name] (validation)

Result: A working hook following best practices

Quick Lookup (While Building)

Need a command or pattern right now?

→ Commands Reference - All 15 commands with examples → Examples Library - 13 pre-built hook patterns

Learn Hook System (Deep Dive)

Want to understand hook architecture?

→ Event Types Reference - Complete event documentation → Security Best Practices - Hook security guide

Available Commands

Category	Commands
Management	list-hooks, create-hook, edit-hook {name}, delete-hook {name}, enable-hook {name}, disable-hook {name}
Testing	test-hook {name}, debug-hook {name}, validate-config
Examples	hook-examples, event-types, install-example {name}
Sharing	export-hooks, import-hooks {file}

→ Full Command Reference for detailed usage

Hook Examples Library

Quick access to 13 pre-built patterns:

• Logging: bash-command-logger, file-change-tracker, workflow-auditor
• Safety: file-protection, git-safety, syntax-validator
• Automation: auto-formatter, auto-tester, auto-commit
• Notifications: desktop-alerts, slack-integration, completion-notifier
• PRISM: story-context-enforcer

→ Complete Examples with full implementations

Integration with PRISM

The hooks-manager skill enables automation for:

• Workflow Validation: Enforce story context in core-development-cycle
• Quality Gates: Auto-run tests and validation
• PSP Tracking: Auto-update timestamps and metrics
• Skill Integration: Hook into any PRISM skill command

Current PRISM Hooks:

• enforce-story-context - Block workflow commands without active story
• track-current-story - Capture story file from *draft command
• validate-story-updates - Ensure required sections exist
• validate-required-sections - Status-based section validation

Available Reference Files

All detailed content lives in reference files (progressive disclosure):

• Commands Reference (~4.5k tokens) - Complete command documentation
• Event Types (~4.6k tokens) - All 9 events with examples
• Examples Library (~4.2k tokens) - 13 pre-built patterns
• Security Guide - Security checklist and best practices

Common Questions

Q: Where do I start? A: Run *hook-examples to browse patterns, then *create-hook for guided setup

Q: Which event should I use? A: See Event Types Reference for complete guide

Q: Can I see working examples? A: Yes! Run *hook-examples or see Examples Library

Q: How do I test before deployment? A: Use *test-hook [name] to validate with sample input

Q: How do I share hooks with my team? A: Use *export-hooks and commit to .claude/settings.json

Triggers

This skill activates when you mention:

• "create a hook" or "manage hooks"
• "hook automation" or "workflow hooks"
• "PreToolUse" or "PostToolUse" (event names)
• "test hook" or "debug hook"

---

Need help? Use *hook-examples to browse patterns or *create-hook for guided setup.