生活分享

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

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

閱讀時間約 7 分鐘

LINE 分享
把 Skills 與 Hooks 包成可版本管理的 Plugin:文件、螢幕與完成記號的幾何插圖
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 先看清楚套件的根目錄
  2. 2. 定義身分與版本
  3. 3. 讓 Hook 找到套件內腳本
  4. 4. 用本機方式載入並檢查
  5. 5. 搬移、升級與還原
  6. 6. 停用方式與常見問題
  7. 7. 讓版本號對應到可重現的材料
  8. 8. 完成判準與小練習

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

先讀、與。下載第 72 篇材料,在 starter 操作。需要 Node.js 22 以上及有效 Claude 登入;閱讀約 20 分鐘,實作約 45 分鐘。

先看清楚套件的根目錄

先看清楚套件的根目錄 → 定義身分與版本 → 讓 Hook 找到套件內腳本
先看清楚套件的根目錄 → 定義身分與版本 → 讓 Hook 找到套件內腳本 · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

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

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

編輯器:檢查 starter/plugin · text
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 文件格式的版本。

寫入 plugin/.claude-plugin/plugin.json · json
{
  "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 展開成私人路徑。

寫入 plugin/hooks/hooks.json · json
{
  "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 真實觸發。這兩項還需要後續實際操作紀錄,尤其當帳號登入或組織政策限制功能時。

專案終端機:檢查並載入本機外掛 · text
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,核對新的事件時間與工具名稱。既有日誌不能作為本次觸發證據;也不要把完整寫入內容或帳號資料加進紀錄。

Claude Code 對話框:單獨測試 Hook · text
在 fixtures/plugin-note.txt 寫入「Plugin 課程測試」。
只改這個練習檔,完成後回報實際位置。

搬移、升級與還原

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

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

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

停用方式與常見問題

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

症狀檢查位置處理
找不到技能根目錄結構及命名空間使用外掛完整名稱
Hook 找不到腳本Plugin 根路徑與相對匯入附上所有腳本並檢查引號
更新後仍是舊格式實際載入來源與工作階段重載或新階段後再呼叫
停用後仍有日誌日誌時間及其他安裝來源區分歷史資料與新事件

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

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

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

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

完成判準與小練習

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

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

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享

回總目錄

  • 生活分享

    Claude Code|建立第一個 mod:在 Claude Code 行程內數工具呼叫

    寫一個三檔案的 mod,用驗證器與測試確認它掛上的事件。文件把 mod 定義成多了入口檔的 plugin:入口檔叫 hooks module,Claude Code 在事件發生時呼叫裡面的函式,函式可以觀察、改寫或接手事件。

  • 生活分享

    Claude Code|Git Worktree 平行工作

    隔離多個任務的檔案與分支。Git Worktree 讓同一儲存庫擁有多個工作目錄,各自使用分支與檔案。本篇會把待辦篩選與文件整理分開,確認兩個 session 不會直接改到彼此的檔案,再把其中一個成果整合回主分支。你也會知道何時可以安全清理工作目錄。

  • 生活分享

    Claude Code|雙 Worktree 實作與衝突整合

    隔離兩項功能,最後完成整合與回歸。兩個 Claude 工作階段同時編輯專案,最容易出現的問題是互相改到同一份檔案,或各自測試通過、整合後卻失敗。本篇用兩個 Worktree 分別處理篩選預設值與介面文字,故意製造一次小衝突,再完成整合、驗證與清理。你不需要先啟用 Agent Teams。

  • 生活分享

    Claude Code|比較流程品質、用量與執行時間

    以同一資料集比較兩種工作方法。比較兩種 Claude 工作方法時,不能只挑成功那一次,也不能只看第一個答案有多快。本篇用固定案例、原始紀錄和一致判準,比較品質、重試、等待與人工整合時間,最後寫出有樣本數與限制的報告,而不是保證某個方法一定省錢。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享