Claude Code SkillsでHooksを呼び出すハンズオン：Skill使用時に自動処理を追加しよう
こんにちは、とまだです。
今回伝えたいことの要点は、Skills内でHooksを定義すれば、Skill使用時に自動で処理を実行できるということです。
この機能は 2026年1月の v2.1.0 で追加された新機能です。
色々と便利なケースがあるので、早速検証してみました。
忙しい人のために要約
この記事で押さえておきたいポイントは次の5つです。
- Skills内で hooks フィールド を定義すると、Skill使用時に自動処理を実行できる
- 対応イベントは PreToolUse、PostToolUse、Stop の3種類
- 通常のHooksと同じ構文で、Skillのライフサイクルに限定されるのが特徴
- once オプションで、セッション中に1回だけ実行することも可能
- Skill完了時の通知やログ記録などに活用できる
Hooks for Skillsとは
Hooks for Skillsとは、Skillのライフサイクル中に自動実行されるコマンドです。
通常のHooks（settings.jsonに定義するもの）は、Claude Codeのセッション全体で動作します。一方、Hooks for Skillsは特定のSkillが使われている間だけ有効になります。
たとえば、「frontend-design」Skillを使ってUIを作成しているときだけ、Skill完了時に通知を表示する、といった設定が可能になります。他のタスク（バグ修正やドキュメント作成など）では発火しないため、より細かい制御ができるわけです。
通常のHooksとの違い
| 特徴 | Hooks for Skills | 通常のHooks |
|---|---|---|
| 定義場所 | SKILL.md | settings.json |
| スコープ | 特定のSkill使用中のみ | セッション全体 |
| 用途 | Skill固有の自動処理 | プロジェクト全体の自動処理 |
「すべてのタスク完了時に通知を出したい」なら通常のHooks、
「特定のSkill完了時だけ通知を出したい」ならHooks for Skillsを選ぶとよいでしょう。
通常のHooksについては、別な記事で詳しく解説しています。
Claude CodeのHooksとは？ライフサイクルイベントで処理を自動化する
Hooks for Skillsで使えるイベント
Hooks for Skillsでは、以下の3種類のイベントがサポートされています。
| イベント | 発火タイミング |
|---|---|
| PreToolUse | ツール実行前（ブロック可能） |
| PostToolUse | ツール実行完了後 |
| Stop | Skillの処理が完了した時 |
通常のHooksでは10種類のイベントがありますが、Hooks for Skillsでは上記の3種類に限定されています。
これは、Skillのライフサイクルに関連するイベントのみがサポートされているためです。
SKILL.mdでのhooks定義
Hooks for Skillsは、SKILL.mdのYAMLフロントマターに hooks フィールドとして定義します。
構文は通常のHooksとほぼ同じですが、JSONではなくYAMLで記述します。
Skillsの基本やSKILL.mdの作成方法については、別な記事で詳しく解説しています。
Claude Code Skillsの作り方！SKILL.mdの書き方から references フォルダの活用まで
基本構造
---
name: skill-name
description: スキルの説明
hooks:
イベント名:
- matcher: "ツール名"
hooks:
- type: command
command: "実行するコマンド"
---
フィールドの説明
| フィールド | 説明 |
|---|---|
hooks |
Hooksの定義（オプション） |
イベント名 |
PreToolUse、PostToolUse、Stop のいずれか |
matcher |
対象ツールを絞り込む正規表現（省略可） |
type |
"command" を固定で指定 |
command |
実行するシェルコマンド |
once |
true にするとセッション中1回だけ実行（オプション） |
Skill完了時にログを記録する設定
ここからは、実際にHooks for Skillsを設定してみましょう。「デザインスキル完了時に、ログファイルへ記録を行う」という例で進めていきます。
手順1：ディレクトリ構造の作成
まず、テスト用のプロジェクトを作成します。
mkdir -p ~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/scripts
cd ~/Desktop/skills-hooks-test
目指していく（最終的な）ディレクトリ構造は以下のようになります。
~/Desktop/skills-hooks-test/
├── .claude/
│ └── skills/
│ └── design-with-notify/
│ ├── SKILL.md # Skills定義（Hooks含む）
│ └── scripts/
│ └── notify.sh # 通知用スクリプト
└── src/ # テスト用のソースコード
└── index.js
手順2：ログ記録用スクリプトの作成
Skill完了時に実行するスクリプトを作成します。
この例では、完了時刻をログファイルに記録します。
#!/bin/bash
# ログに記録
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Stop Hook: design-with-notify スキルが完了しました" >> ~/Desktop/skills-hooks-test/hooks.log
実行権限を付与します。
chmod +x ~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/scripts/notify.sh
手順3：SKILL.mdの作成
Hooks for Skillsを含むSKILL.mdを作成します。
---
name: design-with-notify
description: UIデザインを作成し、完了時にログを記録する。
Use when creating frontend UI, designing components, or working with
HTML/CSS/JavaScript files.
hooks:
Stop:
- hooks:
- type: command
command: "~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/scripts/notify.sh"
---
# Design with Log Skill
このスキルは、UIデザイン作成が完了したときにログを記録します。
## ガイドライン
- モダンでクリーンなデザインを心がける
- Tailwind CSS を優先的に使用する
- アクセシビリティを考慮する
## ログ記録
スキルの処理が完了すると、自動的にログファイルに記録されます。
ここでは Stop イベントを使用していますので、Claude Code の応答が完了したときにログが記録されます。
また、Stop イベントは特に matcher を指定する必要がありません。
手順4：動作確認
Claude Code を起動し、Skillが認識されているか確認します。
cd ~/Desktop/skills-hooks-test
claude
/skills コマンドで確認してみましょう。
> /skills
Project skills (.claude/skills)
design-with-notify · ~46 tokens
design-with-notify が認識されていればOKです。
次に、Skillを使ってファイルを作成してもらいましょう。
念のため、プロンプトにSkillの使用を明示しておきます。
> シンプルなボタンコンポーネントを src/button.html として作成してください。
> design-with-notify スキルを使ってください。
Skillの使用許可を求められたら「Yes」を選択します。
⏺ design-with-notify スキルを使ってボタンコンポーネントを作成します。
⏺ /design-with-notify
⎿ Initializing…
────────────────────────────────────────────────────────────────────────────────
Use skill "design-with-notify"?
Claude may use instructions, code, or files from this Skill.
UIデザインを作成し、完了時にログを記録する。
Use when creating frontend UI, designing components, or working with
HTML/CSS/JavaScript files.
(project skill)
Do you want to proceed?
❯ 1. Yes
2. Yes, and don't ask again for design-with-notify in this project
3. No, and tell Claude what to do differently (esc)
ファイルが作成され、Claudeの応答が完了すると、Stop Hookが発火してスクリプトが実行されます。
通常の表示では Hooks の実行結果が折りたたまれていることがあります。
Claude Code の出力を Ctrl + Oで展開すると、以下のようにHooksの実行結果が確認できます。
⎿ Stop hook succeeded
hooks.log を確認すると、Skill完了時にスクリプトが実行されたことがわかります。
cat ~/Desktop/skills-hooks-test/hooks.log
[2026-01-08 15:49:50] Stop Hook: design-with-notify スキルが完了しました
このように、Skillの処理が完了したときにだけHooksが発火することを確認できました。
onceオプションの活用
Hooks for Skillsには、セッション中に1回だけ実行する once オプションがあります。
たとえば、Skill使用開始時に「ログディレクトリが存在するか」を事前にチェックしておきたいとします。しかし、毎回ツール実行のたびにチェックするのは無駄です。こういった初回だけ確認すれば十分なケースで once オプションが役立ちます。
---
name: design-with-notify
description: UIデザインを作成し、完了時にログを記録する
hooks:
PreToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "./scripts/check-deps.sh"
once: true
Stop:
- hooks:
- type: command
command: "./scripts/notify.sh"
---
この設定では、Write/Edit ツールが最初に実行される前に1回だけ環境チェックが走ります。ログディレクトリが存在しなければ警告を出し、処理が失敗する前に気づけるわけです。
check-deps.sh の例を以下に示します。
#!/bin/bash
# ログディレクトリの存在確認
LOG_DIR=~/Desktop/skills-hooks-test
if [ ! -d "$LOG_DIR" ]; then
echo "⚠️ ログディレクトリが存在しません: $LOG_DIR"
exit 1
fi
echo "✅ 依存関係チェック完了"
notify.sh と同様に、実行権限を付与しておきましょう。
chmod +x ./scripts/check-deps.sh
うまく動作しない場合の確認ポイント
Hooks for Skillsがうまく動作しない場合は、以下を確認してください。
| 問題 | 対処法 |
|---|---|
| Hookが発火しない |
/skills でSkillが認識されているか確認 |
| コマンドがエラー | パスがあっているか、実行権限があるか確認 |
| 特定のツールで発火しない |
matcher の正規表現が正しいか確認（Write|Edit など） |
Hookにエラーがある場合、以下のようなメッセージが表示されます。
⎿ Stop hook error
この場合は、スクリプトを直接実行してエラーがないか確認しましょう。
~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/scripts/notify.sh
まとめ
Skills内でHooksを定義する方法を解説しました。
- Hooks for Skillsは SKILL.md の hooks フィールド で定義する
- 対応イベントは PreToolUse、PostToolUse、Stop の3種類
- 通常のHooksと異なり、Skillのライフサイクルに限定される
-
onceオプションでセッション中1回だけの実行も可能 - Skill完了時の通知やログ記録に活用できる
Hooks for Skillsを活用することで、「このSkillを使うときだけ特定の処理を実行したい」というニーズに応えられます。
通常のHooksと組み合わせることで、より細かい自動化が実現できるでしょう。
開発以外にも使える場面は多いので、試してみてください。
Xをフォローいただけると嬉しいです！
AI駆動開発（特に Claude Code）のノウハウや Tips をよく発信しています！
Discussion