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 開發需要一種不同的工作流。不只是文字編輯器，而是一個能讓你在緊湊、可重複的循環裡編輯、觀察和評估的測試環境。

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

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

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

輸出在每次執行之間會變化。 你寫一套指令。Agent 讀了之後產出結果。你用完全一樣的 prompt 再跑一次，拿到略微不同的輸出。這是正常的。這意味著單次測試幾乎證明不了什麼。你需要多次執行才能區分訊號和雜訊。

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

觸發機制和指令是分開的。 一個 skill 有兩個獨立的問題：它該啟動的時候有沒有啟動（description 欄位），以及啟動後做的事對不對（body）。一個永遠不觸發的 skill，不管指令寫得多好都是隱形的。一個 description 完美但指令很爛的 skill，比沒有 skill 還糟。你必須分開測試兩者。

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

Edit-Test-Evaluate Loop

Skill 開發的核心工作流是三面板配置：

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

右上面板：agent session。 你輸入一個應該觸發 skill 的 prompt，或一個不該觸發的 prompt。Agent 回應。你觀察發生了什麼。

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

Loop 是：編輯、切到 agent 面板、測試、切到輸出面板、評估、切回編輯器、修正。每個循環應該在 60 到 90 秒內完成。如果更久，瓶頸通常是 context switching：翻找正確的終端 tab、捲動找輸出、忘了自己改了什麼。

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

面板比例會隨著工作階段變化。開發初期，當你還在調 description，agent 面板佔主導。你在跑一個又一個 prompt，確認 skill 是否觸發。後期，當你在調指令，編輯器和輸出面板平分焦點。能隨時拖拉調整面板大小，讓你的配置跟著工作階段走。

用 AST 分析理解 Skill 結構

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

對於會和專案實際 codebase 互動的 skill，理解結構更加重要。Code review skill 需要知道哪些檔案 export 了什麼。Testing skill 需要理解測試框架的 API。Deployment skill 需要追蹤依賴鏈。

Termdock 內建的 Tree-sitter 分析不需離開終端就能處理這件事。它支援 12 種以上的語言，顯示 function signature、export 結構、import 圖和呼叫依賴。當你在寫一個告訴 agent「讀取測試檔案來理解專案的測試模式」的 skill 時，你可以先自己跑 AST 分析，確認你指向的東西確實包含你以為的內容。

實際使用場景：你在寫一個按照專案慣例產生 API route handler 的 skill。你把一個 reference 檔案放進 skill 的 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 應該處理的任務的 prompt。邊界情況能揭露你的 description 和指令是穩健的還是脆弱的。

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

這是唯一重要的比較。Skill 有沒有改善輸出？每個測試 prompt 各跑三次（有 skill 裝著和沒裝的情況下），比較結果。

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

如果有 skill 的輸出持續更好，你有訊號了。進入下一步。

第四步：讀完整逐字稿

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

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

Skill Creator 在 2026 年 3 月更新後，用四個可組合的子 agent 自動化了這件事：executor 跑 skill、grader 評分輸出、comparator 在 skill 版本之間做盲測 A/B 對比、analyzer 挖出隱藏模式。你不需要 Skill Creator 也能手動做這些，但它能顯著加速迭代。

第五步：迭代

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

Description 調校：20-Query 方法

description 欄位決定你的 skill 是否啟動。如果觸發永遠不 fire，其他一切都不重要。Agent Skills 完全指南解釋了為什麼這很重要。以下是系統化改進它的方法。

建立 20 個 eval query。 10 個應該觸發 skill，10 個不應該。應觸發的 set 涵蓋常見情境、邊界情況和不尋常的措辭。不應觸發的 set 涵蓋相鄰但明確在 skill 範圍之外的任務。

以 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"

不應觸發的 set：

• "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 只在 3 次中 fire 了 1 次，你的 description 對那種措辭 undertrigger 了。如果一個不應觸發的 query 在 3 次中 fire 了 2 次，你 overtrigger 了。

目標是整個 set 80% 的準確率。 低於這個數字就重寫 description 再測。Skill Creator 的 description 調校用 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 that code has been recently modified and the user is asking about quality」比「Helps with code review」好太多。

多 Skill 專案的 Workspace 管理

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

在 skill 開發 context 之間切換，意味著更換開啟的檔案、活躍的 agent session、載入的 eval prompt。如果每次切換都丟掉終端配置，你會花 5 到 10 分鐘重建環境。乘以一天內的切換次數，你在流失大量時間。

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

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

完整的 Skill 開發 Session

以下是一個從頭到尾的完整 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 記下 skill 是否觸發。根據失敗調整 description，重跑失敗的 query，重複直到觸發準確率超過 80%。

第 35-55 分鐘：行為測試。 切換配置讓編輯器和輸出面板平分焦點。用 skill 啟動的狀態跑三個基準線 prompt。把輸出和先前存的基準線比較。在輸出面板讀推理逐字稿。找出 agent 在哪遵循指令做得好、在哪偏離。編輯 SKILL.md body，重跑，比較。

第 55-65 分鐘：收尾。 把完整 eval set 再跑一次。檢查 regression：修一個行為有沒有破壞另一個？確認 SKILL.md 在 500 行以內、每個段落都在出力。如果有段落在逐字稿裡從沒被引用過，刪掉。用 Tree-sitter 確認任何被引用的 script 或檔案的 signature 和你的指令一致。

第 65-70 分鐘：Commit。 Skill 測過了、description 調好了、指令精簡了。用 git visual diff 檢視確切改了什麼，然後 commit。

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

你帶走的東西

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

讓這件事可以操作的工作流：

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 完全指南涵蓋完整生態系。逐步教學涵蓋格式。設計原則涵蓋手藝。這篇文章涵蓋環境和工作流。四塊合在一起，帶你從「我有一個 SKILL.md」到「我有一個能用的 skill」。