hook-factory

Hook Factory v2.0

対話型のQ&A、自動インストール、強化された検証機能により、本番環境ですぐに使えるClaude Codeフックを生成します。

このスキルでできること

Hook Factory v2.0は、3つのモードを備えた包括的なフック生成システムです。

1. 対話型モード（新機能！） - スマートなデフォルト設定を備えた7つの質問によるガイド付きフロー
2. 自然言語モード - 英語の平易な表現で、実現したいことを説明します
3. テンプレートモード - 本番環境向けの10種類のテンプレートから直接生成します

主な機能：

• 対話型Q&A - 検証機能とスマートなデフォルト設定を備えた7つの質問
• 自動インストール - バックアップ／ロールバックに対応したPythonおよびBashインストーラー
• 強化された検証機能 - シークレットの検出、イベント固有のルール、コマンドの検証
• 10種類のテンプレート - 7種類のイベントに対応（PostToolUse、SubagentStop、SessionStart、PreToolUse、UserPromptSubmit、Stop、PrePush）
• 包括的な安全対策 - ツールの検出、サイレントフェイル、アトミック操作
• macOS/Linux対応 - Unix環境ですぐに使える本番環境向けの設定

このスキルを使う場面

次のようなことを行いたい場合は、hook-factoryを使ってください。

• 編集後にコードを自動フォーマットする
• gitでファイルを自動的にステージングする
• エージェントの処理完了時にテストを実行する
• セッション開始時にプロジェクトのコンテキストを読み込む
• カスタムのワークフロー自動化を作成する
• サンプルを通じてフックの仕組みを学ぶ

機能

3つの生成モード

1. 対話型モード（推奨）

python3 hook_factory.py -i

• 7つの質問によるガイド付きフロー
• イベントタイプに基づくスマートなデフォルト設定
• 入力検証と安全性に関する警告
• 自動インストール（任意）

2. 自然言語モード

python3 hook_factory.py -r "auto-format Python files after editing"

• シンプルなキーワードマッチング
• よくあるパターンをすばやく生成

3. テンプレートモード（上級者向け）

python3 hook_factory.py -t post_tool_use_format -l python

• テンプレートを直接選択
• 完全なカスタマイズ制御

対応フックテンプレート（全10種類）

フォーマットとコード品質：

1. post_tool_use_format - 編集後に自動フォーマット（Python、JS、TS、Rust、Go）
2. post_tool_use_git_add - gitでファイルを自動的にステージング

テストと検証： 3. subagent_stop_test_runner - エージェントの処理完了時にテストを実行 4. pre_tool_use_validation - ツール実行前に検証 5. pre_push_validation - git pushの前に確認

セッション管理： 6. session_start_load_context - セッション開始時にコンテキストを読み込む 7. stop_session_cleanup - セッション終了時にクリーンアップ

ユーザーとのやり取り： 8. user_prompt_submit_preprocessor - ユーザープロンプトを前処理 9. notify_user_desktop - デスクトップ通知（macOS/Linux）

セキュリティ： 10. security_scan_code - semgrep/banditによるセキュリティスキャン

対応言語

• Python（blackフォーマッター、pytest）
• JavaScript（prettier、jest）
• TypeScript（prettier、jest）
• Rust（rustfmt、cargo test）
• Go（gofmt、go test）

強化された検証機能（v2.0）

4層の検証システム：

1. 構造検証 - JSON構文、必須フィールド、型
2. 安全性検証 - 破壊的な操作がないこと、ツールの検出、サイレントフェイル
3. マッチャー検証 - 有効なglobパターン、ツール名、ファイルパス
4. イベント固有の検証 - イベントタイプごとのルール（PreToolUse、SessionStartなど）

v2.0の新機能：

• ✅ シークレット検出 - AWSキー、JWTトークン、APIキー、秘密鍵（20種類以上のパターン）
• ✅ イベント固有のルール - PreToolUseにはツールマッチャーが必要、SessionStartは読み取り専用など
• ✅ コマンド検証 - Bash構文、Unixコマンド、パス検証、危険な操作
• ✅ macOS/Linux検証 - プラットフォーム固有のコマンドチェック

安全機能

生成されるすべてのフックには、次の機能が含まれます。

• ✅ ツールの検出（必要なツールがインストールされているか確認）
• ✅ サイレントフェイルモード（ワークフローを中断しません）
• ✅ 適切なタイムアウト設定（イベントタイプに応じて5秒～120秒）
• ✅ 破壊的な操作なし
• ✅ 生成前の包括的な検証
• ✅ わかりやすいドキュメントとトラブルシューティングガイド
• ✅ インストール中の自動バックアップ

呼び出し方

自然言語でのリクエスト

フックに実行させたいことを説明してください。

"I want to auto-format Python files after editing"
"Create a hook that runs tests when agents complete"
"Auto-add files to git after editing"
"Load my TODO.md at session start"

テンプレートの明示的な選択

使用したいテンプレートがわかっている場合：

"Generate a hook using the post_tool_use_format template for JavaScript"
"Create a test runner hook for Rust"

利用可能なテンプレートの一覧

"Show me all available hook templates"
"List hook templates"

インタラクション例

例 1：Python の自動フォーマット

あなた：「編集後に Python コードを自動フォーマットするフックが必要です」

Hook Factory：

• テンプレートを検出：post_tool_use_format
• 言語を検出：Python
• black フォーマッターを使用するフックを生成
• 設定を検証
• generated-hooks/auto-format-code-after-editing-python/ に保存
• hook.json と README.md を作成

例 2：Git への自動追加

あなた：「ファイルを編集したときに、git で自動的にステージングしてください」

Hook Factory：

• テンプレートを検出：post_tool_use_git_add
• git の自動追加フックを生成
• git コマンドを検証
• generated-hooks/auto-add-files-to-git-after-editing/ に保存

例 3：テストランナー

あなた：「エージェントのコーディング完了後に JavaScript のテストを実行してください」

Hook Factory：

• テンプレートを検出：subagent_stop_test_runner
• 言語を検出：JavaScript
• jest/npm test を設定
• generated-hooks/run-tests-when-agent-completes-javascript/ に保存

出力構成

各フックについて、Hook Factory は以下を作成します。

generated-hooks/
└── [hook-name]/
    ├── hook.json        # Complete hook configuration (validated)
    └── README.md        # Installation guide, usage, troubleshooting

hook.json

Claude Code の設定にコピーしてすぐに使える、有効な JSON 設定です。

{
  "matcher": {
    "tool_names": ["Write", "Edit"]
  },
  "hooks": [
    {
      "type": "command",
      "command": "if ! command -v black &> /dev/null; then\n    exit 0\nfi\n\nif [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.py ]]; then\n    black \"$CLAUDE_TOOL_FILE_PATH\" || exit 0\nfi",
      "timeout": 60
    }
  ]
}

README.md

以下を含む包括的なドキュメントです。

• 概要と仕組み
• 前提条件
• インストール手順（手動）
• 設定オプション
• 安全上の注意事項
• トラブルシューティングガイド
• 高度なカスタマイズのヒント

生成されたフックのインストール

自動インストール（v2.0 の新機能！）

Python インストーラーを使用：

cd generated-skills/hook-factory

# Install to user level (~/.claude/settings.json)
python3 installer.py install generated-hooks/[hook-name] user

# Install to project level (.claude/settings.json)
python3 installer.py install generated-hooks/[hook-name] project

# Uninstall
python3 installer.py uninstall [hook-name] user

# List installed hooks
python3 installer.py list user

Bash スクリプトを使用（macOS/Linux）：

cd generated-skills/hook-factory

# Install
./install-hook.sh generated-hooks/[hook-name] user

# Features:
# - Automatic backup with timestamp
# - JSON validation before/after
# - Atomic write operations
# - Rollback on failure
# - Keeps last 5 backups

インタラクティブモードから自動インストール：

• Q7（自動インストール）に「y」と回答します
• フックが自動的にインストールされます
• 手動での作業は不要です

手動インストール（従来の方法）

1. 生成されたファイルを確認

   cd generated-hooks/[hook-name]
   cat README.md
   cat hook.json
   

2. 手動インストール

   • .claude/settings.json（プロジェクト）または ~/.claude/settings.json（ユーザー）を開きます
   • hook.json からフック設定をコピーします
   • 適切なイベントタイプの配列に追加します
   • 保存して Claude Code を再起動します

3. 確認

   • Claude Code のログを確認します：~/.claude/logs/
   • トリガーとなる操作を実行してフックをテストします

検証

すべてのフックについて、以下を検証します。

• JSON 構文：有効で、解析可能な JSON
• 構造：必須フィールドが存在し、型が正しいこと
• 安全性：破壊的な操作（rm -rf など）がないこと
• ツールの検出：外部ツールに検出チェックがあること
• サイレントな失敗：コマンドがワークフローを中断しないこと
• タイムアウト：イベントタイプに適切であること
• マッチャー：有効な glob パターンとツール名であること

ベストプラクティス

1. シンプルに始める：一般的なパターンには自然言語でリクエストします
2. インストール前に確認する：生成された README.md を必ず読みます
3. 独立した環境でテストする：まずテスト用プロジェクトでフックを試します
4. 段階的にカスタマイズする：デフォルト設定から始め、後でカスタマイズします
5. ログを監視する：フックが機能しない場合は ~/.claude/logs/ を確認します

制限事項

プラットフォームのサポート：

• ✅ macOS と Linux を完全にサポート
• ❌ Windows はサポートされていません（Unix コマンド、bash 固有の構文）

カスタマイズ：

• インタラクティブモードでは適切なデフォルト設定が提供されますが、詳細なカスタマイズには制限があります
• 上級ユーザーはテンプレートモードと手動編集を使用してください
• GUI はなく、CLI のみです

テンプレートシステム：

• 一般的なパターンをカバーする 10 個のテンプレート
• カスタムテンプレートを使用するには、templates.json に手動で追加する必要があります
• テンプレートの合成（複数のパターンの組み合わせ）には未対応です

技術詳細

このスキルのファイル

コアファイル：

• SKILL.md - このマニフェストファイル
• hook_factory.py - CLI インターフェースを備えたメインオーケストレーター（687 行）
• generator.py - テンプレートの置換とフックの生成
• validator.py - 拡張検証エンジン（700 行以上）
• templates.json - 本番環境向けフックテンプレート 10 個
• README.md - スキルの使用ガイドと例

v2.0 の新機能：

• installer.py - 自動インストールシステム（536 行）
• install-hook.sh - Bash インストールスクリプト（148 行）
• examples/ - 参考例 10 個（10 フォルダー × 2 ファイル）

依存関係

• Python 3.7+
• 標準ライブラリのみ（外部依存関係なし）

アーキテクチャ（v2.0）

インタラクティブモードのフロー：

User: python3 hook_factory.py -i
    ↓
[7-Question Flow with Smart Defaults]
    ↓
[Template Selection]
    ↓
[Variable Substitution]
    ↓
[4-Layer Validation]
    ↓
[File Generation]
    ↓
[Optional: Auto-Install via installer.py]
    ↓
Generated Hook in generated-hooks/ + Installed

自然言語のフロー：

User Request
    ↓
[Keyword Matching]
    ↓
[Template Selection]
    ↓
[Variable Substitution]
    ↓
[4-Layer Validation]
    ↓
[File Generation]
    ↓
Generated Hook in generated-hooks/

インストールのフロー：

Hook Folder
    ↓
[installer.py or install-hook.sh]
    ↓
[Backup settings.json]
    ↓
[Load + Validate JSON]
    ↓
[Merge Hook]
    ↓
[Atomic Write (temp → rename)]
    ↓
[Validate Result]
    ↓
✅ Installed (or ❌ Rollback)

トラブルシューティング

「リクエストからフックの種類を特定できませんでした」

• より具体的なキーワード（format、test、git add、load）を使用してください
• または、テンプレートを明示的に選択してください
• または、テンプレートを一覧表示して利用可能なものを確認してください

生成されたフックが動作しない

• Claude Code のログを確認してください
• 必要なツールがインストールされていることを確認してください
• ターミナルでコマンドを手動でテストしてください
• README.md のトラブルシューティングセクションを確認してください

検証エラー

• エラーメッセージと修正案を確認してください
• よくある問題：ツールの検出漏れ、破壊的なコマンド
• 必要に応じてテンプレートを変更してください

examples ディレクトリ

examples/ ディレクトリには、参考実装が含まれています。

examples/
├── auto-format-python/      # PostToolUse format example
├── git-auto-add/            # PostToolUse git example
├── test-runner/             # SubagentStop test example
└── load-context/            # SessionStart context example

各例には、直接コピーして使用できる動作確認済みの hook.json ファイルと README.md ファイルが含まれています。

コントリビューション

新しいフックパターンを追加するには：

1. templates.json にテンプレートを追加します
2. generator.py のキーワードマッチングを更新します
3. examples/ に例を追加します
4. この SKILL.md を更新します

バージョン履歴

• 1.0.0（2025-10-30）：初回リリース
  • 4 つのコアフックパターン
  • 自然言語による生成
  • 包括的な検証
  • シンプルなキーワードマッチング

サポート

• ドキュメント：スキルディレクトリの README.md を参照してください
• 例：examples/ ディレクトリを参照してください
• 検証の問題：validator.py の出力を確認してください
• Claude Code Hooks：https://docs.claude.com/en/docs/claude-code/hooks

---

Claude Code Skills Factory によって生成 **最終更新日：**2025-10-30