Agent Skills: Hook Manager

Hook Manager

Manages Claude Code lifecycle hook configurations. Hooks are shell commands that execute automatically at specific points in the Claude Code lifecycle, providing deterministic control over formatting, logging, blocking, and notifications.

Activation

This skill activates when:

• User invokes /aida hook list
• User invokes /aida hook add
• User invokes /aida hook remove
• User invokes /aida hook validate
• Hook management is needed

Operations

List Hooks

Show all configured hooks across settings files.

python {base_directory}/scripts/manage.py --execute \
  --context='{"operation": "list", "scope": "all"}'

Scopes:

• user -- User-level hooks only
• project -- Project-level hooks only
• local -- Local overrides only
• all -- All hooks (default)

Add Hook

Add a new hook using the two-phase API.

Phase 1: Gather Context

python {base_directory}/scripts/manage.py \
  --get-questions \
  --context='{"operation": "add", "description": "..."}'

Returns questions about event type, scope, and whether to use a built-in template.

Phase 2: Execute

python {base_directory}/scripts/manage.py --execute \
  --context='{"operation": "add", "event": "PostToolUse", "matcher": "Write|Edit", "command": "prettier --write", "scope": "project"}'

Built-in templates:

| Template | Event | Purpose | | --- | --- | --- | | formatter | PostToolUse | Auto-format after writes | | logger | PostToolUse | Log commands for audit | | blocker | PreToolUse | Block sensitive file writes | | notifier | Notification | Desktop notifications |

Remove Hook

Remove a hook by event and matcher.

python {base_directory}/scripts/manage.py --execute \
  --context='{"operation": "remove", "event": "PostToolUse", "matcher": "Write|Edit", "scope": "project"}'

Validate Hooks

Validate hook configurations for correctness.

python {base_directory}/scripts/manage.py --execute \
  --context='{"operation": "validate", "scope": "all"}'

Checks:

• Hook structure (required fields)
• Event names are valid
• Commands are safe (warns about dangerous patterns)

Two-Phase API

Phase 1: get_questions(context)

Analyzes the operation context and returns:

• questions: List of questions needing user input
• inferred: Values inferred from the description

Phase 2: execute(context, responses)

Executes the operation with user responses and returns:

• success: Whether the operation succeeded
• message: Human-readable result message
• Operation-specific data (hooks list, added hook, etc.)

Hook Configuration Locations

| Scope | Path | Use Case | | --- | --- | --- | | user | ~/.claude/settings.json | Personal hooks | | project | .claude/settings.json | Shared team hooks | | local | .claude/settings.local.json | Local overrides |

Path Resolution

Script entry point:

{base_directory}/scripts/manage.py

Reference docs:

{base_directory}/references/hooks-reference.md

Resources

Scripts

| Script | Purpose | | --- | --- | | scripts/manage.py | Two-phase API entry point | | scripts/_paths.py | Path setup for shared utils | | scripts/operations/hooks.py | Hook operations |