主題: AI agents

Agent Skill 不是長 Prompt：值得留下的，是可驗證工作流

Agent Skills 正在快速普及，但多一份 SKILL.md 不等於多一項能力。真正有用的 skill，應該保存決策、檢查點與可重複執行的流程。

最近看 Agent Skills 生態，很容易同時得到兩種完全相反的印象。

一邊是 daily.dev 上的介紹：Skill 把程序知識包成可按需載入的資料夾，正在成為跨工具的開放格式。另一邊，Reddit 上也出現很直接的質疑：為什麼網路上的 Claude Code skills 看起來都沒什麼用？

兩邊其實都說對了。

Agent Skills 解決了一個真的問題，但 SKILL.md 這個檔案本身不會讓普通建議突然變專業。它只是讓 agent 知道：什麼時候該載入哪一套做事方法。 至於那套方法值不值得載入，仍然要看裡面有沒有保存真正稀缺的東西。

格式解決的是「怎麼載入」，不是「內容好不好」

依照 Agent Skills 官方規格，一個 skill 最少只需要一個帶有 name、description 與 Markdown 內容的 SKILL.md。需要時，還可以附帶：

• scripts/：可執行程式
• references/：參考資料
• assets/：模板或其他資源

它的核心設計是 progressive disclosure：agent 啟動時只看名稱與描述；判斷任務相關後，才讀完整指示；腳本與參考資料則等真正需要時再載入。

這套設計很合理。它避免每次對話都把所有規則塞進 context，也讓同一套流程可以進版控、被分享、被更新。

但它只規範容器，沒有替內容把關。把「請寫乾淨的程式碼、使用有意義的變數名稱、記得測試」放進 skill，仍然只是把模型本來就知道的常識再念一次。

最沒價值的 skill：教模型它早就知道的事

很多公開 skill 像一篇寫給初學者的教學文章：解釋什麼是 accessibility、什麼是 REST、React component 應該怎麼拆。文章本身可能沒錯，但模型訓練資料裡通常早已有大量同類內容。

這種 skill 常見三個問題：

1. 觸發範圍太大：只要碰到 frontend 或 database 就載入，平白吃掉 context。
2. 只有形容詞，沒有判斷：要求「robust、production-ready、best practice」，卻沒說如何判定完成。
3. 沒有環境差異：忽略專案實際 scripts、部署方式、相容性與失敗條件。

它們讓 agent 多讀了字，卻沒有少猜任何一步。

真正值得保存的，通常不是公開知識，而是你在工作裡反覆付過學費的細節：哪個檢查不能省、哪種狀態必須停、哪個來源才是準的、做完要看到什麼證據。

好 skill 保存的是決策點與煞車

想像一個發布流程。差的版本會寫：「檢查程式碼、建立 commit、部署並確認網站正常。」每個 agent 都能生成這句話，但它沒有解決真正容易出錯的地方。

比較有用的版本會像這樣：

---
name: safe-release
description: Use when publishing a completed change to the current release branch.
---

1. Read repository instructions and existing deploy scripts.
2. Stop if the worktree contains unrelated changes or conflicts.
3. Run the smallest repository-defined check covering the change.
4. Stage only files created or changed by this task.
5. Use the existing deploy path; do not create a second one.
6. Verify the production URL contains the expected release marker.

這些步驟不高深，價值卻很實際：它們把 agent 最容易跳過的「無聊關卡」固定下來。Skill 的作用不是讓模型突然懂部署，而是讓它在每次部署時都記得先看髒工作樹、只 stage 本次檔案，最後拿正式環境的證據。

近期論文 Authoring Agent Skills: A Software-Engineering Approach 把 skill 視為軟體工件：description 是決定是否觸發的介面，正文與附帶資源則是實作。這個類比很有用，因為它迫使我們問兩個比「內容寫得完整嗎」更重要的問題：

• 該用時，agent 會不會選到它？
• 不該用時，它會不會亂入？

兩種情境都測過，才算真的驗證過一個 skill。

能確定的部分，交給程式；需要判斷的部分，才留給模型

Anthropic 介紹 Agent Skills 的原始文章 特別指出，有些工作更適合傳統程式執行。這條界線很重要。

如果一個步驟能用 parser、schema validator、測試或 exit code 判定，就不要用一大段自然語言拜託模型「仔細確認」。例如：

• frontmatter 格式是否合法：交給 validator
• 產物是否缺檔：交給 script
• build 是否成功：看 exit code
• 變更是否符合需求：才由 agent 結合上下文判斷

不過也不用為了「看起來像工程」而替每個 skill 寫腳本。只有當同一段確定性操作會重複、容易做錯，或人工展開會浪費大量 token 時，腳本才值得存在。一行既有指令能解決，就用那一行。

Skill 是建議，不是安全邊界

Skill 會影響 agent 的選擇，但不能保證 agent 一定照做。更不能因為 SKILL.md 裡寫了「不要讀 secrets」，就把它當成權限控管。

這在安裝第三方 skill 時尤其重要。Skill 可以附帶 Python、Shell 或 JavaScript，執行時通常繼承 agent 當下擁有的檔案與網路權限。Red Hat 的 Agent Skills 安全分析 因此建議把它當供應鏈問題處理：審查來源與腳本、限制檔案權限、隔離執行環境、縮小網路與工具權限，也不要把憑證寫進 skill。

官方規格雖然已有實驗性的 allowed-tools 欄位，但並非所有 agent 都支援。真正的安全邊界仍應放在 sandbox、作業系統權限、人工批准與平台控制層，而不是自然語言裡。

開放格式不等於到處表現一樣

Agent Skills 的開放格式讓資料夾結構與核心 metadata 可以攜帶到不同工具，這是很好的起點。但「讀得懂」和「跑得一樣」仍是兩回事。

Skill 只要依賴某個 agent 專屬工具、特定目錄、未宣告的 binary，或一組隱含權限，移到別處就可能失效。想要重用，至少要把環境需求寫清楚，使用相對路徑，並在缺少必要工具時提早失敗。跨工具相容性應該是測試結果，不是看到 .md 就自動成立的假設。

發布 skill 前，我會先問這七題

1. 這個問題是否真的重複發生？只用一次的需求，不需要 skill。
2. description 是否同時說清楚「做什麼」與「何時用」？
3. 內容是否保存了模型不知道的流程、限制或組織脈絡？
4. 是否列出必須停止、批准或回報的條件？
5. 能確定判斷的步驟，是否已有最小可執行檢查？
6. 第三方腳本、權限與網路需求是否看得見、可限制？
7. 是否測過該觸發與不該觸發的案例？

如果七題裡大半答不出來，先不要發布。那可能是一篇文件、一條專案規則，或一次性的 prompt，沒必要硬包成 skill。

結論：Skill 應該像疤，不該像百科全書

好的 skill，通常來自一次真實失敗：漏跑 migration、覆蓋別人的變更、部署後沒驗證、把不可信輸入當成指令。團隊把那次代價整理成觸發條件、流程、煞車與證據，下一次 agent 就不必重踩。

壞的 skill 則只是把一篇技術文章塞進 context，然後期待模型因此變得更資深。

Agent Skills 值得用，但判斷標準不該是「寫了多少規則」，而是：它有沒有讓 agent 少猜一步、少漏一個關卡，並留下可驗證的結果。

外部參考連結

• Agent Skills 官方規格
• Anthropic：Equipping agents for the real world with Agent Skills
• daily.dev：What are Agent Skills and How Agents Use Them?
• Reddit：Why are all the Claude Code skill files I see online completely pointless?
• Authoring Agent Skills: A Software-Engineering Approach
• Red Hat：Agent Skills: Explore security threats and controls