К основному содержанию
скилл CX Codex

hook-development · josiahsiegel — скилл для Claude Code: хуки и установка

Скилл hook-development помогает создавать и настраивать хуки Claude Code: от проверок перед вызовом инструмента до запуска тестов после изменений. Пригодится и для поиска причин, почему хук не срабатывает.

MIT 112 установок ★ 66 обновлён 2026-06-18

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill hook-development -a claude-code
Открыть на GitHub

Что делает hook-development

Скилл описывает события хуков, фильтры по инструментам и два способа выполнения: промпт с решением на основе контекста или команду оболочки для проверок с предсказуемым результатом. С его помощью можно настроить проверку записи файлов, автозапуск тестов после изменений и проверку завершения задачи.

Внутри есть схемы для hooks/hooks.json и .claude/settings.json, примеры входных и выходных данных, переменных окружения и защитных проверок. Форматы конфигурации различаются: в hooks.json события лежат внутри поля hooks, а в настройках пользователя — на верхнем уровне.

Хуки загружаются при старте сессии, поэтому после изменения конфигурации Claude Code нужно перезапустить. Совпавшие хуки запускаются параллельно, а не по очереди.

Какие задачи решает

  • создать хук для проверки вызова инструмента
  • запускать тесты после изменения файлов
  • блокировать запись в чувствительные пути
  • ограничить срабатывание хуков выбранными инструментами
  • найти причину, по которой хук не запускается

Примеры запросов агенту

  • Настрой хук PreToolUse, который проверяет запись файлов и запрещает небезопасные пути.
  • Добавь PostToolUse для Write|Edit, чтобы после изменений запускалась команда тестов.
  • Объясни, почему мой хук не срабатывает, и проверь настройки в hooks/hooks.json.

Как установить hook-development

1Через Skills CLI (Vercel)

npx skills add JosiahSiegel/claude-plugin-marketplace --skill hook-development -a claude-code

2Вручную: положить файлы

~/.claude/skills/hook-development/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/hook-development/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о hook-development

Как установить hook-development в Claude Code?

Выполни npx skills add JosiahSiegel/claude-plugin-marketplace --skill hook-development -a claude-code. Файл скилла появится по пути ~/.claude/skills/hook-development/SKILL.md.

Что делает скилл hook-development?

Он помогает проектировать хуки Claude Code: выбирать событие и фильтр, задавать проверки через промпт или команду и разбирать формат входных и выходных данных.

Что происходит после изменения конфигурации хука?

Изменения подхватятся после перезапуска Claude Code, поскольку хуки загружаются при старте сессии. Хуки, которые подходят под фильтры, запускаются параллельно.

Исходный текст

SKILL.md · MIT
---
name: hook-development
description: |
  Canonical guide to authoring Claude Code hooks, both prompt-based and command-based.
  PROACTIVELY activate for: (1) creating a hook, (2) adding PreToolUse or PostToolUse hooks, (3) validating tool use, (4) implementing prompt-based hooks, (5) blocking dangerous commands, (6) event-driven automation, (7) configuring hooks.json, (8) using ${CLAUDE_PLUGIN_ROOT}, (9) hook matchers and filtering, (10) debugging hooks that do not fire.
  Provides: hooks.json schema, event reference, security guidance, and examples.
---

# Hook Development for Claude Code Plugins

## Overview

Hooks are event-driven automation that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, load context, and integrate external tools.

**Two hook types:**
- **Prompt-based** (recommended): LLM-driven, context-aware decisions
- **Command-based**: Shell commands for fast, deterministic checks

## Hook Events Reference

| Event | When | Common Use |
|-------|------|------------|
| PreToolUse | Before tool executes | Validate, approve/deny, modify input |
| PostToolUse | After tool completes | Test, lint, log, provide feedback |
| Stop | Main agent stopping | Verify task completeness |
| SubagentStop | Subagent stopping | Validate subagent work |
| UserPromptSubmit | User sends prompt | Add context, validate, preprocess |
| SessionStart | Session begins | Load context, set environment |
| SessionEnd | Session ends | Cleanup, logging |
| PreCompact | Before context compaction | Preserve critical information |
| Notification | Notification shown | Custom alert reactions |

## Configuration Formats

### Plugin hooks.json (in `hooks/hooks.json`)

**Uses wrapper format with `hooks` field:**

```json
{
  "description": "What these hooks do (optional)",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
```

### User settings format (in `.claude/settings.json`)

**Direct format, no wrapper:**

```json
{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [{ "type": "command", "command": "script.sh" }]
    }
  ]
}
```

**Critical difference:** Plugin hooks.json wraps events inside `{"hooks": {...}}`. Settings format puts events at top level.

## Prompt-Based Hooks (Recommended)

Use LLM reasoning for context-aware decisions:

```json
{
  "type": "prompt",
  "prompt": "Evaluate if this tool use is appropriate. Check for: system paths, credentials, path traversal. Return 'approve' or 'deny'.",
  "timeout": 30
}
```

**Supported events:** PreToolUse, PostToolUse, Stop, SubagentStop, UserPromptSubmit

**Benefits:** Context-aware, flexible, better edge case handling, easier to maintain.

## Command Hooks

Execute shell commands for deterministic checks:

```json
{
  "type": "command",
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
  "timeout": 60
}
```

**Always use `${CLAUDE_PLUGIN_ROOT}` for portable paths.**

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success (stdout shown in transcript) |
| 2 | Blocking error (stderr fed back to Claude) |
| Other | Non-blocking error |

## Matchers

Control which tools trigger hooks:

```json
"matcher": "Write"              // Exact match
"matcher": "Write|Edit|Bash"    // Multiple tools
"matcher": "mcp__.*__delete.*"  // Regex (all MCP delete tools)
"matcher": "*"                  // All tools (use sparingly)
```

Matchers are case-sensitive.

## Hook Input/Output

### Input (all hooks receive via stdin)

```json
{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.txt",
  "cwd": "/current/working/dir",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": { "file_path": "/path/to/file" }
}
```

Event-specific fields: `tool_name`, `tool_input`, `tool_result`, `user_prompt`, `reason`

Access in prompts: `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`

### Output

**Standard (all hooks):**
```json
{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "Message for Claude"
}
```

**PreToolUse decisions:**
```json
{
  "hookSpecificOutput": {
    "permissionDecision": "allow|deny|ask",
    "updatedInput": { "field": "modified_value" }
  }
}
```

**Stop/SubagentStop decisions:**
```json
{
  "decision": "approve|block",
  "reason": "Explanation"
}
```

## Environment Variables

| Variable | Available | Purpose |
|----------|-----------|---------|
| `$CLAUDE_PLUGIN_ROOT` | All hooks | Plugin directory (portable paths) |
| `$CLAUDE_PROJECT_DIR` | All hooks | Project root path |
| `$CLAUDE_ENV_FILE` | SessionStart only | Persist env vars for session |

**SessionStart can persist variables:**
```bash
echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
```

## Common Patterns

### Validate file writes (PreToolUse)

```json
{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "prompt",
      "prompt": "Check if this file write is safe. Deny writes to: .env, credentials, system paths, or files with path traversal (..). Return 'approve' or 'deny' with reason."
    }]
  }]
}
```

### Auto-test after changes (PostToolUse)

```json
{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "npm test -- --bail",
      "timeout": 60
    }]
  }]
}
```

### Verify task completion (Stop)

```json
{
  "Stop": [{
    "matcher": "*",
    "hooks": [{
      "type": "prompt",
      "prompt": "Verify: tests run, build succeeded, all questions answered. Return 'approve' to stop or 'block' with reason to continue."
    }]
  }]
}
```

### Load project context (SessionStart)

```json
{
  "SessionStart": [{
    "matcher": "*",
    "hooks": [{
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh",
      "timeout": 10
    }]
  }]
}
```

## Security Best Practices

### In command hook scripts:

```bash
#!/bin/bash
set -euo pipefail

input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')

# Always validate inputs
if [[ ! "$file_path" =~ ^[a-zA-Z0-9_./-]+$ ]]; then
  echo '{"decision": "deny", "reason": "Invalid path"}' >&2
  exit 2
fi

# Block path traversal
if [[ "$file_path" == *".."* ]]; then
  echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2
  exit 2
fi

# Block sensitive files
if [[ "$file_path" == *".env"* ]]; then
  echo '{"decision": "deny", "reason": "Sensitive file"}' >&2
  exit 2
fi

# Always quote variables
echo "$file_path"
```

## Lifecycle and Limitations

**Hooks load at session start.** Changes to hook configuration require restarting Claude Code.

- Editing `hooks/hooks.json` won't affect the current session
- Adding new hook scripts won't be recognized until restart
- All matching hooks run **in parallel** (not sequentially)
- Hooks don't see each other's output - design for independence

**To test changes:** Exit Claude Code, restart with `claude` or `claude --debug`.

## Debugging

```bash
# Enable debug mode to see hook execution
claude --debug

# Test hook scripts directly
echo '{"tool_name": "Write", "tool_input": {"file_path": "/test"}}' | \
  bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh

# Validate hook JSON output
output=$(./hook-script.sh < test-input.json)
echo "$output" | jq .

# View loaded hooks in session
# Use /hooks command
```

## Validation Checklist

- [ ] hooks.json uses correct format (plugin wrapper or settings direct)
- [ ] All script paths use `${CLAUDE_PLUGIN_ROOT}` (no hardcoded paths)
- [ ] Scripts are executable and handle errors (`set -euo pipefail`)
- [ ] Scripts validate all inputs and quote all variables
- [ ] Matchers are specific (avoid `*` unless necessary)
- [ ] Timeouts are set appropriately (default: command 60s, prompt 30s)
- [ ] Hook output is valid JSON
- [ ] Tested with `claude --debug`

© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →

Сначала — hook-development от других авторов.

hook-development официальный Anthropic Скилл hook-development помогает создавать хуки для плагинов Claude Code: от перехвата опасных команд до проверки сборки перед завершением задачи. CX Codex +1 7 028установок doubt-driven-development addyosmani Скилл doubt-driven-development отправляет нетривиальные решения на проверку свежему ревьюеру, который ищет слабые места. Пригодится перед сложными изменениями, когда ошибку трудно исправить позже. CX Codex +1 72 600установок backend-development-feature-development sickn33 Скилл backend-development-feature-development для Claude Code ведёт разработку функции от требований и архитектуры до реализации, тестирования и выката. Координирует изменения между сервисами и командами. CX Codex +1 2установок constraint-driven-development addyosmani Скилл constraint-driven-development превращает размытые представления о качестве в письменный контракт проекта. Опрашивает вас, какие метрики важны, и записывает всё в CONSTRAINTS.md с числами, которые можно проверять автоматически. CX Codex +1 49 100установок wp-plugin-development WordPress Скилл wp-plugin-development для Claude Code, Codex, Cursor и других платформ: архитектура плагинов, хуки, настройки через Settings API, безопасность и упаковка релиза. CX Codex +1 9 300установок unix-goto-development manutej Скилл unix-goto-development помогает добавлять функции в навигационную утилиту unix-goto по девятишаговому процессу, с тестами на 100% покрытия и кэшем быстрее 100 мс. CX Codex +1 428установок iterative-development alinaqi Скилл iterative-development для Claude Code запускает тесты после каждого ответа и возвращает ошибки модели, продолжая TDD-цикл до успешных проверок. CX Codex +1 286установок

Из того же набора96

Весь набор →
viral-video-long-form Скилл viral-video-long-form для Claude Code помогает планировать длинные YouTube-видео и улучшать их SEO, удержание аудитории и обложки. Активируется для стратегии канала, структуры ролика и разбора аналитики. CX Codex +1 114установок power-query-m Помогает писать Power Query M, разбирать query folding и собирать ETL-преобразования. Охватывает запросы, параметры и коннекторы. CX Codex +1 114установок adf-ml-analytics Скилл adf-ml-analytics для Claude Code содержит рецепты batch-скоринга Azure ML, запуска Databricks и архивации SQL в Storage через Azure Data Factory. Для новых пайплайнов предлагает batch-эндпоинты SDK v2 вместо SDK v1. CX Codex +1 113установок ffmpeg-filter-complex-patterns Скилл ffmpeg-filter-complex-patterns для Claude Code объясняет синтаксис сложных фильтров FFmpeg. Он подключается к вопросам о композиции видео, переходах, аудиомикшировании и маршрутизации потоков. CX Codex +1 112установок ffmpeg-video-analysis Скилл ffmpeg-video-analysis для Claude Code анализирует видео через фильтры FFmpeg и помогает искать дефекты и оценивать качество. Включается для проверки чёрных и замороженных кадров, размытости, склеек и кадрирования. CX Codex +1 111установок viral-video-platform-specs Скилл viral-video-platform-specs для Claude Code подбирает параметры экспорта видео для соцсетей. Запускается при поиске требований платформы, конвертации кадра или подготовке ролика к загрузке. CX Codex +1 108установок ffmpeg-glitch-distortion-effects Скилл ffmpeg-glitch-distortion-effects для Claude Code подсказывает фильтры FFmpeg для глитч-эффектов и искажений видео. Активируется для датамоша, VHS-симуляции, цветовых сдвигов и пикселизации. CX Codex +1 107установок ffmpeg-opencv-integration Скилл ffmpeg-opencv-integration для Claude Code и Codex помогает связать FFmpeg и OpenCV в Python-скриптах. Защищает от путаницы в RGB/BGR, сбоев с пайпами и потери звука при обработке кадров. CX Codex +1 107установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой