setup-pre-commit

setup-pre-commit skill 概覽

setup-pre-commit 的作用是什麼

setup-pre-commit skill 會幫代理在 JavaScript 或 TypeScript 儲存庫中，利用 husky、lint-staged、Prettier，以及可選的 typecheck 與 test 腳本，建立一套實用的 Git commit 防線。簡單來說，它會把已暫存檔案的格式化流程串起來，並在有問題時於 commit 進入版本庫前先擋下來。

setup-pre-commit skill 最適合哪些人

這個 skill 很適合團隊或個人開發者：想在既有 repo 裡快速建立穩定、不折騰的 pre-commit 設定，但又不想手動從零設計第一版 Husky 組態。尤其當你本來就是 Node 生態系專案，並希望在 commit 時自動格式化、順手跑一些輕量品質檢查時，它會特別合適。

真正要解決的工作是什麼

大多數使用者要的其實不只是「把 Husky 裝好」。他們真正想要的是一個讓貢獻者能安心 commit 的 repo，並且有一個行為可預期的 hook，能做到：

• 格式化已暫存的檔案
• 在有現成 typecheck 與 test 腳本時執行它們
• 不額外發明 repo 原本沒有的工具鏈
• 跟 repo 使用的 package manager 保持一致

這就是 setup-pre-commit 的實際價值。

setup-pre-commit 與一般泛用提示有什麼不同

泛用提示通常會丟出很多種 Git hook 作法；setup-pre-commit skill 則更聚焦，也更適合常見情境：直接走 Husky + lint-staged + Prettier 這條具體路徑、偵測 package manager、建立正確檔案，並避免加入 repo 其實不支援的 typecheck 或 test 指令。

它預設會建立哪些內容

根據 skill 原始內容，預期輸出會包含：

• husky 初始化
• 一個 .husky/pre-commit 檔案
• 一個 .lintstagedrc
• 只有在 repo 沒有既有 Prettier 設定時才新增 .prettierrc
• 供 lint-staged 使用的 hook 指令，以及在既有腳本存在時才加入 typecheck 與 test

哪些 repo 最適合，哪些不太適合

最適合：

• Node.js repos
• frontend 或 full-stack TypeScript 應用
• 已使用 package.json 的 repos
• 已有 test 與 typecheck 腳本的專案

較不理想：

• 使用自訂 hook 編排的 polyglot monorepo
• 已經採用其他 hook manager 的 repo
• 想要比預設更快、更細緻，或依語言客製 commit 流程的團隊
• 每次 commit 跑測試都會太慢的專案

如何使用 setup-pre-commit skill

setup-pre-commit skill 的安裝情境

如果你在使用 Skills 系統，可以從來源儲存庫加入這個 skill：

npx skills add mattpocock/skills --skill setup-pre-commit

之後應在你要代理實際修改目前儲存庫時呼叫它，而不是拿來抽象地解釋 Git hooks。

setup-pre-commit skill 需要從你的 repo 取得哪些輸入

setup-pre-commit usage 的品質，很大程度取決於 repo 上下文。在呼叫前，請確認代理能檢查：

• package.json
• 任一 lockfile，例如 package-lock.json、pnpm-lock.yaml、yarn.lock 或 bun.lockb
• 現有的 Prettier 設定檔
• 現有的 .husky/ 或其他 Git hook 設定
• 是否存在 typecheck 與 test 腳本

少了這些上下文，代理很可能產出與你的 package manager 或腳本不相符的指令。

應該先讀哪個儲存庫檔案

先看 SKILL.md。這個 skill 本身很單純、也很自含，重要邏輯都在裡面：

• 偵測 package manager
• 安裝 husky、lint-staged 與 prettier
• 執行 npx husky init
• 寫入 .husky/pre-commit
• 寫入 .lintstagedrc
• 只有缺少時才新增 .prettierrc
• 驗證結果

以這個特定 skill 來說，沒有其他藏著關鍵行為的輔助檔案。

如何正確地下 setup-pre-commit 提示

一個太弱的提示：

Set up pre-commit hooks.

一個更有力的提示：

Use the setup-pre-commit skill in this repo. Detect the package manager from lockfiles, inspect package.json, add Husky with lint-staged and Prettier, and only include typecheck or test in .husky/pre-commit if those scripts already exist. Do not overwrite any existing Prettier config. Show me the files you changed and the exact commands you ran.

這樣比較好的原因是：

• 它先把 package manager 規則釘清楚
• 能避免代理憑空加上不存在的腳本
• 能保留既有格式化慣例
• 也要求提供可檢查的 diff

如何把模糊目標轉成完整請求

如果你的真正目標是「讓我們的 Git workflow 更安全」，就應該把它轉成跟 repo 有關的具體限制：

• 目前使用哪個 package manager
• 測試是否快到適合放在 pre-commit
• 你要的是只有格式化，還是格式化加驗證
• repo 是否已經有 Prettier 或 Husky
• 你是否希望 hook 盡量精簡，以免拖慢貢獻者

例如：

Use setup-pre-commit for Git Workflows in this React TypeScript repo. We use pnpm, already have a test script, and have typecheck in package.json. Keep the hook simple and fast. Reuse existing Prettier config if present. If tests look expensive, explain whether they should stay in pre-commit or move to pre-push.

這類提示提供的是足以做判斷的 repo 資訊，而不只是丟一個任務標籤。

預期會產生哪些檔案與指令

對一般 npm repo 來說，這個 skill 通常會導向：

• 安裝 dev dependencies：husky、lint-staged、prettier
• 執行 npx husky init
• 建立 .husky/pre-commit
• 建立 .lintstagedrc
• 視情況建立 .prettierrc

hook 內容應依 package manager 調整。原始 skill 有明確說明：凡是需要用到 npm 的地方，都要替換成偵測到的 package manager。

setup-pre-commit 的 package manager 實務行為

這個 skill 的 package manager 偵測規則很直接：

• package-lock.json → npm
• pnpm-lock.yaml → pnpm
• yarn.lock → yarn
• bun.lockb → bun
• 如果不明確 → npm

這點非常重要，因為不少品質不佳的 setup-pre-commit install 嘗試，真正失敗的原因不是 Husky 本身，而是文件或產生檔案時混用了不同 package manager 的指令。

這個 skill 會刻意省略哪些內容

有一條很實用的邊界：這個 skill 不應該替你的 repo 發明原本不存在的腳本。如果 package.json 裡沒有 typecheck 或 test，那麼 .husky/pre-commit 就不該加入那些行，並且要明確告知使用者。

這也讓它比那種預設每個專案都有 TypeScript 檢查與測試框架的泛用提示更安全。

執行 setup-pre-commit 之後建議的工作流程

代理套用 skill 之後，建議你依序做：

1. 檢查 package.json
2. 檢查 .husky/pre-commit
3. 檢查 .lintstagedrc
4. 確認既有的 Prettier 設定沒有被覆寫
5. 用一個小型的已暫存格式變更做一次測試 commit
6. 判斷 test 是否真的適合留在 pre-commit，還是應該移到其他階段

最後一步很重要：技術上正確，不代表使用體驗就好。若 hook 會跑很久的測試，雖然形式上沒問題，實際上仍可能拖累團隊採用意願。

一份好用的預設審查清單

在合併變更前，請確認：

• package manager 與 repo 一致
• .husky/pre-commit 使用的是貢獻者本機可執行的指令
• hook 沒有呼叫不存在的腳本
• 已暫存檔案的格式化有透過 lint-staged 做範圍限制
• Prettier 設定只有在缺少時才新增
• 每次 commit 的延遲對日常使用來說可以接受

setup-pre-commit skill 常見問題

setup-pre-commit 適合初學者嗎？

適合，前提是 repo 屬於標準 Node 專案。這個 skill 有明確偏好的做法，但本身不複雜，也能避開許多第一次接觸 Husky 初始化與基本 lint-staged 串接時常見的卡點。

setup-pre-commit 沒有涵蓋哪些事？

這個 skill 不會替你設計完整的 code quality 策略。它不會幫你挑 ESLint 規則、不會最佳化 monorepo 的 hook 執行方式，也不會建立複雜到依檔案類型細分的 lint-staged 指令。它的範圍就是先把初始 commit hook 設定好。

什麼情況下不該使用 setup-pre-commit？

以下情況建議跳過：

• 你的 repo 已經有成熟的 Git hook 系統
• 你需要脫離 Node 工具鏈、依語言客製的多步驟 hooks
• 你想要高度自訂的 staged-file 比對模式
• 每次 commit 都跑測試，明顯會拖慢開發者節奏

這些情境下，改用更量身打造的提示，或直接沿用既有內部標準，通常會更好。

它比直接叫 AI「set up Husky」更好嗎？

以這個明確用途來說，通常是。setup-pre-commit 的價值不在於新奇，而在於受約束的執行方式。它把一條合理的預設路徑編碼進來，減少了 lockfile 偵測、缺少腳本判斷，以及何時該建立 Prettier 設定這些地方的猜測成本。

setup-pre-commit 能用在 monorepo 嗎？

有時可以，但要保守看待。如果 repo 有清楚的頂層 package.json，且 hook 策略也是統一的，那它仍然能幫上忙。但如果各個 package 有獨立腳本、不同格式化政策，或 workspace 專屬的測試命令，它的可靠度就會下降。

如果 repo 已經有格式化設定，它還會硬塞 Prettier 嗎？

不會。原始說明明確寫的是：只有在不存在任何既有 Prettier 設定時，才建立 .prettierrc。這是很重要、也很利於採納的行為。

我可以把 setup-pre-commit 用在格式化以外的 Git Workflows 嗎？

可以，但範圍有限。這個 skill 支援在既有 typecheck 與 test 腳本存在時，把它們加進 commit workflow。它不是完整的 branch protection 或 CI 設計工具。

如何改善 setup-pre-commit skill 的使用效果

一開始就提供更完整的 repo 事實

想提升 setup-pre-commit usage 品質，最快的方法就是在提示裡直接提供具體 repo 訊號：

• package manager
• 是否存在 typecheck
• 是否存在 test
• 測試是否夠快
• 是否已經有 Prettier 設定
• 是否已經有 .husky/

當這個 skill 是根據已驗證的事實運作，而不是根據假設推斷時，可靠度會高很多。

要求以 diff 為中心的實作方式

一個很強的改善型提示是：

Use the setup-pre-commit skill, but minimize changes. Reuse existing config where possible, avoid replacing current hook behavior, and show the exact file diff before writing anything risky.

這對那些可能已經有部分工具鏈設定的 repo 特別有幫助。

避免最常見的失敗模式

最常見的失敗模式，就是加進 repo 根本跑不起來的指令。你可以明確告訴代理：

Only add typecheck and test to the hook if those scripts already exist in package.json. Otherwise omit them and explain why.

這條要求與原始 skill 完全一致，也能有效避免 commit 流程壞掉。

以開發者速度為優先，而不只是追求正確

很多團隊後來都會發現，把 npm run test 放進 pre-commit 實在太重。如果速度很重要，就應要求代理評估 hook 成本：

Use setup-pre-commit, but if tests appear slow or broad, explain whether they should move to pre-push or CI instead of pre-commit.

這樣就能把 skill 從「安裝工具」提升成「調整到適合實際 workflow」。

要求輸出對 package manager 安全的指令

如果你的團隊使用 pnpm、yarn 或 bun，即使 repo 裡已經有 lockfile，也建議在提示中直接講明。這能減少歧義，並讓產生的 hook 檔與後續操作說明在指令風格上更一致。

要求代理保留既有標準

如果 repo 本來就已經有格式化或 hook 檔案，請補上：

Do not overwrite existing Prettier or Husky config without comparing and explaining the merge strategy.

這比看起來更重要。Pre-commit 工具常常不是因為技術上有問題而失敗，而是因為太強硬地替換掉團隊既有慣例。

用驗證步驟提升輸出品質

更完整的最終提示可以包含：

After applying setup-pre-commit, verify that the hook files exist, dependencies are in devDependencies, and the hook references only valid scripts. Then tell me how to test it with one staged file.

這會迫使代理不只停留在建立檔案，而是進一步確認實際可用性。

第一輪完成後再迭代

如果第一版輸出技術上正確，但用起來還是不夠順手，可以用以下追問微調：

• “Make the hook faster.”
• “Adapt this for pnpm.”
• “Remove test from pre-commit but keep typecheck.”
• “Keep existing Prettier settings and only add missing pieces.”
• “Adjust for a monorepo root package.”

通常這比重新從零下另一個很寬泛的新提示更有效。

使用者最在意的是什麼

對大多數採用者來說，最好的 setup-pre-commit guide 不是「它裝了多少工具」，而是它是否能：

• 立刻在目前 repo 中運作
• 不要把 commit 流程搞壞
• 尊重既有設定
• 保持足夠快速，讓開發者願意長期開啟

只要圍繞這些結果來使用這個 skill，它更有可能帶來長期、可持續的價值。