Claude Code Skills 與 Hooks 關係解析

Claude Code Skills 與 Hooks 關係解析

研究摘要

核心結論 Skills 和 Hooks 是 Claude Code 中兩個互補的擴展機制：Skills 提供「知識和能力」（做什麼、怎麼做），Hooks 提供「控制和自動化」（確保做得對、做得安全）。兩者可在 Plugin 中整合，形成「能力層 + 控制層」的完整架構。

核心概念定義

Skills（技能）

Skills 是 Claude Code 的能力擴展機制，用於將專業知識打包成可重複使用的指導文件。

特性 說明
觸發方式 Model-invoked（模型自主判斷調用）
文件格式 Markdown（SKILL.md）
存放位置 <sub>/.claude/skills/ 或 .claude/skills/
核心目的 教 Claude「如何做」特定任務 
<!-- SKILL.md 範例結構 -->
| Skill Name | Description and trigger conditions |

## 技能說明
詳細的執行指導...

## 最佳實踐
...

Hooks（鉤子）

Hooks 是 Claude Code 的事件驅動自動化機制，在特定時機自動執行 shell 命令。

特性 說明
觸發方式 Event-driven（系統事件自動觸發）
配置格式 JSON（settings.json 或 hooks.json）
存放位置 .claude/settings.json 或 plugin 的 hooks/
核心目的 監控、驗證、自動化執行過程 
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ]
  }
}

兩者的關鍵差異

面向 Skills Hooks
觸發機制 Claude 自主判斷使用 系統事件自動觸發
主要目的 提供知識和指導 執行驗證和自動化
執行控制 無法直接阻止操作 可透過 exit code 阻止工具執行
配置格式 Markdown 文件 JSON + Shell 腳本
用戶互動 被動（Claude 決定是否使用） 確定性（事件發生必定執行）

互動關係與生命週期

執行流程圖

[mermaid 圖表 — 原始 HackMD 版本可正常渲染]

flowchart TD A[用戶請求] --> B{Claude 分析任務} B --> C[識別相關 Skill] C --> D[Skill 指導執行策略] D --> E[Claude 調用工具] E --> F[PreToolUse Hook] F -->|允許| G[工具執行] F -->|阻止| H[回饋給 Claude] G --> I[PostToolUse Hook] I --> J{任務完成?} J -->|否| E J -->|是| K[Stop Hook] K --> L[結束] H --> E

層級架構

┌─────────────────────────────────────────────┐
│              用戶請求（User Request）         │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│    能力層（Skills）- 提供知識和執行指導        │
│    • 定義「做什麼」和「怎麼做」               │
│    • Model-invoked，Claude 自主決定          │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│    執行層（Tool Calls）- Claude 調用工具      │
│    • Write, Edit, Bash, Read 等            │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│    控制層（Hooks）- 監控和干預執行            │
│    • 確保「做得對」和「做得安全」             │
│    • Event-driven，確定性執行               │
└─────────────────────────────────────────────┘

Hook 事件類型一覽

Hook 事件 觸發時機 常見用途
PreToolUse 工具執行前 驗證、阻止危險操作
PostToolUse 工具執行後 格式化、測試、日誌
UserPromptSubmit 用戶提交提示前 添加上下文、過濾輸入
SessionStart 會話開始時 載入項目配置
SessionEnd 會話結束時 清理、保存狀態
Stop Claude 完成回應時 最終驗證、測試
SubagentStop 子代理完成時 子任務驗證
PreCompact 上下文壓縮前 保存重要資訊
Notification 發送通知時 自訂通知處理
PermissionRequest 權限請求時 自動授權/拒絕

[!tip] Exit Code 行為

  • Exit 0：Hook 成功，繼續執行
  • 非零 Exit：對於 PreToolUse，會阻止工具執行並將 stderr 回饋給 Claude

在 Plugin 中整合 Skills 和 Hooks

Plugin 目錄結構

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin 元數據
├── skills/
│   └── code-review/
│       └── SKILL.md         # 代碼審查技能
├── hooks/
│   └── hooks.json           # Hook 配置
├── scripts/
│   ├── pre-write-check.sh   # 寫入前檢查
│   └── post-format.sh       # 寫入後格式化
└── README.md

整合範例：代碼審查 Plugin

skills/code-review/SKILL.md：

| Code Review | Use when reviewing code, analyzing PRs, or checking code quality |

## 審查流程
1. 檢查代碼風格和一致性
2. 識別潛在的 bug 和安全問題
3. 評估可讀性和可維護性
4. 提供具體的改進建議

## 注意事項
此專案使用 PreToolUse hook 阻止寫入 .env 文件，
並使用 PostToolUse hook 自動運行 linter。

hooks/hooks.json：

{
  "description": "代碼審查安全和品質控制",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-write-check.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-format.sh"
          }
        ]
      }
    ]
  }
}

[!info] ${CLAUDE_PLUGIN_ROOT} 變數 此變數會自動解析為 plugin 的根目錄路徑，讓 hooks 可以引用同一 plugin 中的腳本。

實用組合模式

1. 代碼質量保證

[mermaid 圖表 — 原始 HackMD 版本可正常渲染]

flowchart LR A[Skill: 編碼標準] --> B[Claude 編寫代碼] B --> C[PostToolUse: Linter] C --> D[PostToolUse: Formatter] D --> E[Stop: 運行測試]

組件 類型 職責
編碼標準指南 Skill 定義代碼風格和最佳實踐
自動 Linting PostToolUse Hook 即時檢查語法問題
自動格式化 PostToolUse Hook 確保代碼風格一致
測試執行 Stop Hook 確保所有測試通過

2. 安全合規控制

組件 類型 職責
安全編碼指南 Skill 指導安全編碼實踐
敏感文件保護 PreToolUse Hook 阻止寫入 .env、密鑰文件
安全掃描 PostToolUse Hook 掃描新代碼的安全漏洞

PreToolUse 阻止敏感文件寫入範例：

#!/bin/bash
# pre-write-check.sh
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')

# 檢查是否為敏感文件
if [[ "$file_path" =</sub> \.(env|pem|key)$ ]] || [[ "$file_path" =~ secrets ]]; then
    echo "❌ 禁止寫入敏感文件: $file_path" >&2
    exit 1
fi
exit 0

3. 文檔自動化

組件 類型 職責
文檔撰寫指南 Skill 定義文檔格式和內容標準
項目上下文載入 SessionStart Hook 自動載入項目資訊
Markdown 驗證 PostToolUse Hook 確保格式正確

4. 機器學習實驗

組件 類型 職責
實驗流程指南 Skill 定義實驗設計和記錄標準
參數驗證 PreToolUse Hook 確保超參數在合理範圍
結果記錄 Stop Hook 自動保存實驗結果

最佳實踐

Skills 設計原則

[!tip] DO - 建議做法

  • 保持專注：一個 Skill 解決一個問題
  • 清晰描述：讓 Claude 能準確判斷何時使用
  • 包含範例：提供具體的輸入/輸出範例
  • 文檔化限制：告知 Claude 相關的 Hook 行為

[!warning] DON'T - 避免做法

  • 不要讓 Skill 範圍太廣泛
  • 不要在 Skill 中放置實際執行代碼
  • 不要假設 Claude 一定會遵循（使用 Hook 強制執行關鍵規則）

Hooks 設計原則

[!tip] DO - 建議做法

  • 保持快速：Hook 會阻塞執行，保持輕量
  • 明確輸出：使用 stderr 提供清晰的錯誤訊息
  • 冪等設計：Hook 可能多次執行，確保結果一致
  • 使用 Matcher：精確匹配需要的工具，避免過度觸發

[!warning] DON'T - 避免做法

  • 不要在 Hook 中執行耗時操作
  • 不要忽略錯誤處理
  • 不要在 Hook 中做複雜的業務邏輯（保持簡單）

整合建議

  1. 先定義 Skill，再設計 Hooks

    • Skill 定義「應該怎麼做」
    • Hooks 確保「必須這樣做」

  2. 在 Skill 中記錄 Hook 行為

    • 讓 Claude 了解哪些操作會被阻止
    • 避免 Claude 重複嘗試被阻止的操作

  3. 使用 Plugin 打包完整功能

    • 一個 Plugin = 相關 Skills + 對應 Hooks + 輔助腳本
    • 便於分享和版本控制

常見問題

[!faq]- Skill 執行時會觸發哪些 Hooks？ Skill 本身不直接觸發 Hooks。但當 Claude 根據 Skill 的指導調用工具（如 Write、Edit、Bash）時，這些工具調用會觸發相應的 PreToolUse 和 PostToolUse Hooks。

[!faq]- 可以用 Hook 強制 Claude 使用特定 Skill 嗎？ 不能直接強制。但可以在 UserPromptSubmit Hook 中注入上下文或提示，引導 Claude 考慮使用特定 Skill。

[!faq]- Hooks 失敗時 Skill 會如何反應？ 如果 PreToolUse Hook 返回非零 exit code，工具調用會被阻止，stderr 內容會回饋給 Claude。Claude 可能會根據回饋調整策略，但這取決於 Skill 中的指導和 Claude 的判斷。

[!faq]- 如何調試 Skills 和 Hooks 的互動？ 使用 claude --debug 啟動 Claude Code，可以看到詳細的 Hook 執行日誌。也可以在 Hook 腳本中輸出調試資訊到日誌文件。

參考資料

來源 標題 可信度
code.claude.com Agent Skills - Claude Code Docs ⭐⭐⭐⭐⭐
code.claude.com Hooks reference - Claude Code Docs ⭐⭐⭐⭐⭐
code.claude.com Get started with Claude Code hooks ⭐⭐⭐⭐⭐
code.claude.com Create plugins - Claude Code Docs ⭐⭐⭐⭐⭐
GitHub Hook Development Skill ⭐⭐⭐⭐⭐
alexop.dev Claude Code customization guide ⭐⭐⭐⭐
eesel.ai A complete guide to hooks in Claude Code ⭐⭐⭐⭐
youngleaders.tech Understanding Claude Code: Skills vs Commands vs Subagents ⭐⭐⭐⭐

本文最初發布於 HackMD @BASHCAT。

留言

張貼留言

這個網誌中的熱門文章

Arduino 課本可能沒教的事(1)

圖片
　　相信有用過Arduino的人都會知道，在一個開發板上的IO腳，有分為"數位腳"、"類比輸入"，也就是板子上場看到的數字0～13與A0~A5，在比較常見的教材中，往往很少提到A0~A5腳位的使用方式，正常都是說明，如何在上面接上一個可變電阻，在由可變電阻調整電壓進入類比輸入端，再有數位腳輸出對應的亮度，重點來了，因為這樣可能有些人認為A0~A5"只能"做類比的事情，但這些類比腳，亦可拿來當數位腳使用，可以從下圖看到，A0～A5於粉紅色區塊標示為14～19，代表其實該腳位要用於數位時，它的編號，而MEGA版本也是相同道理，數位腳由53之後轉為，A0=54、A1=55…以此類推，總而言之，這樣UNO版本腳位其十就很多，足以供一般專案使用。
閱讀完整內容

SI4432 搭配Arduino

圖片
        前陣子從購入兩片si4432模組，拿來搭配arduino使用，傳輸效果算是相當不錯，訊號從1樓可以打到5F，由於已經作成模組化了，使用上也不會太困難，但需要同時接收/發射，所提供的範例是不夠用的。         Arduino&si4432連接方法，由於Si4432工作電壓用的是3.3V，所以建議以CD4050做電位轉換， 但我測試的時候，是使用arduino mini pro ，工作電壓直接接上3.3V所以沒有在做轉換，要使用5V的MCU則需要加，如果不怕燒掉的話也是可以直接上。 arduino mini pro si4432 library則是使用RF22 http://www.airspayce.com/mikem/arduino/RF22/ 檔案中包含了基本的範例，可以直接使用。
閱讀完整內容

燒錄 Arduino mini Pro 燒錄

圖片
    Arduino Mini Pro 算是Uno的縮小板，使用上也沒太大變化，可以注意的是，市面上可能分為有幾個版本16Mhz、8Mhz就連電壓也會有5V、3.3V，但我這邊使用的是5V-16Mhz，工作於3.3V的時候也是可以正常工作，    該有的腳位也都拉出來了，這塊mini上面還有A4~A7，網路上有些比較精簡的版本就沒有這4pin。     接下來介紹燒錄方法，需要準備一組USB to TTL轉換，有RX/TX就可以了， 將 mini RX->TTL TX mini TX->TTL RX mini VCC->TTL VCC mini GND->TTL GND 接妥後，開啟自己的CODE，這邊用範例Blink測試，按下上傳後，等出現Uploading...這時候，立刻馬上，按下mini的 Reset，成功後就會將CODE Upload上去了。  手腳太慢就會出現下面這畫面  網路上還有領外一個使用Uno對燒的方式，也是相同原理，只是Reset是接Uno板子上的Reset這樣就不用手去按他了。
閱讀完整內容