scaffold-exercises

scaffold-exercises skill 概覽

scaffold-exercises skill 主要用來幫 agent 建立符合嚴格訓練內容慣例的練習資料夾結構：包含有編號的章節、有編號的練習、像 problem/、solution/、explainer/ 這類變體子資料夾，以及最精簡但足以通過 lint 類檢查的必要檔案。如果你正在製作課程教材、工作坊練習，或是經營結構化的學習型 repo，這就是它真正解決的工作。

scaffold-exercises 最適合用在哪些情境

當你已經有明確的學習規劃，只需要把檔案系統骨架正確、快速且一致地建好時，就很適合使用 scaffold-exercises。它特別適合：

• 在 exercises/ 底下建立新的課程章節
• 依照課綱大綱一次建立多個練習 stub
• 新增 problem、solution 或 explainer 變體，而不用自己猜命名規則
• 避免建立出之後會在 repo linting 階段失敗的錯誤 starter 目錄

哪些人應該安裝 scaffold-exercises

最適合的使用者，是正在維護一個本來就採用練習式教學結構的 repo 的人。scaffold-exercises skill 對維護者、課程作者，以及需要 AI 協助編修 repo 的使用者尤其實用，因為這些人通常更需要正確的路徑與檔案佔位，而不是自動生成大量文字內容。

scaffold-exercises 和一般 prompt 有什麼不同

一般 prompt 也可以叫 AI「建立一些練習資料夾」，但 scaffold-exercises 多了一層針對 repo 規範的約束：

• 章節資料夾採用 XX-section-name
• 練習資料夾採用 XX.YY-exercise-name
• 名稱必須使用 dash-case
• 每個練習至少要有一個變體資料夾
• 每個變體都需要一個非空白的 readme.md
• 像 main.ts 這種程式碼檔案，只有在實際有程式碼時才需要

這代表產生時更少出現格式錯誤的路徑、更少空白佔位檔，也能減少後續手動清理的時間。

導入 scaffold-exercises 前最該先回答的問題

如果你最大的風險是結構逐漸偏離規範，而不是內容缺乏原創性，那就應該安裝 scaffold-exercises。這個 skill 的重點是建立符合慣例的骨架；它本身不是完整的課綱規劃器、教材撰寫器，也不是獨立的程式碼產生器。

如何使用 scaffold-exercises skill

scaffold-exercises 通常怎麼安裝

從 repo 摘要來看，SKILL.md 裡沒有提供它自己的自訂安裝器，所以實際用法會取決於你的 skills runtime。在 Skills 類型的環境裡，團隊常見的做法是先加入來源 repo，再用名稱呼叫 scaffold-exercises skill。如果你的環境支援，常見模式會是：

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

如果你的 agent 平台是用別的方式載入 skills，就把它指向 mattpocock/skills repository，然後選擇 scaffold-exercises。

使用 scaffold-exercises 前先看這個檔案

先從這個檔案開始：

• scaffold-exercises/SKILL.md

這個 skill 很單純，也相對自成一體。從 repository 預覽看不到額外公開的 rules/、resources/ 或輔助腳本，所以大部分實際有用的行為，都直接寫在這一個檔案裡。

scaffold-exercises 需要你提供哪些輸入

當你提供的規劃至少包含以下四項時，這個 skill 會發揮得最好：

1. 章節編號與標題
2. 練習編號與標題
3. 每個練習要包含哪些變體
4. 你要的是只有 stub，還是要有真正的 starter code

如果沒有這些資訊，agent 還是能幫你搭骨架，但它會自行補預設值，而那些預設值未必符合你的需求，特別是在 explainer/ 和 problem/ 的選擇上。

可運作的最低限度 prompt

一個粗略但實用的 scaffold-exercises usage prompt 可以長這樣：

Use scaffold-exercises to create section 03-search-fundamentals under exercises/. Add exercises 03.01-tokenization-basics and 03.02-bm25-ranking. Each should have problem/ and solution/ folders with non-empty readme.md files. Stub only, no code yet.

這樣就夠用，因為它已經提供了編號、名稱、位置和變體類型。

能明顯提升 scaffold-exercises 輸出品質的 prompt 寫法

更好的 prompt 會把預設值講清楚：

Use scaffold-exercises for Skill Scaffolding in this repo. Create exercises/03-search-fundamentals/. Add:

• 03.01-tokenization-basics with explainer/
• 03.02-bm25-ranking with problem/ and solution/
• 03.03-query-expansion with problem/

For each variant, create a non-empty readme.md with the final exercise title and a one-sentence description. Do not add main.ts unless the variant includes code. Keep all names dash-case.

這樣效果更好的原因在於：

• 它消除了資料夾變體上的模糊空間
• 它避免生成不必要的程式碼檔
• 它一開始就把命名規範固定下來
• 它讓 agent 知道「non-empty」在實務上應該長什麼樣子

當規劃不完整時，scaffold-exercises 的預設行為

上游 skill 有一個很重要的細節：在建立 stub 時，如果規劃沒有特別說明，預設會使用 explainer/。對概念型練習來說這很方便，但如果你真正需要的是讓學員動手做的工作區，這個預設就可能不對。若你要的是實作型任務，請明確指定 problem/。

scaffold-exercises 會建立哪些內容

這個 skill 主要圍繞著可重複套用的目錄模式，例如：

• exercises/01-section-name/
• exercises/01-section-name/01.01-exercise-name/problem/readme.md
• exercises/01-section-name/01.01-exercise-name/solution/readme.md

對 stub 類骨架來說，只有 readme 的資料夾是可以接受的。如果之後你要補上程式碼，那麼 main.ts 才應該出現，而且內容也不該只是毫無意義的一行佔位文字。

在真實 repo 中使用 scaffold-exercises 的實際工作流程

一個不錯的流程會是：

1. 先用 plain English 寫出課綱大綱。
2. 把它轉成有編號的章節名稱與練習名稱。
3. 為每個練習指定變體。
4. 請 agent 執行 scaffold-exercises。
5. 在填內容之前先檢查路徑名稱。
6. 執行 repo 的 lint 或驗證流程。
7. 確認無誤後，再補進程式碼與更完整的文件。

這個順序很重要，因為這個 skill 最擅長的是先把結構搭對。

最容易造成大量重工的命名錯誤

最常見的錯誤輸入包括：

• 缺少數字前綴
• 用空格而不是 dash-case
• 把章節編號和練習編號混在一起
• 沒有交代資料夾應該是 problem、solution 還是 explainer

如果你的規劃只寫「Create an exercise on BM25」，那 agent 仍然得自行猜很多事。但如果你寫成「Create 01.03-retrieval-with-bm25 inside 01-retrieval-skill-building with problem/ and solution/」，產出通常就會可靠得多。

scaffold-exercises for Skill Scaffolding 的適配建議

當你的瓶頸是在 repo 結構與一致性時，scaffold-exercises for Skill Scaffolding 會很合適；但如果你需要的是豐富的教學設計、評量內容，或自動生成成熟的教學說明，它就不算強項。把它當成結構規範的執行器，而不是教學設計的替代品，會比較符合實際期待。

scaffold-exercises skill 常見問題

scaffold-exercises 對新手友善嗎

可以，前提是你已經知道自己要什麼樣的練習結構。這個 skill 本身不複雜：它主要是在執行命名、資料夾布局和最低必要檔案的規範。真正比較難的部分，反而是你得先決定好課程規劃和各練習的變體配置。

什麼情況下不該使用 scaffold-exercises

遇到以下情況就不建議用 scaffold-exercises：

• 你的 repo 並不是用有編號的章節與練習資料夾
• 你只需要一篇 markdown 課文，而不是一整棵練習樹
• 你希望 AI 從零發明整個課程架構
• 你的專案使用的檔案契約，不是 readme.md 加上可選的 main.ts

scaffold-exercises 和手動建立資料夾差在哪裡

如果你只做一個練習，手動搭骨架完全沒問題。scaffold-exercises usage 的價值，主要體現在你要一次建立很多練習，而且必須保持一致時。它能降低無效命名、空白 readme，以及資料夾慣例混雜而導致後續檢查失敗的機率。

scaffold-exercises 會生成完整的練習內容嗎

不會。它的核心價值是 scaffolding。它可以建立最小可用的 readme 和佔位結構，但不應把它當成完整的教材撰寫系統。

每次都一定要有 problem、solution 和 explainer 嗎

不需要。上游規則只要求至少有其中一種即可。對 stub 來說，如果沒有特別指定，預設會是 explainer/。應該依照練習目標來選變體，而不是習慣性每次都全加。

scaffold-exercises 會綁死在某一種 repo 結構嗎

會，它本身有明確立場。這個 skill 預設你會使用 exercises/ 階層與特定編號規則。如果你的 repo 正好就是這種模式，它會很有幫助；如果不是，你很可能會花時間和它的假設對抗。

如何改善 scaffold-exercises skill 的使用效果

給 scaffold-exercises 有編號的規劃，不要只給主題清單

想讓 scaffold-exercises 更穩定，最快的方法就是不要再用「主題」下 prompt，而是直接提供精確目標路徑。比較如下：

Weak:

• “Add some exercises about retrieval.”

Strong:

• “Create exercises/01-retrieval-skill-building/01.01-keyword-search, 01.02-bm25, and 01.03-hybrid-search.”

第二種寫法幾乎沒有留給 agent 把資料夾名稱弄錯的空間。

指定變體用途，不要把決定權留給預設值

如果你省略變體類型，這個 skill 在建立 stub 時可能會自動選擇 explainer/。這樣做很有效率，但未必符合你的教學設計。你可以直接說明：

• problem/ 用於學員實作任務
• solution/ 用於參考答案
• explainer/ 用於純概念說明材料

只要補上這一點，scaffold 品質通常就會有明顯提升。

要求最精簡但有效的 readme

一個常見失敗模式，是檔案 technically 建好了，但內容沒有實際用途。可以要求 agent 在每個 readme.md 中都放入標題和一句描述。這不但能確保檔案非空，也會讓後續撰寫教材更順手。

避免生成不必要的程式碼檔

另一個常見錯誤，是到處都建立 main.ts。上游 skill 並不要求 readme-only 的 stub 一定要有它。如果你想要更輕量的骨架，可以直接說「readme-only unless code is explicitly needed」。這樣第一輪輸出會乾淨很多。

在大量生成前，先驗證命名

如果你要一次建立很多練習，可以先要求 agent 列出打算建立的路徑，等你確認後再正式建立。這能提早抓出編號衝突和不自然的 slug，避免最後得重命名幾十個資料夾。

在第一輪 scaffold-exercises 之後再做第二輪修正

第一輪跑完後，可以從以下幾個面向檢查並優化：

• 編號是否連續
• 變體是否完整
• readme 是否真的有用
• 每個練習是否放在正確章節中

接著再要求 agent 做第二輪，只修正上述問題。當你把生成與審核拆開來處理時，scaffold-exercises guide 的整體品質通常會明顯提升。

哪些地方仍然需要人類判斷，scaffold-exercises 無法取代

scaffold-exercises skill 無法替你決定正確的教學順序、練習難度，或教學覆蓋面是否完整。最好的用法，是讓它自動處理結構，再把課綱邏輯與教學判斷保留給人來審核。