剛開始用 Skill 的時候，我其實不太愿意寫腳本。
我更喜歡用文字。
原因很直接：Codex 本來就能理解中文。我要它怎么做、不要怎么做、輸出什么格式、哪些目錄不要碰、遇到異常怎么處理，寫成一段清楚的說明不就行了？
文字好讀，也好審。
腳本就不一樣了。腳本要考慮路徑、參數、異常、系統差異，還要自己維護。看起來反而多了一層負擔。
所以很長一段時間里，我寫 Skill 的習慣是：盡量把規則寫詳細，把邊界寫清楚，把例子寫充分。能用文字約束的，就不用腳本。
最近項目做大之后，我的想法變了。
不是文字 Skill 不好，而是它只適合一部分場景。需求簡單、輸出自由、偶爾用一次，文字約束很舒服。可一旦項目變大，功能復雜，團隊里要反復使用，還希望輸出格式穩定、結果可檢查、流程可復現，光靠文字就開始吃力。
更關鍵的是，文字規則會持續消耗上下文。
每次運行，Codex 都要重新讀一遍、理解一遍、權衡一遍。項目越大，規則越多，上下文里塞進去的文字越多，真正留給代碼、日志、錯誤信息和現場約束的空間就越少。
我現在越來越覺得，成熟的 Skill 不應該只是“寫得很詳細的提示詞”。
它應該是：腳本做確定動作，文字講工程判斷。
文字 Skill 的優勢很明顯。
比如做一個嵌入式代碼注釋 Skill，可以這樣寫：
# 嵌入式代碼注釋
只處理用戶自研代碼。
必須跳過：
- CMSIS
- HAL 驅動庫
- FreeRTOS
- 第三方組件
- 自動生成文件
優先補充：
- 對外接口函數
- 函數參數和返回值
- 狀態機遷移
- DMA 緩沖區
- 中斷回調
- 全局變量和跨任務共享變量
不要寫語法翻譯式注釋。
不要把不確定的硬件意圖寫成事實。
這種 Skill 對單次任務很有效。
Codex 能理解，也能照著做。問題出現在批量化之后。
同一套文字規則，今天處理 App/Motor 沒問題，明天處理 BSP 可能就漏掉生成文件；這次函數注釋格式統一，下次又混進了幾句“該變量用于保存數據”的低價值注釋；這次輸出清單完整，下次字段名換了，后面的自動匯總腳本就接不上。
這不是 Codex 不聰明。
恰恰是它太會理解，太會根據上下文調整表達。
創造性任務需要這種能力，團隊標準輸出卻害怕這種波動。
小任務里，波動可以接受。
大項目里，波動會變成成本。
以前我喜歡把 Skill 寫得很細。
比如排除目錄寫一遍，注釋格式寫一遍，錯誤處理寫一遍，輸出模板寫一遍，示例再寫幾段。
一開始覺得這是嚴謹。
后來發現，Skill 本身也在吃上下文。
Codex 不是只讀 Skill。它還要讀用戶需求、當前對話、項目文件、錯誤日志、測試輸出、代碼片段。Skill 寫得越長，留給真正任務現場的空間就越少。
這對嵌入式工程師來說很好理解。
上下文窗口就像 RAM。規則、代碼、日志、歷史討論都要放進去。你把一大堆可以機械執行的規則都塞進 RAM，真正要處理的現場數據就被擠掉了。
腳本的好處就在這里。
一個掃描規則，如果寫成文字，每次都要讓 Codex 讀、理解、執行。
如果寫成腳本，Codex 只需要知道“運行這個腳本，讀取結果”。腳本內部的排除規則、路徑過濾、格式校驗，不需要每次全部塞進上下文里重新解釋。
這不只是穩定性問題，也是上下文資源問題。
我現在會把 Skill 分成兩層。
文字層負責講清楚目標和判斷。
腳本層負責做穩定、重復、可校驗的動作。
文字適合寫：
腳本適合做：
這跟嵌入式項目很像。
設計文檔告訴你系統怎么工作，但真正穩定執行的是驅動、接口、測試腳本和 CI。
你不會指望團隊成員每次都靠記憶去手動檢查所有中斷里有沒有阻塞日志。你會做封裝、做規則、做靜態檢查。
Skill 也是一樣。
第一版通常是純文字。
# 嵌入式代碼注釋
請為項目中的用戶自研 C 代碼補充注釋。
跳過開源庫、芯片庫、生成文件。
重點注釋函數參數、返回值、狀態機、DMA、中斷和全局變量。
不要寫低價值注釋。
輸出修改文件列表。
這版適合單次使用。
第二版開始，就應該加入腳本。
比如增加一個掃描腳本：
scripts/scan_user_code.py
它做幾件固定的事：
CMSIS、HAL_Driver、FreeRTOS、third_party。.c、.h、.cpp、.hpp。Codex 不再每次自己判斷掃描范圍，而是讀取腳本結果。
第三版再加檢查腳本：
scripts/check_comment_style.py
它檢查：
這樣流程就變成：
這個流程比純文字穩定得多。
因為最容易漏、最容易抖的動作，被腳本接管了。
個人使用 Skill，結果能看懂就行。
團隊使用 Skill，結果必須能檢查。
如果輸出只是：“已按要求補充注釋，整體符合規范。”
這句話沒有多少價值。
更適合團隊使用的是結構化輸出。
{
"處理文件數": 18,
"跳過文件數": 42,
"新增函數注釋": 31,
"新增變量注釋": 16,
"檢查結果": "通過",
"問題清單": [
{
"文件": "App/Motor/motor_state.c",
"問題": "狀態機注釋缺少故障態退出條件"
}
]
}
這種結果可以進代碼評審，也可以被后續腳本讀取。
如果輸出字段每次都變，團隊就沒法自動化。
這也是為什么腳本重要。腳本可以生成固定字段，可以校驗字段，可以在失敗時明確告訴你哪里不符合。
文字 Skill 很難長期保證這種穩定性。
我現在會按任務的脆弱程度來判斷。
如果任務允許自由發揮，文字 Skill 很好。
如果任務要求穩定復現，腳本就該上場。
尤其當 Skill 里開始出現大量“必須、禁止、固定格式、批量、團隊、校驗、自動化”這些詞時，就應該考慮腳本化。
我現在更喜歡這種結構：
embedded-comment-skill/
├─ SKILL.md
├─ scripts/
│ ├─ scan_user_code.py
│ ├─ check_comment_style.py
│ └─ summarize_result.py
└─ references/
└─ comment_rules.md
SKILL.md 不需要特別長，只寫流程：
# 嵌入式代碼注釋
## 執行流程
1. 先運行 `scripts/scan_user_code.py`，生成候選文件清單。
2. 只處理候選文件，不越過腳本給出的范圍。
3. 為關鍵函數、參數、返回值、狀態機、全局變量和并發訪問補中文注釋。
4. 不寫語法翻譯式注釋。
5. 修改后運行 `scripts/check_comment_style.py`。
6. 檢查失敗時先修正，再輸出總結。
## 不確定情況
如果無法確認某個延時、閾值或硬件動作的真實原因，不要編造設計意圖。可以標記為“需要結合板級文檔確認”。
詳細規則放到 references/comment_rules.md。
掃描和校驗交給腳本。
Codex 負責理解代碼、補充注釋、處理不確定情況。
這樣上下文更干凈，流程也更穩。
我現在對 Skill 的理解，已經從“提示詞增強”變成了“工程化工作流”。
文字仍然重要。
沒有文字，Codex 不知道目標、邊界和取舍。
但只靠文字，很難支撐復雜項目里的穩定輸出，也會持續占用上下文資源。
項目越大，團隊使用越多，輸出越標準化，就越應該把確定動作寫成腳本，把復雜規則拆成可執行、可檢查、可復用的步驟。
這不是不相信 Codex。
恰恰相反，是讓 Codex 做它最擅長的事：理解、判斷、修改和補齊。
而那些重復、機械、容易漏、必須穩定的部分，交給腳本。
嵌入式工程里，我們一直在做這件事。
把經驗固化成驅動，把檢查固化成測試，把危險操作放進受控接口。
Skill 走到最后，也應該這樣。
