上周我在調(diào)一個(gè)多步執(zhí)行的工作流被一個(gè)問題卡了很久每次給Agent換一個(gè)新任務(wù)就得把一堆說(shuō)明、參數(shù)格式、處理邏輯全部塞進(jìn)系統(tǒng)提示里塞完發(fā)現(xiàn)指令之間互相打架輸入稍微變一變輸出就跑偏。后來(lái)我把這套東西完全拆掉換成基于“技能”的組織方式——也就是 agent-skills 的思路問題才算真正解決。這篇文章我會(huì)把技能的構(gòu)成、描述方法、目錄組織、運(yùn)行時(shí)加載和避坑經(jīng)驗(yàn)一次性說(shuō)清楚。先明確一件事我這里說(shuō)的 agent-skills不是某一家平臺(tái)的專屬功能而是一種通用的Agent能力組織范式。核心思想很簡(jiǎn)單——把Agent需要具備的每一種能力抓網(wǎng)頁(yè)、提數(shù)據(jù)、寫摘要、發(fā)消息封裝成一個(gè)獨(dú)立的“技能”每個(gè)技能自帶說(shuō)明書、示例代碼和運(yùn)行腳本Agent在對(duì)話中按需發(fā)現(xiàn)、加載和執(zhí)行。你可以把它理解成給Agent裝了一套隨取隨用的工具箱而不是把所有工具焊死在桌子上。這套思路適合誰(shuí)如果你手頭有一個(gè)基于大模型開發(fā)的Agent并且在為“指令越來(lái)越長(zhǎng)、任務(wù)越來(lái)越雜、復(fù)用越來(lái)越難”頭疼那這篇文章應(yīng)該能給你一套可以立刻動(dòng)手的方案。下面按真實(shí)落地順序來(lái)拆解。1. 技能在Agent體系里的真實(shí)位置它不是插件也不是工具函數(shù)1.1 單一Prompt為什么走不通我把所有指令堆進(jìn)系統(tǒng)提示的那段時(shí)間系統(tǒng)提示從幾百字漲到幾千字效果不升反降。原因并不神秘大模型處理長(zhǎng)上下文時(shí)注意力會(huì)被稀釋。你把“如何抓網(wǎng)頁(yè)”“如何清洗數(shù)據(jù)”“如何按模板生成周報(bào)”這些規(guī)則全部鋪在模型面前它在執(zhí)行具體任務(wù)時(shí)反倒不知道該重點(diǎn)參考哪一段。更麻煩的是參數(shù)沖突。比如我在系統(tǒng)提示里規(guī)定“日期統(tǒng)一用YYYY-MM-DD格式”另一個(gè)模塊的示例里又寫了“2024年1月5日”模型遇到類似矛盾時(shí)會(huì)隨機(jī)發(fā)揮你根本沒法穩(wěn)定復(fù)現(xiàn)同一個(gè)任務(wù)的輸出。把指令抽離成獨(dú)立技能后沖突的指令不再同時(shí)出現(xiàn)每次只把相關(guān)的那份說(shuō)明注入上下文問題直接從根上消掉了。1.2 技能、工具函數(shù)、插件的邊界劃分很多朋友會(huì)問這不就是函數(shù)調(diào)用Function Calling嗎早期我也這么以為但實(shí)際對(duì)比下來(lái)兩者粒度完全不同。對(duì)比維度工具函數(shù)Function技能Skill插件Plugin載體單個(gè)函數(shù) 參數(shù)Json Schema目錄 SKILL.md 腳本整套擴(kuò)展包觸發(fā)方式模型按函數(shù)名調(diào)用模型按技能描述匹配用戶手動(dòng)安裝啟用包含內(nèi)容只能做一次原子操作包含說(shuō)明、示例、模板、失敗處理可能包含多個(gè)技能和運(yùn)行時(shí)復(fù)用粒度細(xì)中粗維護(hù)成本低中高大致可以這樣理解函數(shù)是“手腳”技能是“一套完整的動(dòng)作”插件是“打包好的整套動(dòng)作集”。技能在函數(shù)之上多了一層“說(shuō)明書”在插件之下又比整包擴(kuò)展輕盈得多。我要實(shí)現(xiàn)“抓取某網(wǎng)頁(yè)并提取核心觀點(diǎn)”函數(shù)只能保證“給一個(gè)URL返回HTML”而技能能保證“根據(jù)URL抓取、清洗正文、提煉觀點(diǎn)、按格式輸出”——它把模型需要知道的前置知識(shí)、處理邏輯、輸出格式全部打包了。1.3 技能庫(kù)帶來(lái)的三個(gè)核心價(jià)值第一是上下文減負(fù)。Agent不需要在每次對(duì)話里攜帶全部指令只需要攜帶一份技能索引每個(gè)技能一句話描述用到哪個(gè)加載哪個(gè)。第二是能力資產(chǎn)化。一個(gè)技能調(diào)試好了換一個(gè)Agent、換一個(gè)項(xiàng)目還能繼續(xù)用能力變成了可積累的文件資產(chǎn)。第三是多Agent共享。團(tuán)隊(duì)多個(gè)Agent共用一套技能庫(kù)行為一致性會(huì)大幅提升不用每個(gè)Agent里復(fù)制粘貼同一套Prompt。這三個(gè)價(jià)值是我在實(shí)際切換后感受最明顯的部分。整個(gè)系統(tǒng)的可維護(hù)性比“單一長(zhǎng)Prompt 一堆散裝函數(shù)”高出一個(gè)數(shù)量級(jí)。2. 技能描述SKILL.md才是成敗關(guān)鍵怎么寫才能被穩(wěn)定觸發(fā)技能能不能被正確調(diào)用七成功力在描述文件里。模型讀技能不是像人一樣掃一眼“哦這個(gè)大概是干嘛的”它是在意圖匹配的邊界上做決策。描述寫得含糊模型就會(huì)在相似技能之間猶豫描述寫得太長(zhǎng)重要信息又被淹沒。2.1 先寫觸達(dá)條件再寫功能說(shuō)明我見過(guò)大量技能描述是這么開頭的本技能用于數(shù)據(jù)處理。這等于沒寫。模型看到一個(gè)網(wǎng)頁(yè)抓取任務(wù)時(shí)無(wú)法判斷“數(shù)據(jù)處理”這個(gè)詞和當(dāng)前請(qǐng)求是否匹配。我把寫法改成下面這種當(dāng)用戶需要從一個(gè)或多個(gè)網(wǎng)頁(yè)URL中提取正文內(nèi)容時(shí)使用本技能。典型場(chǎng)景包括抓取新聞頁(yè)面、提取產(chǎn)品描述、采集博客文章。如果用戶需要的是結(jié)構(gòu)化字段如價(jià)格、評(píng)論數(shù)請(qǐng)優(yōu)先選用其他技能。注意這里的關(guān)鍵動(dòng)作明確觸發(fā)條件“當(dāng)……時(shí)使用”給出一組典型場(chǎng)景幫助模型判斷匹配度再給出排除條件“如果……請(qǐng)優(yōu)先選用其他技能”。模型做意圖路由時(shí)靠的就是這些可判斷的信號(hào)詞。2.2 輸入輸出約定要有格式原型描述文件里光說(shuō)“輸出提取結(jié)果”是不夠的模型不知道提取結(jié)果長(zhǎng)什么樣。必須給一個(gè)具體的輸出結(jié)構(gòu)越具體越好。我自己常用的SKILL.md里輸出約定長(zhǎng)這樣輸出格式 { url: 原文URL, title: 頁(yè)面標(biāo)題, content: 清洗后的正文純文本最長(zhǎng)不超過(guò)5000字, word_count: 正文字?jǐn)?shù), extracted_at: ISO8601格式的當(dāng)前時(shí)間 }同時(shí)還要規(guī)定異常情況下的輸出異常處理 - 頁(yè)面無(wú)法訪問時(shí)在content字段返回空字符串并在error字段描述原因 - 頁(yè)面沒有正文內(nèi)容時(shí)同樣返回空content不要憑空編造內(nèi)容這個(gè)細(xì)節(jié)我栽過(guò)跟頭。有一次技能描述里只寫了“提取正文”模型在頁(yè)面內(nèi)容為空時(shí)竟然開始編造“本頁(yè)面暫無(wú)內(nèi)容”的假正文后來(lái)加上明確的異常輸出規(guī)定情況才好轉(zhuǎn)。模型在決策時(shí)是需要邊界感的你給它的邊界越清晰它發(fā)揮越穩(wěn)定。2.3 示例是給模型看的電梯測(cè)試好的SKILL.md里一定有一到兩個(gè)輸入輸出對(duì)。模型在運(yùn)行時(shí)會(huì)把當(dāng)前請(qǐng)求和示例做隱式的相似度匹配示例的形態(tài)直接決定了模型對(duì)技能的“直覺”。下面是一個(gè)簡(jiǎn)短的示例寫法示例 用戶輸入請(qǐng)幫我抓取 https://example.com/news/2024/01/agent-trends 這篇頁(yè)面 技能輸出{ url: https://example.com/news/2024/01/agent-trends, title: Agent Trends in 2024, content: ……正文純文本……, word_count: 1203, extracted_at: 2025-01-14T10:32:00Z }示例不需要多一個(gè)示忙場(chǎng)景足以。關(guān)鍵是這個(gè)輸入要盡量貼近真實(shí)使用不要用抽象的空殼數(shù)據(jù)否則模型學(xué)不到匹配信號(hào)。2.4 從一次誤調(diào)用看描述精修的完整過(guò)程我在一個(gè)技能庫(kù)里跑過(guò)這樣的問題。技能A叫“提取正文”描述是“從網(wǎng)頁(yè)中提取文章內(nèi)容”技能B叫“抽取實(shí)體”描述是“從網(wǎng)頁(yè)中抽取人名、機(jī)構(gòu)名、時(shí)間”。有一次用戶輸入“幫我從這篇新聞里提煉出講了什么”模型沒有選擇技能A反而調(diào)了技能B輸出一堆實(shí)體列表。根因在于兩條描述都用了“從網(wǎng)頁(yè)中提取”的句式模型在語(yǔ)義空間里把兩個(gè)技能的距離拉近了。修復(fù)方式是在技能A描述尾部加上反向觸發(fā)詞如果用戶希望獲得的是語(yǔ)義總結(jié)、觀點(diǎn)提煉、事件梳理而不是簡(jiǎn)單抽取字段請(qǐng)勿使用本技能。同時(shí)給技能B也加了一句“僅當(dāng)用戶明確要求提取結(jié)構(gòu)化實(shí)體時(shí)使用”。這種雙向邊界一劃誤調(diào)用率立刻下來(lái)。所以描述文件里加一個(gè)“When NOT to use”小節(jié)不是冗余是必要配置。3. 技能庫(kù)的組織形式與運(yùn)行時(shí)加載不是堆一堆目錄那么簡(jiǎn)單3.1 技能目錄與命名規(guī)范技能在文件系統(tǒng)里應(yīng)該遵守一個(gè)規(guī)則一個(gè)技能一個(gè)目錄目錄內(nèi)標(biāo)準(zhǔn)文件布局。我的項(xiàng)目里一般長(zhǎng)這樣skills/ ├── fetch_and_extract/ │ ├── SKILL.md │ ├── src/ │ │ ├── fetcher.py │ │ └── cleaner.py │ ├── requirements.txt │ └── tests/ │ └── test_fetcher.py ├── summarize/ │ ├── SKILL.md │ ├── src/ │ │ └── summarizer.py │ └── requirements.txt為什么這樣設(shè)計(jì)因?yàn)镾KILL.md承載“給模型看的說(shuō)明書”src承載“給解釋器執(zhí)行的Python代碼”requirements.txt承載“運(yùn)行這個(gè)技能需要的外部依賴”tests承載“這個(gè)技能的回歸驗(yàn)證”。這樣拆分模型層、代碼層、依賴層、驗(yàn)證層互不干擾。技能目錄命名我堅(jiān)持用小寫字母加下劃線避免不同操作系統(tǒng)之間的大小寫敏感差異。3.2 技能元信息metadata是建立索引的基礎(chǔ)除了SKILL.md我還會(huì)給每個(gè)技能寫一個(gè)輕量的元信息文件用來(lái)支持加載器的快速索引。格式用YAML或JSON都可以關(guān)鍵在于字段設(shè)計(jì)。字段有經(jīng)驗(yàn)講究這字段是給加載器做能力索引用的不是給模型看的完整說(shuō)明書。加載器啟動(dòng)時(shí)只需要掃元信息就能生成一份“技能地圖”等模型選中某個(gè)技能后再讀取完整的SKILL.md注入上下文。這種兩級(jí)加載策略是控制上下文開銷的關(guān)鍵手段。3.3 技能加載器的核心工作流程技能加載器實(shí)際上承擔(dān)了四個(gè)環(huán)節(jié)的工作。第一步是掃描注冊(cè)。啟動(dòng)時(shí)遍歷技能根目錄讀取每個(gè)技能的元信息文件檢查目錄結(jié)構(gòu)是否合法依賴文件是否存在。不合法或依賴缺失的技能不能直接丟棄而是標(biāo)記為“不可用”并記錄原因。第二步是構(gòu)建索引。把技能名稱、觸發(fā)場(chǎng)景、能力類型匯總成簡(jiǎn)短文本。這里有個(gè)原則每個(gè)技能在索引里只保留不超過(guò)30個(gè)字的核心描述這樣即使有20個(gè)技能索引總長(zhǎng)度也能控制在幾百字以內(nèi)。第三步是按需注入。模型在對(duì)話中根據(jù)索引選擇了某個(gè)技能后加載器把完整的SKILL.md讀到上下文里。我的實(shí)現(xiàn)里用的是會(huì)話級(jí)緩存同一個(gè)會(huì)話內(nèi)第二次使用同一個(gè)技能時(shí)不再重復(fù)讀取直接復(fù)用。第四步是執(zhí)行與回寫。模型輸出結(jié)構(gòu)化調(diào)用指令后執(zhí)行器啟動(dòng)獨(dú)立的子進(jìn)程或容器來(lái)運(yùn)行技能代碼結(jié)束后把stdout狀態(tài)和執(zhí)行結(jié)果返回給模型。這四步走完一次技能調(diào)用才算完整。很多自建技能的方案只做到了前兩步后面執(zhí)行和回寫完全缺失導(dǎo)致技能只能“看”不能“用”。3.4 多Agent共享時(shí)的權(quán)限與資源隔離如果多個(gè)Agent共用同一個(gè)技能庫(kù)還要考慮隔離問題。比如“發(fā)送郵件”這個(gè)技能不能允許所有Agent無(wú)限制調(diào)用再比如“讀取本地文件”這個(gè)技能如果不加限制AgentA就能看到AgentB的工作目錄。我的處理方式是在運(yùn)行時(shí)加載器里引入作用域scope概念。每個(gè)Agent實(shí)例綁定一個(gè)允許訪問的技能名單和資源白名單執(zhí)行器在啟動(dòng)子進(jìn)程時(shí)通過(guò)環(huán)境變量傳入白名單技能代碼內(nèi)部只能訪問白名單內(nèi)的路徑。同時(shí)給技能執(zhí)行加超時(shí)時(shí)間我用的是30秒超時(shí)加5MB輸出大小上限。一個(gè)Agent被惡意或誤用代碼拖住不影響其他Agent的正常運(yùn)行。這套機(jī)制實(shí)現(xiàn)不算復(fù)雜但在多Agent場(chǎng)景里屬于必需品。4. 從零跑通一個(gè)“信息收集內(nèi)容產(chǎn)出”技能庫(kù)完整實(shí)操4.1 一個(gè)具體場(chǎng)景的需求拆解為了把上面這些概念串起來(lái)我以一個(gè)真實(shí)小項(xiàng)目為例讓Agent自動(dòng)完成“瀏覽一批新聞頁(yè)面→提取文章要點(diǎn)→生成一份簡(jiǎn)報(bào)”。這個(gè)流程可以拆成三個(gè)技能fetch_and_extract抓取并清洗網(wǎng)頁(yè)正文summarize對(duì)正文做要點(diǎn)提煉report_builder把多條要點(diǎn)按模板拼接成簡(jiǎn)報(bào)每個(gè)技能獨(dú)立可復(fù)用尤其是 fetch_and_extract 和 summarize以后在其他任務(wù)里還能單獨(dú)拿出來(lái)用。4.2 搭建技能工程的過(guò)程先寫 fetch_and_extract 的 SKILL.md描述部分用第二節(jié)講的方法# fetch_and_extract ## 觸發(fā)條件 當(dāng)用戶需要從一個(gè)或多個(gè)URL獲取網(wǎng)頁(yè)內(nèi)容并提取正文時(shí)使用。 ## 輸入?yún)?shù) - url必填需要抓取的網(wǎng)頁(yè)地址 - max_words可選正文截?cái)嚅L(zhǎng)度默認(rèn)5000 ## 輸出格式 { url: ..., title: ..., content: ..., word_count: 123, error: } ## 示例 用戶輸入抓取 https://example.com/news/1 技能輸出{url:https://example.com/news/1, title:Example News, content:..., word_count:800, error:} ## 異常處理 頁(yè)面不可訪問時(shí)content為空error字段描述原因。不得編造正文內(nèi)容。然后在 src/fetcher.py 里寫抓取和清洗邏輯。技術(shù)要點(diǎn)是使用 requests BeautifulSoup對(duì)抓到的HTML先做標(biāo)題抽取再摘除script/style/nav等噪音標(biāo)簽最后提取正文段落。用 fake_useragent 避免部分簡(jiǎn)單反爬攔截加上超時(shí)和重試機(jī)制這些細(xì)節(jié)網(wǎng)上都能查到關(guān)鍵是記得把異常結(jié)構(gòu)化返回給模型。summarize 技能的寫法和它類似區(qū)別在輸入是正文文本輸出是分條要點(diǎn)列表。report_builder 技能則是讀取多條摘要數(shù)據(jù)按既定模板生成Markdown格式的周報(bào)。4.3 在Agent對(duì)話里讓模型自主選擇技能技能跑通后需要在Agent主流程里把它們組織起來(lái)。我的實(shí)現(xiàn)里系統(tǒng)提示只保留一份簡(jiǎn)短索引可調(diào)用技能 - fetch_and_extract抓取網(wǎng)頁(yè)正文 - summarize對(duì)正文生成要點(diǎn)摘要 - report_builder將多條摘要組裝成簡(jiǎn)報(bào)模型判斷當(dāng)前任務(wù)需要哪個(gè)技能后輸出一個(gè)結(jié)構(gòu)化調(diào)用指令例如{skill: fetch_and_extract, parameters: {url: https://example.com/news/1}}加載器解析后執(zhí)行代碼把結(jié)果返回給模型。模型再據(jù)此決定是否調(diào)用下一個(gè)技能。整個(gè)過(guò)程里模型上下文只出現(xiàn)了當(dāng)前相關(guān)技能說(shuō)明而不是全部指令。我實(shí)際跑下來(lái)同樣任務(wù)的行為穩(wěn)定性比之前長(zhǎng)Prompt方案好很多。4.4 技能執(zhí)行失敗時(shí)的降級(jí)回退設(shè)計(jì)任何技能都可能失敗設(shè)計(jì)時(shí)必須預(yù)留降級(jí)邏輯。我在每個(gè)技能的執(zhí)行結(jié)果里統(tǒng)一加入 exit_code 字段0表示成功非0表示失敗。模型看到失敗結(jié)果后可以決定是更換參數(shù)重試還是改用其他技能。比如 fetch_and_extract 返回“目標(biāo)站點(diǎn)超時(shí)”模型可以選擇稍后重試也可以直接讀取用戶提供的備用數(shù)據(jù)源。更復(fù)雜一點(diǎn)的降級(jí)是我在 summarize 技能失敗時(shí)會(huì)觸發(fā) report_builder 直接使用原文第一段作為摘要占位。這看起來(lái)微不足道但在真實(shí)業(yè)務(wù)流程里一個(gè)不會(huì)因?yàn)樾∈【椭袛嗾w流程的Agent才具備可用性。5. 真正跑起來(lái)才遇到的坑技能沖突、描述誤觸與上下文膨脹5.1 相似技能的“選擇困難癥”與解法第一節(jié)和第二節(jié)都提到了技能描述相似導(dǎo)致的誤調(diào)用這里再展開一種更隱蔽的情況兩個(gè)技能A和B功能確實(shí)有重疊且用戶請(qǐng)求落在重疊區(qū)域。比如“抓取正文”和“抓取頁(yè)面所有鏈接”兩個(gè)技能遇到“幫我看看這個(gè)頁(yè)面上有哪些內(nèi)容”時(shí)模型可能隨機(jī)選擇。解法是人為制造差異化信號(hào)。我在技能A的觸發(fā)條件開頭直接寫入“當(dāng)用戶提到提取正文、文章內(nèi)容、閱讀全文等詞匯時(shí)”技能B則寫“當(dāng)用戶提到鏈接、URL列表、外鏈等詞匯時(shí)”。關(guān)鍵詞信號(hào)比模糊的意圖描述可靠得多。如果一個(gè)技能不能被兩個(gè)以上關(guān)鍵詞唯一觸發(fā)說(shuō)明技能邊界劃得有問題應(yīng)當(dāng)合并或拆分。5.2 技能之間的依賴沖突與環(huán)境隔離這是自建技能庫(kù)時(shí)最容易被低估的問題。技能A用requests2.28技能B必須用requests2.31如果都跑在同一個(gè)Python環(huán)境里要么一起升級(jí)要么互相踩依賴。我在方案里讓每個(gè)技能目錄自帶 requirements.txt并在執(zhí)行階段使用虛擬環(huán)境隔離。實(shí)現(xiàn)方式并不復(fù)雜執(zhí)行器為每個(gè)技能創(chuàng)建 .venv-{skill_id} 的虛擬環(huán)境安裝依賴后運(yùn)行如果虛擬環(huán)境已存在直接復(fù)用。首次安裝確實(shí)會(huì)慢幾秒但換來(lái)的是技能之間的徹底隔離。對(duì)于依賴較重或多語(yǔ)言技能可以考慮直接切到容器執(zhí)行——更重但更干凈。5.3 SKILL.md過(guò)長(zhǎng)引起的上下文膨脹技能說(shuō)明不是越詳細(xì)越好。我在一次調(diào)試中把SKILL.md寫到了2000多字結(jié)果單個(gè)技能加載后上下文窗口被吃掉一大截對(duì)話歷史反而被擠壓。經(jīng)驗(yàn)值是單個(gè)SKILL.md控制在800字以內(nèi)。超出部分盡可能放到src目錄下的參考文件里描述文件只保留觸發(fā)條件、輸入輸出、異常處理、一條示例。實(shí)現(xiàn)上還可以給加載器加一個(gè)按需讀取機(jī)制初始化時(shí)只讀取描述文件技能代碼源碼不進(jìn)入上下文只在執(zhí)行時(shí)由解釋器加載。5.4 技能版本管理改一行描述引發(fā)的連鎖反應(yīng)技能描述和代碼一樣會(huì)演化但它的影響會(huì)更隱蔽。我改動(dòng)過(guò)一個(gè)技能的觸發(fā)條件加了兩個(gè)新關(guān)鍵詞結(jié)果當(dāng)天所有類似請(qǐng)求開始優(yōu)先命中它另一個(gè)技能的調(diào)用量直線下降下游流程輸出風(fēng)格整個(gè)變了。所以現(xiàn)在我對(duì)技能目錄做版本管理元信息文件里保留 version 字段遵循語(yǔ)義化版本號(hào)。描述改動(dòng)屬于行為變化至少升Minor版本只改示例或微調(diào)參數(shù)說(shuō)明升Patch版本。改動(dòng)后在測(cè)試集上跑一遍回歸驗(yàn)證確認(rèn)影響范圍再同步給其他依賴該技能的Agent。技能不是寫出來(lái)就完事的它需要持續(xù)打磨而這恰恰是它比普通函數(shù)調(diào)用更有價(jià)值的地方——每一次線上反饋都能沉淀回說(shuō)明文檔里讓Agent一步一步變得更聰明。跑通這套體系之后我最大的感受是你不再是為Agent編寫一次性指令而是在經(jīng)營(yíng)一套不斷演進(jìn)的能力資產(chǎn)。隨著技能庫(kù)逐漸變大新任務(wù)大概率能復(fù)用已有技能少數(shù)需要新技能的因?yàn)橛辛饲逦摹罢f(shuō)明書-代碼-驗(yàn)證”范式開發(fā)一個(gè)也很快。如果你正被長(zhǎng)Prompt和散裝工具函數(shù)折磨不用一步到位先挑一個(gè)高頻重復(fù)的任務(wù)改造成獨(dú)立技能跑順一個(gè)案例之后整個(gè)模式的價(jià)值你自然就能體會(huì)到了。