Claude Code Skills vs Hooks 使い分けガイド｜SKILL.md・PreToolUse・PostToolUse 完全解説

Skills はClaudeへの「知識・手順の追加」、Hooks はClaudeの判断に関係なく「イベントを確実に処理させる仕組み」——この一文が両者の本質的な違いを表している。

本記事では、SKILL.md のフロントマター全フィールド・2026年4月時点で公式確認された30以上のフックイベント一覧・PreToolUse/PostToolUse のJSONスキーマを日本語でまとめる。Claude Code を業務ワークフローに組み込みたいエンジニアやチームリードが、どちらの機能を使うべきか判断できるようになることを目的としている。

出典: Claude Code 公式サイト

Skills・Hooks・CLAUDE.mdの三者比較

三者は「いつ読み込まれるか」と「どう制御するか」の2軸で明確に分かれる。

CLAUDE.md が「常に有効なプロジェクト憲法」だとすると、Skills は「呼び出したときだけ有効になる手順書」、Hooks は「Claudeが何をしようとしていても問答無用で動くトリガー」だ。

「Claudeに知ってほしい」のか「確実に実行させたい」のか——この問いがSkills と Hooks を選ぶ最短の判断基準になる。

Skills（SKILL.md）の仕組みと活用

Skills は Claude のツールキットを拡張する「再利用可能なプロンプト・ワークフロー」の仕組みで、2026年時点では Agent Skills オープンスタンダードに準拠している。/skill-name で手動呼び出しするか、関連タスクをClaudeが検知して自動的に読み込む。

旧来の .claude/commands/ ディレクトリ（カスタムコマンド）はスキルに統合済みだが、既存のファイルはそのまま動作する。

出典: Anthropic 公式サイト

ディレクトリ構造とスコープ

my-skill/
├── SKILL.md           # メイン指示（必須）
├── template.md        # Claudeが埋めるテンプレート（任意）
├── examples/
│   └── sample.md      # 期待される出力例（任意）
└── scripts/
    └── validate.sh    # 実行可能なスクリプト（任意）

スキルの保存場所によってスコープが変わる。

同名スキルが複数ある場合、優先順位は Enterprise > Personal > Project の順。

SKILL.mdフロントマター全フィールドリファレンス（2026年4月現在）

---
name: skill-name               # 表示名。省略時はディレクトリ名
description: |                 # Claudeの自動呼び出し判断に使用（推奨）
  記事の下書きを生成する必要があるとき
when_to_use: |                 # descriptionへの追加コンテキスト
  ユーザーが「下書きして」「記事を書いて」と言ったとき
argument-hint: "[topic]"       # オートコンプリート中に表示されるヒント
arguments: topic audience      # $topic, $audience で参照できる位置引数
disable-model-invocation: true # trueにするとClaudeの自動呼び出しを禁止
user-invocable: false          # falseにするとメニューから非表示（Claude専用）
allowed-tools:                 # 承認不要で使用できるツール
  - Bash
  - Write
model: claude-opus-4-6         # このスキルで使用するモデル（セッション中オーバーライド）
effort: high                   # 努力レベル: low/medium/high/xhigh/max
context: fork                  # forkでサブエージェントとして実行
agent: research                # context: fork時に使用するサブエージェントタイプ
hooks:                         # このスキルのライフサイクルにスコープされたフック
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: prompt
          prompt: "読み取り専用操作のみか確認する"
paths:                         # スキルが自動化されるGlobパターン
  - "src/**/*.ts"
shell: bash                    # インラインシェルコマンドのシェル
---

description の品質がトリガー精度を左右する。「プロフェッショナルなドキュメントを作成する」のような抽象的な書き方では誤発火が増える。「記事の下書きを生成する必要があるとき」のように具体的な状況を書くと精度が上がる。また、1,536文字で自動短縮されるため主要ユースケースを前に書くこと。

文字列置換変数

SKILL.md 本文内では次の変数が使える。

呼び出し制御マトリクス

disable-model-invocation と user-invocable を組み合わせることで、スキルの起動経路を細かく制御できる。

副作用が大きいスキル（deploy、send-slack-message 等）は必ず disable-model-invocation: true を設定する。設定しないと、関連する会話の文脈でClaudeが自動起動してしまうリスクがある。

バンドルされたスキル一覧（2026年4月時点）

公式が提供するバンドルスキルは即座に使える実装例でもある。

Hooksの仕組みと全イベント一覧（30以上）

Hooks は settings.json の hooks ブロックで設定し、Claude のライフサイクル上の特定ポイントで確実にシェルコマンドやHTTPリクエストを実行する。「Claudeがその処理を選ぶかどうか」に関係なく動作する点がSkillsとの最大の違いだ。

出典: Claude Code 公式サイト

セッション・ユーザー入力関連イベント

SessionStart の compact マッチャーは、コンテキスト圧縮後の再起動時に重要なコンテキストを再注入するために使われる。

ツール実行関連イベント（最重要）

ツール実行前後を制御するイベント群で、実務的に最も頻繁に使われる。

エージェント・タスク関連イベント

ファイル・設定・その他イベント

公式確認済みのイベント数は30以上。旧来の「18イベント」という情報は古く、2026年4月時点では大幅に拡充されている。

フックタイプ5種の選び方

agent タイプは公式が「実験的（experimental）」と明示しており、今後の変更可能性に注意が必要だ。大半のユースケースでは command または prompt で十分対応できる。

PreToolUse——実行前の制御ゲート

PreToolUse は Claude がツールを呼び出す直前に発火し、許可・拒否・入力書き換えの3つを制御できる唯一のフックイベントだ。セキュリティゲートとして機能する。

入力JSONスキーマ（stdin から受け取る）

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "テストを実行",
    "timeout": 120000,
    "run_in_background": false
  },
  "tool_use_id": "toolu_01ABC123..."
}

ツール別の tool_input の内容を整理する。

permissionDecision 4種の動作と使い分け

重要: "allow" を返しても、settings.json の deny ルールや企業管理のポリシーには勝てない。フックで許可を返せるのは、すでにポリシーが許容している範囲内の操作のみだ。

出力JSONスキーマ（stdout に書き出す）

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": ".envファイルへの書き込みはポリシーにより禁止されています",
    "updatedInput": { "command": "安全な代替コマンド" },
    "additionalContext": "Claudeへの追加情報（ユーザーには表示されない）"
  }
}

updatedInput でツールの入力自体を書き換えることもできる。ただし複数のフックが同時に updatedInput を返した場合、最後に完了したものが勝つ（順序非決定的）ため、書き換えフックは1つだけにするのが安全だ。

実践例: .envファイルへの書き込みブロック

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$TOOL" == "Write" || "$TOOL" == "Edit" ]]; then
  if [[ "$FILE" == *".env"* || "$FILE" == *"package-lock.json"* ]]; then
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":".envおよびpackage-lock.jsonへの直接編集は禁止されています"}}'
    exit 0
  fi
fi
exit 0

PostToolUse——実行後の検証・監査ログ

PostToolUse はツールが正常に完了した後に発火し、実行結果の検証・後処理・ログ記録に使う。ツールはすでに実行済みのため、アクションを元に戻すことはできない点がPreToolUseとの決定的な違いだ。

追加入力フィールド（PreToolUseとの差分）

{
  "tool_response": {
    "stdout": "コマンドの標準出力",
    "stderr": "エラー出力",
    "interrupted": false
  },
  "duration_ms": 1234
}

出力JSONスキーマ

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "decision": "block",
    "reason": "テストが失敗しています。修正してから続けてください",
    "additionalContext": "テスト結果の詳細をClaudeに渡す",
    "updatedToolOutput": { "stdout": "フィルタリングまたは補完した出力" }
  }
}

decision: "block" を返すと、次ターンでClaudeに reason が伝わり、処理の続行を止められる。

実践例: ファイル編集後の自動Prettier実行

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$TOOL" == "Write" || "$TOOL" == "Edit" ]]; then
  if [[ "$FILE" == *.ts || "$FILE" == *.tsx || "$FILE" == *.js ]]; then
    npx prettier --write "$FILE" 2>/dev/null
  fi
fi
exit 0

Stop イベントの無限ループ対策

Stop イベントでClaudeに追加作業を依頼するフックを書く場合、stop_hook_active フィールドのチェックが必須だ。

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # 2回目以降は無条件に終了（無限ループ防止）
fi
# 通常処理...

stop_hook_active が true のときに早期終了しないと、StopフックがClaudeを再起動し、再びStopフックが発火する無限ループに陥る。

Skillsから始め、必要ならHooksを追加する

公式が推奨する順序は「スキルから始め、必要になったらHooksを追加する」だ。

この処理を設定したい
│
├── Claudeに「知っていてほしい」だけ？
│   ├── プロジェクト全体に適用 → CLAUDE.md
│   └── 特定タスクのみ         → Skills（SKILL.md）
│
└── 「必ず実行させたい」処理？
    ├── イベントトリガーで動く → Hooks
    └── ユーザーが明示的に呼ぶ → Skills（disable-model-invocation: true）

判断に迷ったときの補助質問：

• この処理は毎回確実に実行しなければいけないか？ → はい: Hooks / いいえ: Skills
• Claudeの判断に任せてもよいか？ → はい: Skills / いいえ: Hooks
• コードレビューや手順書のようなガイドラインか？ → はい: Skills
• ファイル変更後のフォーマット適用や危険コマンドのブロックか？ → はい: Hooks

実践ユースケース集

Skillsが適している処理

Hooksが適している処理

Skills × Hooks の連携パターン

SKILL.md のフロントマターに hooks フィールドを定義すると、そのスキルがアクティブな間だけ有効なフックを設定できる（2026年追加機能）。

---
name: database-analyst
description: データベース分析タスクを実行するとき
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: prompt
          prompt: "このBashコマンドはデータベースの読み取り専用操作のみか確認する"
---
データベース分析の手順をここに記述...

このパターンにより、スキルのスコープ内でのみ有効な細粒度のセキュリティポリシーを定義できる。全体設定の settings.json を汚さずに済む。

セキュリティと制約事項

フックの実行モデルと「allow」の限界

PreToolUse フックが "allow" を返しても、settings.json の deny ルールや企業管理のポリシーは常に優先される。フックは既存のポリシーが許容する範囲を超えて権限を緩和できない設計になっている。つまり、フックは制限を「より厳しく」することはできるが、「より緩く」することには限界がある。

シェルプロファイルの干渉問題

~/.zshrc や ~/.bashrc に無条件の echo や出力があると、フックの stdout にプリペンドされてJSON解析に失敗する。フックが動作しない場合は、シェルプロファイルを確認することが公式の推奨手順だ。

注意すべき制約一覧

• PostToolUse フックはツールが実行済みのため、アクションを元に戻せない
• PermissionRequest フックは非インタラクティブモード（-p）では発火しない
• Stop フックはユーザーの割り込み時には発火しない（APIエラーは StopFailure を発火）
• 複数フックが updatedInput を返した場合、最後に完了したものが勝つ（順序非決定的）
• フックのデフォルトタイムアウトはコマンドフックで10分。timeout フィールドで調整可能
• bypassPermissions の設定は既存のバイパスモードセッションでのみ有効
• SKILL.md は500行以下に保つことが公式推奨（コンテキストウィンドウ節約のため）

企業利用時の管理設定

• スキルのインラインシェルコマンド（!`command` 構文）は管理設定で "disableSkillShellExecution": true にすると組織全体で無効化できる（ユーザーによるオーバーライド不可）
• Enterprise スキルはProject/Personalスキルより優先され、組織全体のワークフローを統一できる

こんな人・チームに向いている / 向いていない

Skills（SKILL.md）を導入すべき人

• チーム固有のコーディング規約やレビュー手順を標準化したい
• 特定の繰り返しタスク（PR作成・ドキュメント生成・デプロイ手順）をワンコマンド化したい
• 複数プロジェクトで同じ手順をPersonalスキルとして使い回したい
• Claudeに「知識」を渡したいが、毎回CLAUDE.mdに全部書くには量が多い

Hooks を導入すべき人

• ファイル変更のたびにフォーマッタやLintを確実に実行させたい
• Claudeが危険なコマンドを実行しようとしたときに自動でブロックしたい
• 全コマンドの監査ログを確実に残す必要がある（コンプライアンス要件）
• Agent Teamsやサブエージェントを多用しており、タスク完了の制御を細かくしたい

Skills・Hooks ともに今は見送ったほうがよい人

• Claude Code を使い始めて間もなく、CLAUDE.md での基本的なカスタマイズも試していない
• シェルスクリプトや JSON の扱いに不慣れで、デバッグコストが高そう
• チームの合意なく個人がHooksでブロックルールを設定しようとしている（意図しない操作停止につながる）
• スキルに500行超の巨大な手順書を書こうとしている（コンテキスト圧縮で重要部分が消える）

よくある質問

Q. CLAUDE.md、SKILL.md、Hooksの3つは何が違いますか？

CLAUDE.md はセッション開始時から常に有効なプロジェクト全体の指示書。SKILL.md は特定のタスクを呼び出したときだけ読み込まれる手順書。Hooks は特定イベントで「Claudeの判断とは無関係に」確実に実行される処理。Claudeに「知ってほしい」なら CLAUDE.md か SKILL.md、「必ず実行させたい」なら Hooks を選ぶ。

Q. PreToolUse で allow を返せばすべての権限プロンプトを消せますか？

消せない。allow を返してもポリシーの deny ルールが優先される。フックは許可の範囲を「ポリシーが許容する範囲内で」広げることはできるが、ポリシーそのものをバイパスする手段ではない。

Q. フックイベントは何種類ありますか？ 18種と書いてある記事を見たのですが？

公式ドキュメントで確認できるイベントは2026年4月時点で30以上ある。2025年以前の情報を参照している記事は古い。TeammateIdle・TaskCreated・TaskCompleted・Elicitation・ElicitationResult・PostToolBatch・WorktreeCreate・WorktreeRemove など、2026年に追加されたイベントが多数存在する。

Q. SKILL.md はどれくらいの長さまで書けますか？

公式は500行以下を推奨している。長くなると自動コンパクション後に古いスキルがドロップされるリスクがある。必要な情報を絞り込み、詳細はスキルディレクトリの別ファイル（examples/・scripts/等）に分けると効率的だ。

Q. disable-model-invocation: true はどんなときに必須ですか？

デプロイ・外部通知（Slack送信など）・本番DBへの操作のような、実行すると副作用が大きいスキルには必ず設定する。設定しないと、関連する会話でClaudeが自動的にスキルを起動してしまう場合がある。

Q. Hooks はリポジトリにコミットしてチームで共有できますか？

.claude/settings.json に定義したフックはリポジトリにコミットしてチーム全員に配布できる。ただし ~/.claude/settings.json に書いたフックはローカルのみ有効で、コミット対象外となる。セキュリティポリシーの強制適用はプロジェクトの .claude/settings.json か管理ポリシー設定で行う。

関連記事

Claude Code の基本的な使い方は「Claude Codeとは？機能・料金・使い方ガイド」で整理している。

Skills と Hooks の前提となる Claude Code の全体像を把握したい場合は「Claude Code 使い方ガイド」も参照のこと。

Claude Code を含む AIコーディングツール全体の比較は「AIコーディングツール おすすめ 比較」で確認できる。

Claude Code のサブエージェント機能と組み合わせた高度な自動化については「Claude Code Agent Teams 使い方」で解説している。