Skill 開發者的工作流：在 Termdock 中建立和測試 Agent Skill

沒人談的那個問題

寫 SKILL.md 只要五分鐘。逐步教學帶你從目錄結構、frontmatter 到 body，花的時間比泡咖啡還短。完成後你手上有一個格式正確的 skill。

然後你測試它。

Skill 在你預期的時候沒觸發。或在錯的 prompt 上觸發。或觸發了但 agent 用你沒想到的方式詮釋指令 -- 輸出技術上有遵照指示，卻完全抓不到重點。你打開 SKILL.md 改一句、測試、拿到另一種錯誤、再改、再測。

「skill 存在」和「skill 有用」之間的這道鴻溝，就是多數作者放棄的地方。格式簡單。迭代難。迭代之所以難，因為 feedback loop 和開發者習慣的完全不同。

寫程式時，電腦確定性地執行指令。寫 SKILL.md 時，AI 用機率的方式詮釋指令。同樣文字在不同次執行可能產生不同行為。你覺得明顯的 description 對模型可能含糊。你認為清晰的指令可能和 agent context window 裡的其他東西衝突。

Skill 開發需要不同 workflow。不只文字編輯器，而是能在緊湊、可重複的循環裡編輯、觀察和評估的測試環境。

Skill 開發和一般寫程式有什麼不同

一般寫程式有短而確定性的 feedback loop。改一行。跑程式。輸出每次一樣。從程式碼往前推到行為，準確度接近完美。

Skill 開發打破這個契約。「Runtime」是語言模型，語言模型是隨機的。三件事讓 loop 本質不同：

輸出在每次執行之間會變。 一套指令。Agent 讀了產出結果。完全一樣的 prompt 再跑一次 -- 略微不同的輸出。正常。單次測試幾乎證明不了什麼。需要多次執行才能區分訊號和雜訊。

失敗模式是隱性的。 程式壞掉丟 error。Skill 出問題時 agent 產出看起來合理但安靜地出錯的結果。遵循大部分指令卻跳過你最在意的那一條。用了正確格式卻捏造事實。沒辦法 grep 找這些失敗。只能仔細讀輸出，最好同時對照 agent 推理逐字稿。

觸發機制和指令分開。 Skill 有兩個獨立問題：該啟動時有沒有啟動（description），啟動後做的事對不對（body）。永遠不觸發的 skill 不管指令多好都隱形。Description 完美但指令爛的 skill 比沒有 skill 還糟。兩者必須分開測。

這三個特性意味著你沒辦法用開發程式碼的方式開發 skill。你需要能容納變異、獎勵仔細觀察、把觸發測試和行為測試分開的 workflow。

Edit-Test-Evaluate Loop

核心 workflow 是三面板配置：

左面板：編輯器。 SKILL.md 打開。編輯 frontmatter、description、body 指令。每次修改是一個假設：「如果重新措辭這段，agent 就會正確處理邊界情況 X。」

右上面板：agent session。 輸入應該觸發 skill 的 prompt，或不該觸發的。Agent 回應。觀察。

右下面板：輸出和逐字稿。 Agent 推理過程、完整輸出、碰過的檔案。評估假設是否成立的地方。

Loop：編輯、切到 agent 面板、測試、切到輸出面板、評估、切回編輯器、修正。每個循環 60-90 秒。更久的話瓶頸通常是 context switching -- 翻找終端 tab、捲動找輸出、忘了改了什麼。

終端配置重要的原因就在這裡。三個 view 同時可見時，context-switching 成本歸零。SKILL.md、agent 互動、輸出同時在眼前。Feedback loop 從分鐘壓縮到秒。

面板比例隨工作階段變。開發初期調 description 時 agent 面板佔主導 -- 一個又一個 prompt 確認觸發。後期調指令時編輯器和輸出面板平分焦點。隨時拖拉調整大小，配置跟著工作階段走。

用 AST 分析理解 Skill 結構

包含 script 和 reference 檔案的 skill 有容易丟失的依賴。SKILL.md 引用 scripts/validate.sh，它呼叫 scripts/utils.sh 的 helper，後者讀 references/ 的 config。改一個檔名，skill 無聲壞掉。

跟專案 codebase 互動的 skill 更需要理解結構。Code review skill 要知道哪些檔案 export 什麼。Testing skill 要理解測試框架 API。Deploy skill 要追蹤依賴鏈。

Termdock 內建的 Tree-sitter 分析不用離開終端就能處理。支援 12+ 語言，顯示 function signature、export 結構、import 圖、呼叫依賴。寫一個叫 agent「讀測試檔案來理解測試模式」的 skill 時，你可以先確認那些檔案確實包含你以為的內容。

實際場景：寫一個按專案慣例產生 API route handler 的 skill。把 reference 檔案放進 references/。在寫叫 agent 讀它的指令之前，先對 reference 跑 Tree-sitter，看 agent 會遇到的確切 function signature 和 type definition。避免常見失敗：指令引用的 pattern 存在於心智模型裡卻不在實際檔案中。

Eval Loop：系統化 Skill 測試

好的 skill 設計原則講理論。這裡講實作。

第一步：建立基準線

寫 skill 之前，先在沒有 skill 的狀態下對 agent 跑目標 prompt。儲存輸出。這是基準線。Agent 已經處理得不錯就不需要 skill。在特定可重複的地方失敗的話，那些失敗就是 eval 標準。

Anthropic 官方最佳實踐現在建議 eval-first：不用 skill 讓 Claude 跑代表性任務、找缺口、記錄具體失敗，然後寫最少量指令填補。先 eval 再寫文件。

第二步：寫 2-3 個測試 Prompt

要寫實。不是「test the code review skill」而是「我剛完成 auth 模組重構。Review 這個 branch 的改動，告訴我是否可以安全 merge。」寫實措辭、寫實 context、寫實期待。

至少一個邊界情況。跟 skill 領域相鄰但不該觸發的 prompt。用不尋常措辭表達 skill 該處理的任務。邊界情況揭露 description 和指令是穩健還是脆弱。

第三步：跑有 Skill vs 無 Skill 對比

唯一重要的比較。Skill 有沒有改善輸出？每個測試 prompt 各跑三次（有 skill 和沒有），比較。

輸出大致相當就是花 context 成本沒帶來價值。回頭讓指令更具體，或重新考慮 skill 是否正確解法。

有 skill 的輸出持續更好就有訊號。下一步。

第四步：讀完整逐字稿

不只最終輸出。推理過程。Agent 內部獨白告訴你：

• 有沒有載入 skill（觸發測試）
• 有沒有遵循指令（遵從測試）
• 在哪偏離、為什麼（詮釋測試）
• 花多少 token 把指令複述給自己聽（冗長度指標）

Skill Creator 2026 年 3 月更新後用四個可組合子 agent 自動化：executor 跑 skill、grader 評分、comparator 盲測 A/B、analyzer 挖隱藏模式。不需要 Skill Creator 也能手動做，但它顯著加速迭代。

第五步：迭代

根據逐字稿揭露的問題修。重跑。再檢視。每個循環在至少一個 eval prompt 上產生可量測改善。迭代卻看不到進步就退一步重新審視假設。Skill 可能需要結構性改變，不是措辭微調。

Description 調校：20-Query 方法

description 決定 skill 是否啟動。觸發不 fire 的話其他一切不重要。Agent Skills 完全指南解釋原因。以下是系統化改進方法。

建 20 個 eval query。 10 個應觸發，10 個不應。應觸發涵蓋常見情境、邊界情況、不尋常措辭。不應觸發涵蓋相鄰但明確在 scope 外的任務。

Code review skill 的應觸發 set：

• "Review my last commit"
• "Is this PR safe to merge?"
• "Check the auth module for security issues"
• "I changed 15 files, can you audit them?"
• "Look at the diff and flag anything concerning"

不應觸發：

• "Write unit tests for the auth module"
• "Deploy the staging branch"
• "Explain how the auth module works"
• "Create a new API endpoint"
• "Fix the failing CI build"

每個 query 跑 3 次。 計觸發成功次數。應觸發 query 只 fire 1/3 次就是 undertrigger。不應觸發 query fire 2/3 次就是 overtrigger。

目標整個 set 80% 準確率。 低於就重寫 description 再測。Skill Creator 用 60/40 train/test split 最多迭代 5 次。你也能手動做：找失敗 query 共享的模式，調 description 捕捉或排除。

Claude 傾向 undertrigger skill，description 寧可「積極主動」一點。觸發條件一個個列。「Use this skill when the user asks to review code, audit changes, check a PR, inspect a diff, or when you detect recently modified code and the user asks about quality」比「Helps with code review」好太多。

多 Skill 專案的 Workspace 管理

真實專案有多個 skill。團隊可能同時維護 code review、commit message、testing、deploy skill。每個都有自己的 edit-test-evaluate 循環、eval query、迭代歷史。

在 skill 開發 context 間切換意味著換開啟的檔案、活躍的 agent session、載入的 eval prompt。每次切換丟掉終端配置就花 5-10 分鐘重建。乘以一天的切換次數，流失大量時間。

Termdock 的 workspace 切換保留終端配置和 session 狀態。從 code review skill workspace 切到 deploy skill workspace -- 面板排列、工作目錄、活躍 session 完全回到離開時的樣子。切回去，code review context 原封不動。

對跨多個專案維護 skill 庫的團隊，這是「skill 開發是有空閒下午才做的事」和「skill 開發是日常 workflow 一部分」之間的差別。進出開發環境的摩擦越低，迭代越多。更多迭代代表更好的 skill。

完整 Skill 開發 Session

從頭到尾：

第 0-5 分鐘：Setup。 開 Termdock。三面板：左邊編輯器（60% 寬），右上 agent session，右下輸出。建 skill 目錄和空 SKILL.md。

第 5-10 分鐘：基準線。 Agent 面板跑三個代表 skill 該處理任務的 prompt。儲存輸出。記具體失敗：agent 在哪猜錯、哪裡漏了慣例、哪裡給通用輸出而非專案特定。

第 10-20 分鐘：初稿。 寫 frontmatter 和 body。Description 瞄準剛觀察到的失敗模式。Body 處理具體缺口。初稿 100 行以內。參考設計原則。

第 20-35 分鐘：觸發測試。 跑 10 個應觸發和 5 個不應觸發 query。Agent session 佔螢幕 70%。每個 query 記觸發結果。根據失敗調 description。重跑失敗 query。重複直到 80%+。

第 35-55 分鐘：行為測試。 編輯器和輸出面板平分焦點。用 skill 跑三個基準線 prompt。對比先前存的基準線。讀推理逐字稿。找出 agent 在哪遵循得好、在哪偏離。改 body，重跑，比較。

第 55-65 分鐘：收尾。 完整 eval set 再跑一次。查 regression。確認 SKILL.md 500 行以內、每段都在出力。逐字稿從沒引用過的段落 -- 刪。Tree-sitter 確認被引用 script/檔案的 signature 和指令一致。

第 65-70 分鐘：Commit。 Skill 測過、description 調好、指令精簡。Git visual diff 檢視，commit。

70 分鐘得到測過、評估過的 skill。大部分時間花在觀察和評估，不是寫作。這就是重點：skill 開發主要是測試，測試需要正確的環境。

你帶走的東西

Skill 開發不是寫作問題，是測試問題。格式是小事。讓觸發正確、讓指令正確、驗證 skill 確實比基準線改善 agent 行為 -- 那才是工作。

讓這件事可操作的 workflow：

1. 三面板配置：編輯器、agent session、輸出。三者同時可見。
2. Eval-first 方法：寫任何一行 SKILL.md 之前先建基準線。
3. 20-query description 調校：10 個應觸發、10 個不應觸發，各跑 3 次，目標 80%。
4. 讀逐字稿不只讀輸出：推理過程告訴你 agent 拿指令做了什麼。
5. Workspace 持久化：儲存配置和 session 狀態，隨時進入開發 context。

這和 Anthropic Skill Creator 自動化的 loop 是同一套。工具有幫助，方法論有沒有工具都成立。重要的是量測、比較、迭代的紀律 -- 不是猜測、祈禱然後發布。

Agent Skills 完全指南涵蓋生態系。逐步教學涵蓋格式。設計原則涵蓋手藝。這篇涵蓋環境和 workflow。四塊合在一起，帶你從「我有一個 SKILL.md」到「我有一個能用的 skill」。