create-hooks

Hooks は、ツールの使用、セッションイベント、ユーザー操作に応じてシェルコマンドまたは LLM プロンプトを実行する、Claude Code のイベント駆動型自動化機能です。このスキルでは、コマンドの検証、ワークフローの自動化、コンテキストの注入、カスタム完了条件の実装に使用する Hooks の作成、設定、デバッグ方法を学びます。

Hooks を使うと、コアコードを変更せずに Claude の動作をプログラムで制御できるため、プロジェクト固有の自動化、安全性チェック、ワークフローのカスタマイズが可能になります。

Hooks は、Claude Code のイベントに応じて実行されるシェルコマンド、または LLM が評価するプロンプトです。イベント階層内で動作し、イベント（PreToolUse、PostToolUse、Stop など）がマッチャー（ツールパターン）をトリガーし、マッチャーが Hooks（コマンドまたはプロンプト）を実行します。Hooks はアクションのブロック、ツール入力の変更、コンテキストの注入、または Claude の操作の監視やログ記録のみを行うことができます。

<quick_start>

1. Hooks の設定ファイルを作成します：
   • プロジェクト：.claude/hooks.json
   • ユーザー：~/.claude/hooks.json
2. Hook イベント（実行されるタイミング）を選択します
3. Hook の種類（コマンドまたはプロンプト）を選択します
4. マッチャー（トリガーとなるツール）を設定します
5. claude --debug でテストします

**すべての bash コマンドを記録する**：

.claude/hooks.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \\\"No description\\\")\"' >> ~/.claude/bash-log.txt"
          }
        ]
      }
    ]
  }
}

この Hook は次の処理を行います：

• すべての Bash ツールの使用前（PreToolUse）に実行されます
• command を実行します（LLM プロンプトではありません）
• コマンドと説明をファイルに記録します

</quick_start>

<hook_types>

イベント	実行されるタイミング	ブロック可能か
PreToolUse	ツールの実行前	はい
PostToolUse	ツールの実行後	いいえ
UserPromptSubmit	ユーザーがプロンプトを送信したとき	はい
Stop	Claude が停止しようとしたとき	はい
SubagentStop	サブエージェントが停止しようとしたとき	はい
SessionStart	セッションの開始時	いいえ
SessionEnd	セッションの終了時	いいえ
PreCompact	コンテキストの圧縮前	はい
Notification	Claude が入力を必要としたとき	いいえ

ブロックする Hooks は "decision": "block" を返して、アクションを阻止できます。詳しい使用例については、references/hook-types.md を参照してください。 </hook_types>

<hook_anatomy> <hook_type name="command"> 種類：シェルコマンドを実行します

用途：

• 簡単な検証（ファイルの存在確認）
• ログ記録（ファイルへの追記）
• 外部ツール（フォーマッター、リンター）
• デスクトップ通知

入力：stdin 経由の JSON 出力：stdout 経由の JSON（任意）

{
  "type": "command",
  "command": "/path/to/script.sh",
  "timeout": 30000
}

</hook_type>

<hook_type name="prompt"> 種類：LLM がプロンプトを評価します

用途：

• 複雑な判断ロジック
• 自然言語による検証
• コンテキストを考慮したチェック
• 推論が必要な場合

入力：$ARGUMENTS プレースホルダーを含むプロンプト 出力：decision と reason を含む JSON

{
  "type": "prompt",
  "prompt": "Evaluate if this command is safe: $ARGUMENTS\n\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
}

</hook_type> </hook_anatomy>

マッチャーは、Hook をトリガーするツールを絞り込みます：

{
  "matcher": "Bash",           // Exact match
  "matcher": "Write|Edit",     // Multiple tools (regex OR)
  "matcher": "mcp__.*",        // All MCP tools
  "matcher": "mcp__memory__.*" // Specific MCP server
}

マッチャーなし：Hook はすべてのツールに対して実行されます

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [...]  // No matcher - fires on every user prompt
      }
    ]
  }
}

<input_output> Hooks は、セッション情報、現在のディレクトリ、イベント固有のデータを含む JSON を stdin 経由で受け取ります。ブロックする Hooks は、アクションを許可またはブロックするため、あるいは入力を変更するための JSON を返すことができます。

出力例（ブロックする Hooks）：

{
  "decision": "approve" | "block",
  "reason": "Why this decision was made"
}

各 Hook の種類に対応する完全なスキーマについては、references/input-output-schemas.md を参照してください。 </input_output>

<environment_variables> Hook コマンドで使用できる環境変数：

変数	値
$CLAUDE_PROJECT_DIR	プロジェクトのルートディレクトリ
${CLAUDE_PLUGIN_ROOT}	プラグインのディレクトリ（プラグインの Hooks のみ）
$ARGUMENTS	Hook 入力の JSON（プロンプト Hooks のみ）

例：

{
  "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.sh"
}

</environment_variables>

<common_patterns> 入力が必要なときにデスクトップ通知を表示する：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

破壊的な git コマンドをブロックする：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if this command is destructive: $ARGUMENTS\n\nBlock if it contains: 'git push --force', 'rm -rf', 'git reset --hard'\n\nReturn: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
          }
        ]
      }
    ]
  }
}

編集後にコードを自動フォーマットする：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_PROJECT_DIR",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

セッション開始時にコンテキストを追加する：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"Current sprint: Sprint 23. Focus: User authentication\"}}'"
          }
        ]
      }
    ]
  }
}

</common_patterns>

Hooks は必ずデバッグフラグを使ってテストしてください： ```bash claude --debug ``` これは、どのフックが一致したか、コマンドの実行、および出力を示します。一般的な問題と解決策については、[references/troubleshooting.md](references/troubleshooting.md) を参照してください。

<reference_guides> フックの種類とイベント: references/hook-types.md

• フックイベントの完全なリスト
• 各イベントが発火するタイミング
• それぞれの入力/出力スキーマ
• ブロッキングフックと非ブロッキングフック

コマンドフックとプロンプトフック: references/command-vs-prompt.md

• 判断ツリー: どちらの種類を使うか
• コマンドフックのパターンと例
• プロンプトフックのパターンと例
• パフォーマンスに関する考慮事項

マッチャーとパターン: references/matchers.md

• ツールマッチング用の正規表現パターン
• MCP ツールのマッチングパターン
• 複数ツールのマッチング
• マッチャーの問題のデバッグ

入力/出力スキーマ: references/input-output-schemas.md

• 各フックの種類の完全なスキーマ
• フィールドの説明と型
• フック固有の出力フィールド
• 各イベントの JSON の例

動作する例: references/examples.md

• デスクトップ通知
• コマンドの検証
• 自動フォーマットのワークフロー
• ログ記録と監査証跡
• 停止ロジックのパターン
• セッションコンテキストの注入

トラブルシューティング: references/troubleshooting.md

• フックが発火しない
• コマンド実行の失敗
• プロンプトフックの問題
• 権限の問題
• タイムアウトの処理
• デバッグワークフロー </reference_guides>

<security_checklist> 重要な安全要件:

• 無限ループの防止: Stop フックで stop_hook_active フラグを確認し、再帰的な発火を防ぎます
• タイムアウトの設定: ハングを防ぐために適切なタイムアウトを設定します（デフォルト: 60秒）
• 権限の検証: フックスクリプトに実行権限があることを確認します（chmod +x）
• パスの安全性: パスインジェクションを避けるために $CLAUDE_PROJECT_DIR を付けた絶対パスを使用します
• JSON の検証: 構文エラーを検出するために、使用前に jq でフック設定を検証します
• 選択的なブロッキング: ワークフローの中断を避けるために、ブロッキングフックは慎重に使用します

テストプロトコル:

# Always test with debug flag first
claude --debug

# Validate JSON config
jq . .claude/hooks.json

</security_checklist>

<success_criteria> 動作するフック設定には以下が含まれます:

• .claude/hooks.json 内の有効な JSON（jq で検証済み）
• ユースケースに適したフックイベントの選択
• 対象のツールに一致する正しいマッチャーパターン
• エラーなく実行されるコマンドまたはプロンプト
• 適切な出力スキーマ（ブロッキングフックの decision/reason）
• 期待どおりの動作を示す --debug フラグでのテスト
• Stop フックに無限ループがないこと（stop_hook_active フラグを確認）
• 適切なタイムアウトの設定（特に外部コマンドの場合）
• ファイルパスを使用する場合のスクリプトファイルの実行権限 </success_criteria>