scaffold-exercises

scaffold-exercises 技能概覽

scaffold-exercises 是一個偏向建立環境的技能，用來建立符合倉庫命名與 lint 規範的練習目錄。當你需要新增一個章節、建立練習骨架，或在不猜資料夾結構的前提下，統一 problem、solution、explainer 的版型時，它特別有用。它真正要做的不只是「建立資料夾」，而是「產出一個可用的練習骨架，能直接進入內容撰寫、審閱，以及 pnpm ai-hero-cli internal lint」。

scaffold-exercises 適合做什麼

當你已經知道要新增的學習內容，但需要一個乾淨的目錄骨架來承載它時，就適合使用 scaffold-exercises。對課程作者、維護者，以及需要在多個章節之間建立可重複練習結構的代理來說，它都很實用。

scaffold-exercises 最能發揮的場景

當倉庫有嚴格慣例時，這個技能最強：例如分章節編號、練習編號，以及每個變體資料夾內都必須有 readme.md。如果你的工作流程裡常常要先做骨架再填內容，scaffold-exercises 的安裝價值特別高，因為它能在你動筆前先減少格式錯誤。

scaffold-exercises 需要你提供什麼

這個技能預設你能提供章節編號、練習編號、練習名稱，以及預期的變體類型。如果你的需求描述比較模糊，骨架仍然可以建立，但只要輸入能更清楚區分 problem、solution 與 explainer 的用途，結果通常會更好。

如何使用 scaffold-exercises 技能

安裝 scaffold-exercises

用以下方式安裝 scaffold-exercises 技能：

npx skills add mattpocock/skills --skill scaffold-exercises

這就是倉庫裡實際使用的 scaffold-exercises 安裝路徑。安裝完成後，請把它當成一個建立目錄的工作流程，而不是泛用的寫作提示詞。

提供結構化的需求說明

最好的 scaffold-exercises 用法，是先用精簡計畫說清楚目標章節、練習名稱，以及需要的變體。例如：「建立 exercises/02-generation/02.01-rerank-basics/，包含 explainer/ 和 solution/ 骨架；命名維持 dash-case；確保每個 readme 都有內容。」這會比「幫我 scaffold 一個課程」好得多，因為它直接告訴技能要建立哪些路徑，以及哪些檔案必須存在。

先讀對的檔案

先從 SKILL.md 看起，再檢查倉庫中關於練習慣例的部分，包括章節命名、必備子資料夾，以及骨架內容。如果倉庫在其他地方還有相鄰的說明，也要先讀完再產生任何內容。對 scaffold-exercises 來說，關鍵判斷點是目錄格式、預設變體，以及是否需要程式碼檔，或只要 readme.md 骨架就夠。

遵循倉庫的最小可用模式

比較安全的 scaffold-exercises 做法是：先建立資料夾，再加入非空的 readme.md，只有在該變體真的包含程式碼時才加入 main.ts。如果你只是先做骨架，通常預設用 explainer/ 會比硬塞 problem 檔案更乾淨，因為後者容易暗示學生工作還沒完成。標題要和練習名稱一致，第一次建立占位內容時也要避免出現失效連結。

scaffold-exercises 技能 FAQ

scaffold-exercises 只適合新練習嗎？

不是。scaffold-exercises 也適合你在新增章節，或要把既有的一系列練習統一格式時使用。只要你需要先把倉庫的練習結構做對，再往下填內容，它就很有用。

我一定要用這個技能，而不是一般提示詞嗎？

當結構比文案更重要時，就應該用這個技能。一般提示詞可以描述概念，但當輸出必須遵守命名規則、必備資料夾，以及利於 lint 的骨架時，scaffold-exercises 會更適合。

scaffold-exercises 對初學者友善嗎？

算友善，只要你能辨認練習名稱和目標資料夾。初學者最常犯的錯，是把變體類型講得太模糊，或忽略章節／練習的編號規則，結果產生看起來合理、實際上卻不符合倉庫的路徑。

什麼時候不該用 scaffold-exercises？

如果你只需要課程文案、發想腦暴，或一份沒有目錄限制的單次 markdown 草稿，就不要用 scaffold-exercises。它是倉庫結構技能，不是內容生成捷徑。

如何改進 scaffold-exercises 技能

提供更精確的路徑與變體意圖

品質提升最大的方式，就是把精確目錄與每個子資料夾的角色講清楚。強而有力的需求會明確說出應該存在什麼，例如：「建立 exercises/03-ranking/03.02-bm25-tuning/，包含 problem/、solution/、explainer/ 的 readme；problem/ 資料夾要有 TODO；solution/ 資料夾要有參考大綱；explainer/ 則保持概念性內容。」這能幫助 scaffold-exercises 技能在第一次就產出正確結構。

注意常見失敗模式

最常見的問題包括：編號錯誤、少了 readme.md、占位檔案是空的，以及在只需要骨架的練習裡加入了不必要的程式碼檔。另一個常見錯誤，是把章節層級名稱和練習層級名稱混在同一路徑裡。scaffold-exercises 的指引最有效的時候，是你把命名慣例和內容期待分開處理。

第一版骨架完成後再迭代

產生之後，請確認每個資料夾都有必要檔案，而且每份 readme 的文字也確實對應實際練習類型。若你後來決定這個練習需要程式碼，就只在真正影響學習體驗的地方加入 main.ts。對 scaffold-exercises 來說，最快的改善循環是：先 scaffold、再 lint、再調整名稱，最後擴充內容。