為什麼可長期使用的 Skill 不只是一個 Markdown 檔

昨晚學員問「網路上看到的 skill 都是一個 md 檔，為什麼你的都要包一整個資料夾？」這個問題問得很好，因為這不是我刻意做出來的「規格」，而是我在做 skill 的過程中，被現實逼出來的結果。怕遇到淹水的自己互動！！！

關於紀律這檔事

大多數人做 skill 的出發點是「我怎麼讓 Claude 幫我把這件事做好？」，這個問題用一個 md，寫清楚任務說明、輸出格式、幾個範例，完全能解決這個問題。

但我在做 skill 的時候，腦子裡轉的是另一個問題 「這個 skill 交給完全不認識我的學員，他 fork 下去之後，能不能跑出跟我一樣的結果？」

這對應的是兩種完全不同的設計紀律。

① 我是教學者，不只是自用工具人

我的 skill 從一開始就有兩個受眾，第一個受眾是我自己，用來做實際業務，要跑得穩、要快、要可重現。

第二個受眾是學員，要看得懂、能學、能 fork 之後照著做，還要能夠自動識別需求，自己生成所需的 py 驗證。

一旦 skill 要被教，所有隱性的知識就必須外顯化。

我腦子裡記得的這個版型套哪個、這個情境要換哪個參數，全部都要變成明文寫下來的契約。

這就是資料夾結構的第一個來源，因為「可教」這個需求，強迫我把所有約定俗成的東西寫成檔案。

② 我被現實揍過

validate_punct.py 這支驗證腳本為什麼存在？因為我有一次交付的講義裡夾了半形逗號，印出來才發現。

check_clip.py 這支裁切偵測器為什麼存在？因為我有一次做知識圖，在螢幕上看起來好好的，印出來文字被裁掉三分之一。

每一支驗證腳本背後，都是一個「靠肉眼看，看漏了，付出代價」的真實案例。

工程紀律不是從理論長出來的，是從痛長出來的。資料夾裡的 scripts/ 和 tests/ 目錄，記錄的都是這些痛的學費。

③ 我習慣用生態系思維看問題

我在台大念的是森林系，森林系教你的核心思維是：任何一個系統，都不是由孤立的個體組成的，而是由有關係的物種組成的。

物種之間有分工、有邊界、有共用的資源、有共同遵守的規則，這個系統才能穩定運作。

我在做 skill 的時候，腦子裡跑的是同一套邏輯。

course-handout-generator 做的是 A4 多頁講義，knowledge-map-generator 做的是整面知識牆，cornell-notes-generator 做的是固定分區的筆記頁。

這三個 skill 的邊界很清楚，不重疊，各司其職。但它們共用同一套房規，全形標點、凍結契約、驗證閘門，這套房規就像生態系的基因，讓所有 skill 長出來的東西都有一致的品質基準。

一個資料夾式的 skill，不是一個孤立的工具，而是這個浪漫的生態系裡的一個物種。

它有自己的邊界，有自己的內部結構，有共用的 bootstrap.py 和 validate_punct.py，能和其他 skill 共存而不打架。

④ 可靠性的標準不一樣

一個只有自己用的提示詞，大概正確就夠了。

一個要拿去教、要讓學員 fork、要在企業客戶的工作流裡跑的 skill，「大概對」是不夠的。

我把這個標準稱為「可靠性」，除了本身的龜毛之外，我也希望在沒有我在旁邊盯著的情況下，它也能跑出可預期的結果。

要達到這個標準，你需要把所有約定寫成明文，不能靠記憶，所以需要 FROZEN.md 和 registry.json。

要把所有驗證變成程式，不能靠肉眼，所以需要 scripts/ 裡的驗證腳本。

把所有核心邏輯變成測試，不能靠感覺，所以需要 tests/ 裡的回歸測試。

把所有相依套件變成自動安裝，不能靠使用者自己搞定，所以需要 bootstrap.py。

這些東西加起來，就變成了一個資料夾，不是一個 .md 檔。

那一個 md 檔有什麼問題嗎？

沒有問題，如果你的 skill 只是自己用、用完就算、不需要重現、不需要教、不需要讓別人接手，一個 md 檔完全足夠。你想讓這個 skill 做什麼事，寫清楚就好。

但如果你想讓它跨越時間穩定運作，如果你想讓它被教，被學，被 fork 之後還能跑出一樣的結果，如果你想讓它成為體系裡的一個可靠的示範，那它就必須從「提示詞備忘錄」升級成「可維護的自動化系統」。

資料夾結構，就是在升級成半個自動化系統。

別人的 skill 是提示詞，我的 skill 是我對「可靠性」和「可複製性」這兩個要求的設計。

那我這麼懶為什麼還要這樣設計呢？

因為這樣設計的 Skill 丟到 Codex 就是一個產品雛型了，要開發產品快很多啊！

大多數人的 skill 是手稿，我的 skill 是已經打好地基的建築工地。手稿要蓋房子，要先找地、挖土、打地基，才能開始蓋。工地直接繼續蓋就好。

因為本身就已經有明確的引擎邏輯（scripts/）、驗證層（validate_*.py、tests/）、資料契約（registry.json、FROZEN.md）、相依管理（bootstrap.py），丟進 Codex 或 Claude Code 的時候，它看到的就不是「一段描述」，而是一個已經有骨架的專案。

它不需要從零猜你要什麼，它只需要把現有的結構往前推就好咧～～～

本文原發表於 2026/06/26 的 Facebook 貼文，原文照登，僅調整網頁排版；文中提及的產品、價格與活動以當時為準。