可重現的智能體技能：從自我檢查開始

許多團隊在打造 AI 智能體時會陷入同樣的怪圈：技能定義了幾十個，模型卻常在關鍵時刻「失憶」——要么誤用不適合當前環境的能力，要么在明明失敗的操作上反覆重試。複盤這些事故，根因往往不在模型能力，而在技能定義缺少「可重現」的地基：沒有自我檢查、沒有前置條件宣告、沒有失敗語義。

技能不是提示詞的堆砌

傳統寫法把技能當成一段長提示詞，描述「你應該如何做」。問題在於，模型無法在執行前驗證自己是否真的具備條件。一個健康的技能體系應該像可執行程式那樣：先看進入條件，再執行主體，最後定義明確的退出碼。

具體而言，每個技能至少應包含三段結構：

• 前置檢查：執行任何實質動作前，先用唯讀操作確認相依是否就緒。需要 SSH 的技能，先跑一次 echo ok；需要憑證的技能，先驗證 token 是否有效、權限是否足夠。失敗即終止，不進入正文。
• 冪等主體：核心步驟應支援重複執行而不產生副作用。寫入前先讀當前狀態，寫入後再讀校驗，比「盲寫不驗證」穩健一個數量級。
• 失敗契約：定義「什麼算失敗」以及失敗後回傳什麼。沒有失敗契約的技能會把錯誤丟給上下文，讓模型自行猜測下一步，這是多數循環重試的源頭。

自我檢查優先能省 token

把自我檢查放在最前面還有一個容易被忽略的好處：它能在技能真正消耗 token 與外部 API 配額之前，就決定「不該執行」。一次自我檢查的成本通常是幾條唯讀命令，而一次誤執行的成本可能是半小時的清理、被污染的資料，甚至一次需要人工介入的審批。

實務上建議這樣的骨架：先探測環境與參數合法性，再取得一次性資源（例如臨時 token），然後才進入商業邏輯。每一步都要顯式拋出失敗，而不是吞掉錯誤繼續往下走。

可重現性來自可觀測

技能要可重現，前提是失敗可觀察。給每個技能約定統一的錯誤回傳格式——至少包含錯誤碼、人可读原因、可安全重試與否三個欄位——能讓編排層做出正確決策。重試一個不該重試的操作，比不重試危害更大。

另一個觀測手段是乾跑（dry-run）模式：所有寫入降級為列印意圖，讓使用者在真實執行前確認影響面。這對生產環境的自動化管道尤其重要，因為線上沒有復原鍵。

從第一天就固化的習慣

1. 技能文件裡寫明「何時不要用」，與「何時使用」同等重要。
2. 任何外部寫入必須先 GET 確認欄位寫入成功，再進入下一步。
3. 憑證永遠不落日誌，即使是 debug 等級。
4. 每個技能都要有一個探針用例，驗證從真實進入點能否正確失敗與正確成功。

技能工程的核心不是讓模型更聰明，而是把不確定性擋在執行之前。自我檢查優先的技能，是智能體系統從「展示可用」走向「長期可靠」的第一塊基礎設施。