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

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

本記事では、SKILL.md のフロントマター全フィールド・2026年5月時点で公式確認された30種類以上のフックイベント・PreToolUse/PostToolUse/UserPromptSubmit のJSONスキーマを日本語でまとめる。2026年4〜5月の最新アップデート（continueOnBlock・updatedToolOutput 全ツール対応・/run /verify バンドルスキル追加）も反映済みだ。Claude Code を業務ワークフローに組み込みたいエンジニアやチームリードが、どちらの機能を使うべきか判断できるようになることを目的としている。

出典: Claude Code 公式サイト

Claude Code の全体像については「Claude Codeとは？機能・料金・使い方ガイド」も参照のこと。

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

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

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

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

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

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

旧来の .claude/commands/ ディレクトリ（カスタムコマンド）はスキルに統合済みだが、既存の .claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は同等に機能する。スキルが優先されるものの、既存ファイルはそのまま動作する。

出典: Anthropic 公式サイト

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

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

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

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

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

---
name: skill-name               # 表示名。省略時はディレクトリ名
description: |                 # Claudeの自動呼び出し判断に使用（推奨）
  記事の下書きを生成する必要があるとき
when_to_use: |                 # descriptionへの追加コンテキスト（1,536文字キャップに合算）
  ユーザーが「下書きして」「記事を書いて」と言ったとき
argument-hint: "[topic]"       # オートコンプリート中に表示されるヒント
arguments: topic audience      # $topic, $audience で参照できる位置引数
disable-model-invocation: true # trueにするとClaudeの自動呼び出しを禁止
user-invocable: false          # falseにするとメニューから非表示（Claude専用）
allowed-tools:                 # 承認不要で使用できるツール
  - Bash
  - Write
disallowed-tools:              # スキル有効中に使用禁止にするツール
  - WebSearch
model: claude-opus-4-5         # このスキルで使用するモデル（/model コマンドで確認できる名前を指定）
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                    # インラインシェルコマンドのシェル（bash or powershell）
---

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

文字列置換変数

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

また、!`コマンド` 構文でスキル本文内にシェルコマンドの出力を動的に埋め込める（ダイナミックコンテキストインジェクション）。たとえば !`git diff HEAD` と書くと、スキル読み込み時に最新のgit差分が本文に挿入される。

呼び出し制御マトリクス

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

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

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

公式が提供するバンドルスキルは即座に使える実装例でもある。v2.1.145以降では /run・/verify・/run-skill-generator が追加された。

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

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

出典: Claude Code 公式サイト

設定の基本構造:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/security-check.sh"
          }
        ]
      }
    ]
  }
}

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

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

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

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

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

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

マッチャーパターンのルール

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

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

v2.1.139以降では、command タイプに args: string[] 形式でシェル解析なし直接実行が可能になった。スペースを含むパスや特殊文字を扱う場合に有用だ。

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...",
  "effort": { "level": "high" }
}

v2.1.128以降、effort.level フィールドと環境変数 $CLAUDE_EFFORT で現在のeffortレベルを受け取れる。effortレベルに応じてチェックの厳密さを切り替えるといった用途に使える。

ツール別の 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スキーマ（2026年5月最新）

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

2026年4〜5月の主要アップデート:

• updatedToolOutput（v2.1.120+）: ツール出力を置換できる。以前はMCPツールのみ対応だったが、v2.1.120以降は全ツール（Bash・Write・Edit等）に対応した。
• continueOnBlock（v2.1.139+）: ブロック時にターンを継続し、ブロック理由をClaudeに伝えて別アプローチを促せる。false（デフォルト）ではターンが終了してユーザーに制御が戻る。
• terminalSequence（v2.1.139+）: デスクトップ通知用のターミナルシーケンスを送信できる。

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

continueOnBlock の使い方（v2.1.139+）

テスト失敗のブロックなど「止めるが諦めるのではなくClaudeに別の方法を試させたい」場面で使う。

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "decision": "block",
    "reason": "テスト失敗: 12件のエラーがあります。エラー内容を確認して修正してください",
    "continueOnBlock": true
  }
}

実践例: ファイル編集後の自動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 イベントの無限ループ対策

#!/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フックが発火する無限ループに陥る。

UserPromptSubmit——プロンプト処理前の制御

UserPromptSubmit はユーザーがプロンプトを送信した後、Claudeが処理を開始する前に発火する。マッチャー非対応（全プロンプトで発火）という点が他のフックと異なり、フィルタやコンテキスト注入の入り口として機能する。

主な用途:

• プロンプトのバリデーション（禁止ワードフィルタ、プロジェクト外の要求のブロック）
• コンテキストの自動注入（現在時刻・Gitブランチ・環境変数の付加）
• プロンプトロギング（チームの利用状況の監査）

exit 2 でプロンプト処理をブロックできる。

実践例: Gitブランチ情報をコンテキストに自動注入

#!/bin/bash
INPUT=$(cat)

BRANCH=$(git branch --show-current 2>/dev/null || echo 'N/A')
ENV_NAME="${NODE_ENV:-development}"

echo "{
  \"hookSpecificOutput\": {
    \"hookEventName\": \"UserPromptSubmit\",
    \"additionalContext\": \"現在のブランチ: $BRANCH | 環境: $ENV_NAME\"
  }
}"
exit 0

実践例: 禁止ワードフィルタ

#!/bin/bash
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.user_prompt // empty')

if echo "$PROMPT" | grep -qi "本番DB\|production database\|DROP TABLE"; then
  echo "本番DBへの直接操作はポリシーによりブロックされています。ステージング環境で試してください。" >&2
  exit 2
fi
exit 0

2026年4〜5月の最新機能アップデート

Claude Code の Hooks/Skills 周辺は2026年4〜5月に大きく強化された。競合記事に未反映の最新機能をまとめる。

Skillsから始め、必要ならHooksを追加する（判断フロー）

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

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

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

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

CLAUDE.md = 社員ハンドブック（常に参照）、Skills = 業務マニュアル（必要時に開く）、Hooks = ドライブレコーダー（AIの判断に干渉せず危険な操作を検知・警告）という比喩が理解の助けになる。

実践ユースケース集

Skillsが適している処理

Hooksが適している処理

Skills × Hooks の連携パターン（スキル内フック）

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

---
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 を発火）
• UserPromptSubmit フックはマッチャー非対応（全プロンプトで発火するため注意）
• 複数フックが updatedInput を返した場合、最後に完了したものが勝つ（順序非決定的）
• フックのデフォルトタイムアウトはコマンドフックで10分。timeout フィールドで調整可能
• SKILL.md は500行以下に保つことが公式推奨（オートコンパクト時に全スキル合計25,000トークンのバジェット管理下）
• agent タイプのフックは実験的機能（仕様変更の可能性あり）

企業利用時の管理設定

• スキルのインラインシェルコマンド（!`command` 構文）は管理設定で "disableSkillShellExecution": true にすると組織全体で無効化できる（ユーザーによるオーバーライド不可）
• settings.autoMode.hard_deny（v2.1.128+）で自動モードの絶対禁止ルールを設定可能
• Enterprise スキルはProject/Personalスキルより優先され、組織全体のワークフローを統一できる
• フックの設定は .claude/settings.json（プロジェクト共有）または ~/.claude/settings.json（個人ローカル）で管理スコープを分離できる

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

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

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

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年5月時点で30種類以上。2025年以前の情報を参照している記事は古い。TeammateIdle・TaskCreated・TaskCompleted・Elicitation・ElicitationResult・PostToolBatch・WorktreeCreate・WorktreeRemove・MessageDisplay など、2026年に追加されたイベントが多数存在する。

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

公式は500行以下を推奨している。オートコンパクション後に古いスキルがドロップされるリスクがあり、全スキル合計25,000トークンのバジェット内で管理される。必要な情報を絞り込み、詳細はスキルディレクトリの別ファイル（examples/・scripts/等）に分けると効率的だ。

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

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

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

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

Q. continueOnBlock はどんなときに使いますか？（v2.1.139+）

テスト失敗のブロックなど「止めるが諦めるのではなくClaudeに別の方法を試させたい」場面で使う。continueOnBlock: true にするとブロック理由をClaudeに伝えてターンを継続する。false（デフォルト）ではターンが終了しユーザーに制御が戻る。

関連記事

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

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

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

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