Hands-on: Using Hooks in Claude Code Skills to Automate Tasks During Skill Usage

Hello, this is Tomada.

The main point I want to convey this time is that by defining Hooks within Skills, you can automatically execute processes when the Skill is used.
In short, it's a feature that allows you to "set dedicated Hooks for Skills."

This is a new feature added in v2.1.0 in January 2026.

https://code.claude.com/docs/en/skills#define-hooks-for-skills

I tested it immediately as there are many useful use cases.

In this article, we will proceed in a hands-on format, covering everything from the YAML syntax for Hooks for Skills to practical configuration methods and operation verification.

Summary for Busy People

Here are the five key points to keep in mind from this article:

• Defining the hooks field within Skills allows you to execute automatic processes when using a Skill.
• Supported events are PreToolUse, PostToolUse, and Stop.
• It uses the same syntax as regular Hooks, but is characterized by being limited to the Skill's lifecycle.
• Using the once option, you can execute a process only once during a session.
• It can be utilized for notifications upon Skill completion, logging, and more.

What are Hooks for Skills?

The official documentation refers to this as "Define hooks for Skills". For convenience, this article will refer to this feature as Hooks for Skills.

Hooks for Skills are commands that are automatically executed during a Skill's lifecycle.

Regular Hooks (defined in settings.json) operate throughout the entire Claude Code session. On the other hand, Hooks for Skills are active only while a specific Skill is being used.

For example, you can set it up so that a notification is displayed upon Skill completion only when you are using the "frontend-design" Skill to create a UI. Since it doesn't fire during other tasks (such as bug fixes or document creation), it allows for finer control.

Differences from Regular Hooks

Feature	Hooks for Skills	Regular Hooks
Definition Location	SKILL.md	settings.json
Scope	Only while using a specific Skill	Entire session
Purpose	Automatic processing specific to a Skill	Automatic processing for the entire project

If you want to "send a notification when all tasks are complete," use regular Hooks. If you want to "send a notification only when a specific Skill is complete," choose Hooks for Skills.

Regular Hooks are explained in detail in another article.

What are Claude Code Hooks? Automate Processes with Lifecycle Events

Events available in Hooks for Skills

Hooks for Skills support the following three types of events:

Event	Firing Timing
PreToolUse	Before tool execution (can be blocked)
PostToolUse	After tool execution completion
Stop	When the Skill process is completed

While regular Hooks have 10 types of events, Hooks for Skills are limited to the three types mentioned above. This is because only events related to the Skill's lifecycle are supported.

Defining hooks in SKILL.md

Hooks for Skills are defined as the hooks field in the YAML front matter of SKILL.md. The syntax is almost the same as regular Hooks, but it is written in YAML instead of JSON.

The basics of Skills and how to create SKILL.md are explained in detail in another article.

How to Create Claude Code Skills! From writing SKILL.md to utilizing the references folder

Basic Structure

---
name: skill-name
description: Skill description
hooks:
  EventName:
    - matcher: "ToolName"
      hooks:
        - type: command
          command: "Command to execute"
---

Field Descriptions

Field	Description
hooks	Definition of Hooks (optional)
EventName	One of PreToolUse, PostToolUse, or Stop
matcher	Regular expression to filter target tools (optional)
type	Fixed value specified as "command"
command	Shell command to execute
once	If true, executes only once during the session (optional)

Hands-on: Setting up logging upon Skill completion

From here, let's actually configure Hooks for Skills. We will proceed with an example: "Record in a log file when the design skill is completed."

Step 1: Creating the Directory Structure

First, create a project for testing.

mkdir -p ~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/scripts
cd ~/Desktop/skills-hooks-test

The target (final) directory structure will be as follows:

~/Desktop/skills-hooks-test/
├── .claude/
│   └── skills/
│       └── design-with-notify/
│           ├── SKILL.md           # Skill definition (including Hooks)
│           └── scripts/
│               └── notify.sh      # Script for notification
└── src/                           # Source code for testing
    └── index.js

Step 2: Creating the Log Recording Script

Create a script to be executed when the Skill completes. In this example, we will record the completion time in a log file.

~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/scripts/notify.sh

#!/bin/bash

# Record to log
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Stop Hook: design-with-notify skill completed" >> ~/Desktop/skills-hooks-test/hooks.log

Grant execution permission.

chmod +x ~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/scripts/notify.sh

Step 3: Creating SKILL.md

Create the SKILL.md file that includes the Hooks for Skills.

~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/SKILL.md

---
name: design-with-notify
description: Creates UI design and records a log upon completion.
  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

This skill records a log when UI design creation is completed.

## Guidelines

- Aim for modern and clean design
- Prioritize using Tailwind CSS
- Consider accessibility

## Logging

When the skill process is completed, it is automatically recorded in the log file.

Here, the Stop event is used, so the log will be recorded when Claude Code's response is finished. Additionally, the Stop event does not require a matcher to be specified.

Step 4: Operation Verification

Start Claude Code and check if the Skill is recognized.

cd ~/Desktop/skills-hooks-test
claude

Check with the /skills command.

> /skills

 Project skills (.claude/skills)
 design-with-notify · ~46 tokens

If design-with-notify is recognized, you are ready to proceed.

Next, ask Claude to create a file. Just to be sure, explicitly mention using the Skill in the prompt.

> Please create a simple button component as src/button.html.
> Use the design-with-notify skill.

When asked for permission to use the Skill, select "Yes".

⏺ Creating a button component using the design-with-notify skill.

⏺ /design-with-notify
  ⎿  Initializing…

────────────────────────────────────────────────────────────────────────────────
 Use skill "design-with-notify"?
 Claude may use instructions, code, or files from this Skill.

   Creates UI design and records a log upon completion.
   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)

Once the file is created and Claude's response is complete, the Stop Hook will fire and the script will execute.

In the default display, Hook execution results may be collapsed. If you expand the Claude Code output with Ctrl + O, you can see the execution result as follows:

  ⎿  Stop hook succeeded

Checking hooks.log confirms that the script was executed upon Skill completion.

cat ~/Desktop/skills-hooks-test/hooks.log

[2026-01-08 15:49:50] Stop Hook: design-with-notify skill completed

This confirms that the Hook fires only when the Skill process is completed.

Supplementary: Utilizing the once Option

Hooks for Skills includes a once option to execute a command only once during a session.

For instance, you might want to check if a log directory exists before starting to use a Skill. However, checking this every time a tool is executed is redundant. The once option is useful in these cases where checking only the first time is sufficient.

---
name: design-with-notify
description: Creates UI design and records a log upon completion
hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "./scripts/check-deps.sh"
          once: true
  Stop:
    - hooks:
        - type: command
          command: "./scripts/notify.sh"
---

In this configuration, the environment check runs only once before the first execution of the Write or Edit tool. If the log directory doesn't exist, it can issue a warning, allowing you to notice before the process fails.

An example of check-deps.sh is shown below:

#!/bin/bash
# Check for the existence of the log directory
LOG_DIR=~/Desktop/skills-hooks-test
if [ ! -d "$LOG_DIR" ]; then
    echo "⚠️ Log directory does not exist: $LOG_DIR"
    exit 1
fi

echo "✅ Dependency check complete"

Just like notify.sh, let's grant execution permission to it.

chmod +x ./scripts/check-deps.sh

Notes on the once Option

If once: true is set, it will not be re-executed during that session. Once you end the session and start a new one, it will be executed again.

Troubleshooting Checkpoints

If Hooks for Skills do not work as expected, check the following points:

Problem	Solution
Hook does not fire	Check if the Skill is recognized with /skills
Command error	Check if the path is correct and if it has execution permissions
Does not fire for specific tools	Check if the matcher regular expression is correct (e.g., Write|Edit)

If there is an error in the Hook, a message like the following will be displayed:

  ⎿  Stop hook error

In this case, try executing the script directly to check for any errors.

~/Desktop/skills-hooks-test/.claude/skills/design-with-notify/scripts/notify.sh

Summary

In this article, we explained how to define Hooks within Skills.

• Hooks for Skills are defined in the hooks field of SKILL.md.
• Supported events are PreToolUse, PostToolUse, and Stop.
• Unlike regular Hooks, they are limited to the Skill's lifecycle.
• The once option allows for execution only once during a session.
• They can be used for notifications or logging upon Skill completion.

By utilizing Hooks for Skills, you can meet the need to "execute specific processes only when using this Skill."
Combining them with regular Hooks will allow for even finer automation.

There are many use cases beyond development as well, so please give it a try!

I'd appreciate it if you followed me on X!

I frequently share expertise and tips on AI-driven development (especially Claude Code)!

https://x.com/muscle_coding

📚 Learn more with the Udemy Course

For those who want to dive deeper into the content of this article:
I have released a Udemy course that systematically explains six expansion features: CLAUDE.md, rules, custom commands, sub-agents, Skills, and Hooks.
You can learn how to maximize development efficiency while saving context through a hands-on format.

https://www.vibecodingstudio.dev/coupons/claude-code-perfect-guide

You can take the course with a special coupon of 1,500 JPY from the link above.