Claude Code hooks are shell commands that run automatically when specific events occur: before a tool executes, after a tool completes, when Claude stops generating, or when a subagent finishes. Skills are invokable specifications with process steps and output contracts. The two layers are not alternatives. They are infrastructure and procedure, and they solve different problems.

Most developers building Claude Code workflows start with skills and eventually hit a class of problem that skills cannot solve by themselves: enforcing that something happened, not just that Claude was told it should happen. That is where hooks enter the architecture. At Agent Engineer Master, the combination of well-built skills with targeted hooks appears in roughly 30% of production commissions, and always for the same reason: the workflow has consequences that matter and steps that must not be skipped (source: AEM commission data, 2026).

TL;DR: Hooks run shell commands in response to Claude Code events, independent of skill instructions. Skills define what Claude does procedurally. Hooks enforce what happens at the infrastructure level. Together, they create workflows where the instructions are reliable and the enforcement is mechanical.

What are Claude Code hooks?

A Claude Code hook is a shell command configured to execute automatically when a named event fires. Five event types are available: PreToolUse, PostToolUse, Stop, SubagentStop, and Notification. Each maps to a distinct point in Claude's execution loop, from before a tool call fires to after a subagent session ends. Each event type serves a different control purpose:

  • PreToolUse: Before Claude calls any tool (Read, Write, Bash, etc.). Use to validate input, block dangerous calls, or log intent.
  • PostToolUse: After a tool call completes. Use to audit output, trigger side effects, or update external state.
  • Stop: When Claude finishes generating its response. Use to run final validation, send notifications, or update task tracking.
  • SubagentStop: When a spawned subagent finishes. Use to process subagent output before it reaches the parent.
  • Notification: When Claude Code triggers a user notification. Use to route alerts to external systems.

Hooks are configured in settings.json (user or project level). Each hook specifies the event name, the shell command to run, and a configurable timeout: the default is 60 seconds, after which the hook is cancelled and Claude continues. The hook has no visibility into what Claude is doing semantically. It sees the event and runs the command (source: Claude Code documentation, 2026).

A hook's output cannot directly change Claude's behavior mid-response. It can block tool execution (by exiting with a non-zero status code in a PreToolUse hook), log to files, call external APIs, or update files that Claude will read in subsequent steps. This enforcement layer is increasingly important: Gartner projects that over 40% of agentic AI projects will be canceled by end of 2027, with inadequate risk controls cited as a primary cause (source: Gartner, June 2025).

What are Claude Code skills, and what layer do they occupy?

A Claude Code skill is a SKILL.md file containing numbered process steps that Claude follows in sequence. The skill operates at the content layer: it determines what Claude does, in what order, and what it produces. Skills cannot directly detect tool calls or respond to events in the way hooks do.

The critical distinction is that skill instructions are suggestions that Claude interprets and executes. Hooks are code that the runtime executes regardless of Claude's interpretation. A skill step that says "log this output to audit.log" instructs Claude to do it. A PostToolUse hook that writes to audit.log does it mechanically, every time, without relying on Claude's interpretation of that instruction.

"The failure mode isn't that the model is bad at the task. It's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." - Simon Willison, creator of Datasette and llm CLI (2024)

For a workflow that is safety-critical or audit-sensitive, that distinction matters. A skill step is specification. A hook is enforcement. Only 21% of organizations have a mature governance model for agentic AI (source: Deloitte, State of AI in the Enterprise, survey of 3,000+ leaders, January 2026). The hook layer is one of the concrete mechanisms that moves a workflow from the 79% to the 21%.

For a full explanation of the skill architecture, see What Is a Claude Code Skill?.

Where do hooks and skills solve different problems?

Skills and hooks are complementary layers that do not overlap in their core function. Skills operate at the content layer: they determine what steps Claude follows, what format it produces, and what constraints apply. Hooks operate at the runtime layer: they fire on events regardless of which skill is active.

Skills solve:

  • What steps to follow and in what order.
  • What output format to produce.
  • When to load reference files.
  • What constraints apply to the output.

Hooks solve:

  • Mechanical enforcement that something happened, independent of Claude's execution.
  • Event-driven side effects: logging, notifications, external API calls.
  • Safety gates: blocking tool calls that match dangerous patterns before execution.
  • State synchronization: updating external systems when Claude's session ends.

A skill can tell Claude to write a log entry. A hook writes the log entry mechanically every time a specific event fires. These are not redundant. A skill that instructs logging relies on Claude following the instruction correctly in every invocation. A hook that writes the log is not subject to interpretation. In our builds at AEM, hooks are added precisely when a step is critical enough that the gap between "Claude was told" and "it happened" is unacceptable (source: AEM internal, 2026). The cost of that gap is measurable: among organizations that experienced AI-related security incidents in 2025, 97% lacked proper AI access controls at the infrastructure layer (source: IBM Cost of a Data Breach Report, 2025).

How can hooks and skills work together?

The patterns that appear in roughly 30% of AEM production commissions combine skills for procedure and hooks for enforcement. Skills define the steps Claude follows and the output format it produces. Hooks ensure that critical actions, logging, and safety boundaries hold regardless of how Claude interprets its instructions. The four patterns below cover the common integration shapes.

  1. PreToolUse validation before skill execution: A PreToolUse hook checks whether a required file exists or whether a precondition is met before Claude calls any Write tool. If the check fails, the hook blocks the tool call with exit code 2. The skill's instructions describe the workflow; the hook prevents incorrect execution before it starts.
  2. PostToolUse logging for compliance workflows: A skill instructs Claude to generate a compliance report and save it. A PostToolUse hook fires after every Write call and appends an entry to a separate audit file with a timestamp and the file path written. The skill defines the output. The hook creates the audit trail.
  3. Stop hook for task completion: A skill executes a code review and outputs a structured report. A Stop hook fires when Claude finishes, reads the report, and sends it to a Slack webhook. The skill defines the work. The hook handles distribution.
  4. Blocking dangerous operations: A PreToolUse hook scans incoming Bash tool calls for patterns like rm -rf or DROP TABLE. If matched, it exits with exit code 2, blocking execution before the command runs. The skill's process steps describe the intended workflow; the hook enforces a safety boundary the skill cannot define for itself.

These patterns are becoming standard practice. McKinsey's 2025 State of AI report found that 23% of organizations are actively scaling agentic AI systems, with most deploying in safety-sensitive functions where enforcement constraints are not optional (source: McKinsey & Company, State of AI 2025, survey of 1,993 respondents).

See What's the Difference Between CLAUDE.md Instructions and SKILL.md Instructions? for how standing rules interact with these two layers.

When should a hook do the work vs a skill step?

The decision comes down to whether you need mechanical enforcement or structured procedure. A hook is the right choice when an action must happen on every matching event, independent of which skill is running. A skill step is the right choice when the action belongs to a specific workflow and depends on Claude's judgment.

Use a hook when:

  • The action must happen every time a specific event fires, regardless of the skill in use.
  • The action is a side effect that does not produce output Claude needs to use.
  • The action involves calling an external system that should not depend on Claude's interpretation.
  • You are implementing a safety boundary that must hold unconditionally.

Use a skill step when:

  • The action is part of a specific workflow and should only happen during that workflow.
  • The action produces output that subsequent steps need.
  • The action involves Claude making a judgment or applying domain knowledge.
  • The action is optional depending on conditions Claude evaluates during execution.

The enforcement layer built by combining skills with hooks is part of what closes the trust gap. Only 6% of companies fully trust AI agents to handle core business processes autonomously (source: Harvard Business Review Analytic Services / Workato, survey of 603 business leaders, July 2025). Mechanical enforcement at the hook layer is one of the structural steps that closes that gap for production workflows.

This pattern does not scale to complex orchestration. For workflows where hooks need to pass structured data back into Claude's context, or where hooks need to modify skill behavior mid-execution, you are approaching the limit of what the hook-plus-skill pattern handles cleanly. Complex orchestration with dynamic control flow belongs in a multi-agent architecture with a parent agent coordinating skill invocations and monitoring results.

See When Should I Use a Subagent Instead of a Skill? for where to escalate past this pattern.

Frequently Asked Questions

Can a hook trigger a skill? Not directly. A hook runs a shell command. It cannot invoke a Claude Code skill or cause Claude to execute a SKILL.md file. A hook can write to a file that Claude reads in its next step, effectively passing information into the skill's execution context, but the skill itself must be active and running for that to have any effect.

Can a skill configure hooks? A skill can write to settings.json if it has permission to do so. This means a skill could technically add or modify hook configurations. This is a pattern requiring explicit user intent and hook-aware session design: hook changes affect every subsequent session, not just the current one. Use it only when you need to install hooks as part of a setup workflow with the user's explicit intent.

What happens if a PreToolUse hook blocks a tool call? Claude receives an error indicating the tool call was blocked. Claude's behavior after a blocked tool call depends on the session context. If the skill has explicit error handling for blocked calls, Claude follows it. If not, Claude may retry, prompt the user for guidance, or halt the workflow.

Do hooks run during skill invocations or only during regular sessions? Hooks run based on events regardless of whether a skill is active. A PostToolUse hook fires after every tool call in every session, not just during skill invocations. If you need hook behavior scoped to specific skills, you must implement that scoping logic inside the hook's shell command. This session-wide coverage is meaningful: 57.4% of teams building agentic systems cite insufficient observability and audit trails as their primary security concern (source: Gravitee, State of AI Agent Security Report, 919 respondents, February 2026). A PostToolUse hook that logs every tool call provides that audit trail mechanically, regardless of which skill is active.

Can skills and hooks conflict with each other? Yes. A skill that instructs Claude to call a tool and a PreToolUse hook that blocks that tool call are in direct conflict. The hook wins, because it operates at the runtime layer below Claude's instruction processing. Designing skills and hooks for the same workflow requires knowing which tools each skill will call and ensuring no hook inadvertently blocks required calls.

Last updated: 2026-05-05