Claude Code｜把 Skills 與 Hooks 包成可版本管理的 Plugin

當一個 Skill 需要連同範本、參考文件和 Hook 分享給同事，逐個複製檔案容易漏件。本篇把差異審查流程整理成可辨識版本的本機 Plugin，驗證命名空間、腳本路徑、更新與停用，最後交付一個可搬到另一個資料夾使用的完整目錄。

先讀Plugins 入門、Skill 材料拆分與團隊設定維護。下載第 72 篇材料，在 starter 操作。需要 Node.js 22 以上及有效 Claude 登入；閱讀約 20 分鐘，實作約 45 分鐘。

先看清楚套件的根目錄

閱讀完整文字說明

把 Skills 與 Hooks 包成可版本管理的 Plugin，以流程和文件圖形呈現教學重點。

本篇的 plugin 目錄就是外掛根目錄。.claude-plugin 裡放身分描述 plugin.json；skills、hooks、scripts 則是與它並列的資料夾。不要把所有檔案放進 .claude-plugin，也不要把使用者的整個 .claude 目錄拿來當成 Plugin 發布。

plugin/
  .claude-plugin/plugin.json
  skills/review-change/SKILL.md
  skills/review-change/templates/report.md
  skills/review-change/references/checklist.md
  hooks/hooks.json
  scripts/audit.mjs
  scripts/event.mjs

材料中的 Hook 只在匹配的檔案工具事件後寫入本機簡要紀錄，不會寄信、提交程式或上傳內容。先閱讀腳本，再決定是否啟用。分享設定時同時說明實際會執行的動作，不能只用「審查助手」名稱讓讀者忽略套件附帶的自動化。

定義身分與版本

開啟 .claude-plugin/plugin.json，確認 name、version 與 description。mokaair-review 是課程名稱，之後的 Skill 呼叫會帶這個命名空間。version 描述你這份套件的版本，不是 Node、Claude 或 Skill 文件格式的版本。

{
  "name": "mokaair-review",
  "version": "1.0.0",
  "description": "本機教學用唯讀差異審查與簡要事件紀錄"
}

在 plugin/CHANGELOG.md 記錄第一版內容、相容前提與待測環境。如果改了報告欄位、Hook 事件或依賴，應更新版本與說明，讓使用者知道升級會改變什麼。不要只替 ZIP 換檔名，套件內仍保留舊版號，造成難以辨認的兩份內容。

若之前已安裝同名個人 Skill，保留它也可能同時看到不同來源。這時用完整命名空間呼叫外掛技能，並確認來源位置。比較更新時若仍在呼叫舊的 /review-change，結果不會證明新 Plugin 是否正確載入。

讓 Hook 找到套件內腳本

Plugin 可能在讀者電腦或快取的不同位置，腳本路徑不能寫死作者的家目錄。材料以 CLAUDE_PLUGIN_ROOT 指向外掛根目錄，再引用 scripts/audit.mjs。變數在設定裡的寫法要保留，不能在你建立 JSON 時先由本機 shell 展開成私人路徑。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/audit.mjs\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

路徑加引號可處理空格，但仍應在你的目標 shell 與作業系統驗證。腳本採 Node 入口，不依賴 chmod 或特定 shell 內建指令。它從事件的 cwd 決定本次練習的 run-data 位置；外掛程式位置與使用者專案位置分開，更新外掛時不應把使用者結果寫到即將替換的程式目錄。

audit.mjs 另外匯入 event.mjs，因此兩個檔案都要打包。只檢查主檔存在不夠，還要看相對匯入的依賴。如果腳本改成使用第三方套件，也要保存正確依賴與安裝方式；本例只用 Node 內建功能，不需要在 Plugin 裡附上 node_modules。

用本機方式載入並檢查

先執行 Claude 的外掛驗證，再從 starter 啟動本機外掛。驗證成功只代表可檢查的結構通過，不代表 Skill 已被呼叫或 Hook 真實觸發。這兩項還需要後續實際操作紀錄，尤其當帳號登入或組織政策限制功能時。

claude plugin validate ./plugin
claude --plugin-dir ./plugin

進入 Claude 後，查看外掛及技能來源，再以 /mokaair-review:review-change fixtures/toggle.diff 呼叫。預期得到含位置、條件、影響和驗證狀態的報告。這個審查保持唯讀，不能為了證明 Hook 存在就要求 Skill 順便修改程式。

另用一個明確的小任務觸發 Hook，例如請 Claude 在 fixtures/plugin-note.txt 寫入固定假文字。完成後查看 run-data/events.jsonl，核對新的事件時間與工具名稱。既有日誌不能作為本次觸發證據；也不要把完整寫入內容或帳號資料加進紀錄。

在 fixtures/plugin-note.txt 寫入「Plugin 課程測試」。
只改這個練習檔，完成後回報實際位置。

搬移、升級與還原

把完整 plugin 目錄複製到另一個含空格的新資料夾，以那個已確認的路徑重新啟動。再次手動呼叫技能及觸發一次假資料寫入。若仍引用舊資料夾，檢查設定中的絕對路徑、漏掉的附屬檔案，以及你實際啟動的參數。

模擬版本 1.0.1：只在報告範本加入「未執行項目」欄位，更新版號與 CHANGELOG。依當前版本支援的重載方式操作，或直接結束後建立新階段，再確認技能使用的是新範本。不要用同一段舊回答的格式推定新文件已套用。

接著切回保存的 1.0.0 目錄，以相同案例驗證還原。套件更新與結果資料是兩件事；先前的 events.jsonl 不會因為切回舊版而消失。回復程式版本不代表撤銷已發生的外部動作，本課只使用本機假資料便於觀察這個界線。

停用方式與常見問題

--plugin-dir 是本次啟動載入的方式。結束後不帶該參數重新啟動，確認課程外掛來源不再出現。若你另外透過外掛管理介面安裝了它，則需要在對應的安裝來源停用或移除；不要只刪除教材目錄就推定所有已安裝副本都消失。

如果驗證器報錯，先修正身分文件或目錄結構，再測技能與 Hook。若結構通過但執行失敗，保存實際命令、退出碼及 stderr，不要把所有原因都歸成快取問題。可接續Hook 可攜性與恢復追查環境差異。

讓版本號對應到可重現的材料

交付外掛時保存版本號、來源提交及檔案清單，安裝者才能確認自己取得哪一版。單靠資料夾名稱包含 latest，無法比較兩個人的流程差異。若更新修改了 Skill 的參數或輸出格式，在說明中列出需要調整的使用方式。

先在新練習目錄驗證更新，再套用到日常專案。遇到不相容情況時，依保存的上一版檔案重新啟動工作階段，確認載入版本後再重試。移除外掛也不會自動刪掉它曾經產生的報告，這些成果需另外管理。

完成判準與小練習

交付包含所有附屬檔案的 Plugin、版本變更紀錄、兩個位置的載入測試，以及一次升級和還原。Skill 報告與 Hook 事件要分別有證據。這份本機套件完成不等於已上架 Marketplace；對外分發需要另外選擇來源、授權範圍與發布流程。

小練習是故意漏掉 event.mjs，確認驗證與執行各在哪一層發現問題，再恢復檔案重跑。將這個案例加入Skill 回歸集合的分發檢查，讓下一位維護者更新套件時也能發現漏檔，而不是等同事安裝後才回報。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code