這是Bubble2026年的第41篇更新。

我感覺今年以來最火的東西非Skills莫屬了。

無論是OpenClaw、Claude Code再到最近熱度很高的Hermes Agent 都離不開Skills。

所以比起追逐一個又一個熱點，我覺得不如先來看看如何寫好Skills。

最近看到Google DeepMind 研究員 Philipp Schmid 總結(jié)了 8 個他在大量實踐中積累的寫Skills技巧，還蠻有用的，結(jié)合我自己這段時間的使用經(jīng)驗，翻譯轉(zhuǎn)述給大家。

Section 01先搞清楚 Skill 到底是什么

一個 Skill 本質(zhì)上就是一個文件夾，核心是一個SKILL.md文件，其他的都是可選的：

CodeSTRUCTURE

my-skill/ 

├── SKILL.md    ← 唯一必須的文件 

├── scripts/    ← 可復(fù)用的腳本代碼 

├── references/ ← Agent 按需讀取的參考文檔 

└── assets/     ← 模板、圖片等輸出用的資源

一個 Skill 由3 層組成：

?名稱和描述（Frontmatter）：每次都會加載到 Prompt 中，告訴 Agent什么時候該用這個 Skill

?SKILL.md 正文：Skill 被觸發(fā)后才加載的 Markdown 指令，告訴 Agent怎么干活

?附屬文件（可選）：scripts/、references/、assets/ 文件夾里的輔助資源

這里還有一個很重要的認(rèn)知，Skill 其實分兩種：

?能力型 Skills：彌補(bǔ)模型本身做不好的事情。比如填 PDF 表單。隨著模型越來越強(qiáng)，這類 Skill 有可能會被淘汰，定期跑Benchmark就知道它還需不需要了。

?偏好型 Skills：把你自己的工作流固化下來，比如你團(tuán)隊的代碼審查流程。這類 Skill 不會過時，但需要跟你實際流程保持同步。

總結(jié)來說：能力型Skills解決模型能不能做這個任務(wù)，偏好型Skills解決模型按不按我的工作流程來做。

Section 02描述寫不好，一切白搭

SKILL.md 里的 description 就是觸發(fā)器。

如果把描述寫得太模糊，Agent 不知道啥時候該激活這個 Skill。寫得太寬泛，每次請求都會觸發(fā)，直接干擾正常工作流程。

你需要同時說清楚兩件事：

這個 Skill 干什么+什么時候該用它。

舉個例子：

太模糊的寫法："幫助處理文檔"

具體且可執(zhí)行的寫法："創(chuàng)建、編輯和分析 .docx 文件，適用于修訂追蹤、批注、格式化或文本提取"

太模糊的寫法："API 助手"

具體且可執(zhí)行寫法："當(dāng)需要編寫調(diào)用 Gemini API 的代碼時使用，支持文本生成、多輪對話、圖像生成或流式傳輸"

Philipp 說他見過僅僅改了 description，效果就提升了 50%的案例。

Section 03寫指令，不要寫文章

Agent 很聰明，你要做的是告訴它那些它還不知道的事情。

研究表明，過長的、塞了太多上下文的指令反而會讓性能下降。

幾個核心原則：

用指令式語言，別用描述式語言

? 不好的例子："Interactions API 是推薦的方式。"（這是知識，Agent 不會基于它行動）

? 好的示例："始終使用 interactions.create()"（這是指令，Agent 會照做）

用示例開頭，別用大段解釋

?5 行代碼示例 > 5 段文字解釋

解釋為什么

? 當(dāng)一條規(guī)則很重要時，說清楚原因："使用 model X，model Y 已棄用并且會返回錯誤"。這樣 Agent 能舉一反三，而不是死記硬背。

別過擬合

?不要為了讓你手頭那 3 個測試 Prompt 通過就反復(fù)微調(diào)。好的 Skill 應(yīng)該在上百萬次調(diào)用中都穩(wěn)定有效。

Section 04保持精簡

別把所有東西都塞進(jìn)一個文件里。

Agent 是分層加載信息的：

1.始終加載：SKILL.md 的 Frontmatter（名稱 + 描述）

2.觸發(fā)后加載：SKILL.md 的正文（建議控制在 500 行以內(nèi)）

3.按需加載：reference 文件、腳本、資源

如果你的 Skill 涵蓋多個主題，拆分成多個 reference 文件。Agent 只會讀它需要的那個，這樣能把上下文窗口留給真正重要的任務(wù)。

小技巧：如果某個 reference 文件超過 500 行，在文件頂部加一個帶行號提示的目錄，方便 Agent 快速定位。

Section 05給 Agent 適當(dāng)?shù)淖杂啥?br/>

寫 Skill 最常見的錯誤，就是把它變成一份逐步執(zhí)行的操作手冊。

"第一步：讀取文件。第二步：解析 JSON。第三步：提取字段..."

當(dāng)你把每一步都寫死了，Agent 就喪失了自適應(yīng)、糾錯和找到更優(yōu)方案的能力。

描述你想要什么結(jié)果，而不是通往結(jié)果的路徑。

告訴 Agent 目標(biāo)：

? 不要說："步驟1：讀取配置文件。步驟2：找到數(shù)據(jù)庫URL。步驟3：更新端口號。步驟4：寫回文件。"

? 要說："將配置文件中的數(shù)據(jù)庫端口更新為用戶指定的值。"

給約束，不給流程：

? 不要說："步驟1：創(chuàng)建分支。步驟2：修改代碼。步驟3：跑測試。步驟4：提PR。"

? 要說："提 PR 之前必須跑通測試。永遠(yuǎn)不要直接 push 到 main。"

如果某些步驟的順序真的不能亂，那你該寫腳本，而不是 Skills。

Section 06別忘了反面測試

思考一下你的 Skills不應(yīng)該在什么時候觸發(fā)。

一個 description 寫成"處理任何編程任務(wù)"的 Skill，會在每次請求時都搶著出來干活，直接打亂你的工作流。

正確做法是："處理 PDF 文件時使用。不要用于普通文檔編輯、電子表格或純文本文件。"

你需要同時測試應(yīng)該觸發(fā)的場景和不應(yīng)該觸發(fā)的場景。

不做反面測試，你的 Skill 只會朝一個方向優(yōu)化，最終變成一個誤觸狂魔。

Section 07發(fā)布前一定要測試

別寫完就直接發(fā)出去。Agent 的輸出是非確定性的，每次跑出來的結(jié)果可能都不一樣，所以測一次是遠(yuǎn)遠(yuǎn)不夠的。

具體怎么做：

1.手動跑幾次，用不同的 Prompt 試?？此谀睦锍鲥e：是否假設(shè)某個依賴存在？是否跳過了步驟？

2.定義清楚成功的標(biāo)準(zhǔn)是什么樣，并且要可衡量。輸出能編譯嗎？用了對的 API 嗎？按步驟走了嗎？評估結(jié)果，不是評估路徑。

3.準(zhǔn)備 10-20 個測試 Prompt?；旌先悾篠kill 應(yīng)該處理的、Skill 應(yīng)該忽略的、以及刁鉆的邊界情況。每個 Prompt 都應(yīng)該有獨立的成功標(biāo)準(zhǔn)。

4.跑多次。每個 Prompt 跑 3-5 次，看分布結(jié)果，而不是單次通過/失敗。

5.隔離每次測試。用干凈的環(huán)境跑每一次測試，上下文殘留會掩蓋真實的問題。

6.出了問題先改 description。大部分問題出在觸發(fā)條件上，而不是指令本身。

Section 08知道什么時候該退役一個 Skill

把 Skills 關(guān)掉，重新讓Agent跑一遍你的Benchmark。

如果不用這個 Skills 也能通過，那就說明模型已經(jīng)吸收了這個 Skills 的價值，它就不再需要了。大膽扔掉它。

這一點對能力型 Skills尤其重要。模型在不斷進(jìn)步，差距在不斷縮小。你去年寫的那個 Skills，說不定今天已經(jīng)是多余的了。

End Note

這 8 個技巧看起來都不復(fù)雜，但如果你認(rèn)真對照自己寫過的 Skills 復(fù)盤一遍，大概率會發(fā)現(xiàn)好幾個踩過的坑。

我自己的總結(jié)就是：寫 Skills 跟之前寫 Prompt 其實是一脈相承的。

最核心永遠(yuǎn)是那幾件事：

說清楚意圖、給足夠的上下文、別過度約束、持續(xù)迭代測試。

以及，追逐下一個熱點Agent，不如先琢磨一下如何寫好自己手里的Skills。

歡迎評論區(qū)交流你寫好Skills的小技巧～