hook-engineering

Designs and repairs Claude Code hooks using the nested matcher-entry schema and five handler types.

Updated Jun 28, 2026
One-click install
npx skills add https://github.com/JaviMontano/claude-plugins --skill hook-engineering-javimontano
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: hook-engineering
Source: https://github.com/JaviMontano/claude-plugins/tree/main/plugins/claude-native-toolkit/skills/hook-engineering
Command: npx skills add https://github.com/JaviMontano/claude-plugins --skill hook-engineering-javimontano

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve? Claude Code hook configurations fail silently when written with the legacy flat schema, wrong event names, or handler types that an event does not support. This Skill designs and repairs hooks so they run deterministically at lifecycle events without relying on the model to remember a rule. ## Core Features & Use Cases - Schema-correct hook design: Emits the nested matcher-entry structure (event key → matcher entries → inner hooks array) with current case-sensitive event names and one of the five handler types: command, http, mcp_tool, prompt, or agent. - Policy-aware boundaries: Keeps permission rules as the baseline authority; hooks can tighten with deny decisions but never bypass settings or managed deny rules. - Portability and validation: Uses ${CLAUDE_PROJECT_DIR} and ${CLAUDE_PLUGIN_ROOT} placeholders, documents MCP connection timing, and validates with the bundled policy and validate_hooks.py. - Use Case: Block Write/Edit under a protected client directory with a PreToolUse command hook, guard a slash command with UserPromptExpansion, and send PostToolUse audit events to an MCP server, all in one validated configuration. ## Quick Start Ask the assistant to design a PreToolUse hook that blocks writes to a protected path using the current Claude Code hook schema.

Frequently Asked Questions about hook-engineering

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a PreToolUse hook in Claude Code?▼

Use the nested matcher-entry schema: the event key maps to an array of matcher entries, each with an inner hooks array of handler objects. A command handler with a portable script path is the recommended default for deterministic policy.

What is the difference between matcher and if in Claude Code hooks?▼

Matcher belongs to the matcher entry and filters by event-specific fields like tool name or command name. If is a single permission-rule string on an individual handler and is evaluated only on tool-filtered events such as PreToolUse and PostToolUse.

Which events support prompt and agent hooks in Claude Code?▼

The conservative rule restricts prompt and agent handlers to the three ToolUseContext events: PreToolUse, PostToolUse, and PermissionRequest. Using them elsewhere can fail silently, so prefer command or http handlers on other events.

Can a Claude Code hook override deny rules from settings?▼

No. Permission rules remain the baseline authority boundary. A PreToolUse hook can tighten policy by returning a deny decision, but a hook allow decision never bypasses project or managed deny rules.

Why does my mcp_tool hook fail at SessionStart?▼

mcp_tool handlers call tools on already-connected MCP servers, and hooks do not trigger OAuth or connection setup. SessionStart can race the MCP connection, so use later events or make failures non-blocking and explicit.

How do I make hook scripts portable across cloned repos?▼

Replace absolute local paths with ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT}, or ${CLAUDE_PLUGIN_DATA} placeholders. Use exec form with an args array when path placeholders or shell quoting matter, and verify scripts are executable.