Creating Claude Hooks

This is your reference for building executable hooks that tap into Claude Code's event system. It covers the four main events (session start, prompt submit, tool call, assistant response), shows you how to handle JSON input from stdin and use exit codes to block operations, and walks through the PRPM package structure if you want to publish. The format requirements are specific: you need shebangs, executable permissions, and proper quoting around variables. Most useful when you're actually writing a hook and need to remember whether blocking is exit 2 or when to use stderr vs stdout. The examples are practical, showing real validation and logging patterns in both bash and TypeScript.

GitHub stars: 719
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add agentworkforce/relay --skill creating-claude-hooks --agent claude-code

Installs into .claude/skills of the current project.

Files

Creating Claude Code Hooks

Use this skill when creating, improving, or publishing Claude Code hooks. Provides essential guidance on hook format, event handling, I/O conventions, and package structure.

When to Use This Skill

Activate this skill when:

User asks to create a new Claude Code hook
User wants to publish a hook as a PRPM package
User needs to understand hook format or events
User is troubleshooting hook execution
User asks about hook vs skill vs command differences

Quick Reference

Hook File Format

Aspect	Requirement
Location	`.claude/hooks/<event-name>`
Format	Executable file (shell, TypeScript, Python, etc.)
Permissions	Must be executable (`chmod +x`)
Shebang	Required (`#!/bin/bash` or `#!/usr/bin/env node`)
Input	JSON via stdin
Output	Text via stdout (shown to user)
Exit Codes	`0` = success, `2` = block, other = error