# Creating Claude Hooks

Use when creating or publishing Claude Code hooks - covers executable format, event...

- Repository: https://github.com/AgentWorkforce/relay (1088 stars)
- Category: Security
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AgentWorkforce/relay --skill creating-claude-hooks -g -a claude-code -y`
Codex: `npx skills add AgentWorkforce/relay --skill creating-claude-hooks -g -a codex -y`
Cursor: `npx skills add AgentWorkforce/relay --skill creating-claude-hooks -g -a cursor -y`
Gemini CLI: `npx skills add AgentWorkforce/relay --skill creating-claude-hooks -g -a gemini-cli -y`

## Description

Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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         |

### Available Events

| Event                | When It Fires               | Common Use Cases                         |
| -------------------- | --------------------------- | ---------------------------------------- |
| `session-start`      | New session begins          | Environment setup, logging, checks       |
| `user-prompt-submit` | Before user input processes | Validation, enhancement, filtering       |
| `tool-call`          | Before tool execution       | Permission checks, logging, modification |
| `assistant-response` | After assistant responds    | Formatting, logging, cleanup             |

## Hook Format Requirements

### File Location

**Project hooks:**

```
.claude/hooks/session-start
.claude/hooks/user-prompt-submit
```

**User-global hooks:**

The rest: https://github.com/AgentWorkforce/relay/blob/HEAD/.claude/skills/creating-claude-hooks-skill/SKILL.md