做了好一陣子大模型Agent相關(guān)的項(xiàng)目我發(fā)現(xiàn)一個(gè)特別有意思的現(xiàn)象很多人一開(kāi)始追求把工具tool做得又多又全結(jié)果模型在真實(shí)任務(wù)里頻繁選錯(cuò)工具、拼錯(cuò)參數(shù)、中途翻車。真正讓Agent“好用”的往往不是你給它多少把螺絲刀而是你教會(huì)它“怎么修好一臺(tái)機(jī)器”——這正是我最近在整理的這套 agent-skills 技能庫(kù)方案想解決的事。簡(jiǎn)單說(shuō)agent-skills 不是又一份工具清單而是一套把“單點(diǎn)能力”升級(jí)成“可復(fù)用技能”的封裝框架。它給每個(gè)技能配上元數(shù)據(jù)、參數(shù)約束、執(zhí)行鉤子、失敗恢復(fù)邏輯讓 Agent 在接到任務(wù)時(shí)像老師傅一樣“憑經(jīng)驗(yàn)干活”而不是每次從零推理。這套思路適合正在做 Agent 應(yīng)用、RAG 工作流、自動(dòng)化助手的朋友參考也適合想弄明白“技能與工具到底差在哪”的開(kāi)發(fā)者。我會(huì)把設(shè)計(jì)思路、落地代碼、踩坑實(shí)錄都攤開(kāi)講盡量讓不同基礎(chǔ)的讀者都能拿去用。1. 內(nèi)容整體設(shè)計(jì)與思路拆解1.1 為什么 Agent 需要“技能庫(kù)”而不是一堆函數(shù)先聊一個(gè)常見(jiàn)場(chǎng)景。假設(shè)你想讓 Agent 幫你“整理一篇會(huì)議紀(jì)要”你可能會(huì)給它掛上三個(gè)工具一個(gè)做語(yǔ)音轉(zhuǎn)寫(xiě)、一個(gè)調(diào)大模型做摘要、一個(gè)發(fā)郵件。模型確實(shí)能按順序調(diào)這三個(gè)工具但每次執(zhí)行都要重新理解任務(wù)、重新組織參數(shù)、重新處理中間結(jié)果。任務(wù)一多、上下文一變它就很容易在第二步忘了第三步的前提或者在參數(shù)上犯低級(jí)錯(cuò)誤。問(wèn)題不在于模型笨而在于我們只用 function calling 暴露了“零件”卻沒(méi)有給它“工序”。工具調(diào)用解決的是“單點(diǎn)動(dòng)作”技能要解決的是“會(huì)做一件事”。在 agent-skills 里一個(gè)技能內(nèi)部可以包含多個(gè)工具調(diào)用、多步狀態(tài)流轉(zhuǎn)、前置條件檢查和輸出校驗(yàn)。它像一個(gè)封裝好的黑盒模型只需要知道“這個(gè)技能能搞定會(huì)議紀(jì)要”至于內(nèi)部怎么轉(zhuǎn)寫(xiě)、怎么摘要、怎么格式化都不需要重新決策。我常用一個(gè)比喻工具是一抽屜零件技能是一套成熟工序。給 Agent 一百個(gè)零件它未必能組裝出一臺(tái)機(jī)器給它十道工序它反而能穩(wěn)定交付結(jié)果。技能庫(kù)的價(jià)值就是把“零件”按場(chǎng)景組織成“工序”并且讓模型在接到任務(wù)時(shí)能快速檢索到最合適的工序。1.2 “技能”與“工具調(diào)用”的邊界在哪里我踩過(guò)不少坑之后總結(jié)出技能和工具的幾個(gè)核心區(qū)別看下面這張表比較直觀對(duì)比維度工具Tool技能Skill粒度單點(diǎn)能力如“發(fā)HTTP請(qǐng)求”多步驟任務(wù)如“抓取網(wǎng)頁(yè)并提煉要點(diǎn)”狀態(tài)無(wú)狀態(tài)每次調(diào)用獨(dú)立有內(nèi)部狀態(tài)支持階段流轉(zhuǎn)復(fù)用性可被不同技能引用本身是復(fù)用的最小業(yè)務(wù)單元容錯(cuò)通常由調(diào)用方處理錯(cuò)誤自帶前置檢查、后置校驗(yàn)、降級(jí)恢復(fù)描述側(cè)重說(shuō)明“我能做什么動(dòng)作”說(shuō)明“我適合解決什么任務(wù)”工具是技能的“底座”技能是工具的“編排層”。舉個(gè)例子一個(gè)搜索技能內(nèi)部會(huì)調(diào)用檢索 API工具但它還會(huì)做三件工具本身不做的事第一把用戶的模糊問(wèn)題拆成 2-3 個(gè)具體檢索詞第二對(duì)檢索結(jié)果做相關(guān)度過(guò)濾第三如果主搜索源超時(shí)自動(dòng)切到備選搜索源。這些動(dòng)作疊加起來(lái)才是“會(huì)搜索”這個(gè)技能。從工程角度看把技能和工具分開(kāi)還有一個(gè)現(xiàn)實(shí)好處工具的接口往往隨外部服務(wù)變動(dòng)而技能的對(duì)外契約名稱、描述、入?yún)⒊鰠⒖梢员３址€(wěn)定。這樣 Agent 層面的提示詞和路由邏輯就不用頻繁改底層換了供應(yīng)商也不影響上層行為。1.3 技能庫(kù)的整體架構(gòu)分層我在設(shè)計(jì) agent-skills 時(shí)把整個(gè)框架拆成了四層注冊(cè)中心、執(zhí)行引擎、上下文管理器、評(píng)估器。分層的核心原因只有一個(gè)——把“檢索”和“執(zhí)行”解耦把“狀態(tài)”和“邏輯”分離這樣后續(xù)加技能、調(diào)技能都不會(huì)牽一發(fā)動(dòng)全身。注冊(cè)中心負(fù)責(zé)維護(hù)所有技能的元數(shù)據(jù)包括名稱、描述、標(biāo)簽、參數(shù) Schema、優(yōu)先級(jí)。Agent 接到任務(wù)后第一步不是直接執(zhí)行而是先來(lái)注冊(cè)中心“找技能”。這一步可以做成關(guān)鍵詞粗篩也可以疊加向量檢索把候選技能從幾百個(gè)縮小到三到五個(gè)。執(zhí)行引擎拿到候選技能后負(fù)責(zé)加載技能實(shí)例、執(zhí)行前置鉤子、運(yùn)行主邏輯、觸發(fā)后置校驗(yàn)并且在失敗時(shí)調(diào)用恢復(fù)策略。上下文管理器比較容易被忽略它的職責(zé)是把技能執(zhí)行過(guò)程中的關(guān)鍵中間狀態(tài)暫存起來(lái)比如“當(dāng)前進(jìn)行到第幾步”“上一步產(chǎn)出了什么”這樣組合技能才能有序推進(jìn)。評(píng)估器則是一個(gè)閉環(huán)反饋模塊它記錄每次技能調(diào)用的命中率、成功率、token 消耗方便你持續(xù)優(yōu)化技能描述和執(zhí)行邏輯。這四層配合起來(lái)整體流程大概是這樣Agent 收到用戶任務(wù)向注冊(cè)中心發(fā)起檢索拿到最匹配的技能描述后把任務(wù)參數(shù)交給執(zhí)行引擎引擎按技能內(nèi)部定義好的階段逐步執(zhí)行每走一步都從上下文管理器讀寫(xiě)狀態(tài)最終結(jié)果通過(guò)評(píng)估器記錄質(zhì)量再把關(guān)鍵信息寫(xiě)回技能的記憶緩存作為下次執(zhí)行的參考。后面我會(huì)給一個(gè)簡(jiǎn)化版實(shí)現(xiàn)方便你理解每個(gè)環(huán)節(jié)到底做了什么。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 技能描述Agent 選擇技能的“門面”如果你只能優(yōu)化一件事我會(huì)毫不猶豫地建議你打磨技能描述。因?yàn)榧寄軐?shí)現(xiàn)得再完美模型找不到它、或者把它和別的技能搞混等于白寫(xiě)。技能描述本質(zhì)上是寫(xiě)給大模型看的“使用說(shuō)明書(shū)”它的目標(biāo)不是讓人類看懂而是讓模型在“什么場(chǎng)景下該選中我”這件事上沒(méi)有歧義。我寫(xiě)技能描述時(shí)會(huì)遵照一個(gè)檢查清單意圖關(guān)鍵詞、適用場(chǎng)景、輸入限制、輸出格式、使用禁忌。意圖關(guān)鍵詞幫助模型快速匹配比如“會(huì)議紀(jì)要”技能的描述里要有“總結(jié)、紀(jì)要、提煉、議題”這些詞適用場(chǎng)景要寫(xiě)清楚“什么任務(wù)適合你”比如“當(dāng)用戶提供會(huì)議錄音或速記文稿需要輸出結(jié)構(gòu)化紀(jì)要時(shí)”輸入限制要寫(xiě)明白“你能接收什么格式”比如“支持 txt、md不支持音視頻直接輸入”輸出格式則要說(shuō)明“你返回什么東西”比如“返回包含議題列表、結(jié)論、待辦事項(xiàng)的 Markdown 文本”使用禁忌同樣重要用來(lái)排除邊界情況比如“用戶只要求翻譯時(shí)不要使用本技能”。這里放一個(gè)正反對(duì)比你感受一下差別。反例描述“對(duì)文本進(jìn)行摘要。”——太寬泛模型不知道什么時(shí)候該用。正例描述“當(dāng)用戶提供一篇文章、報(bào)告或網(wǎng)頁(yè)正文需要提煉核心觀點(diǎn)和關(guān)鍵數(shù)字時(shí)使用。輸入為純文本輸出為 200 字以內(nèi)的要點(diǎn)列表。若用戶僅要求翻譯或改寫(xiě)不使用本技能?！蹦憧春笳咧苯訋湍Ｐ桶褯Q策邊界框好了。還有一個(gè)實(shí)操細(xì)節(jié)描述不要寫(xiě)實(shí)現(xiàn)細(xì)節(jié)。我見(jiàn)過(guò)有人把內(nèi)部調(diào)用了幾個(gè) API、用了什么模型都寫(xiě)進(jìn)技能描述里這純屬浪費(fèi) token模型根本不關(guān)心這些。描述里只需要寫(xiě)“任務(wù)特征”和“契約約束”實(shí)現(xiàn)細(xì)節(jié)放到技能內(nèi)部文檔里就好。2.2 技能實(shí)現(xiàn)從需求到代碼的落地規(guī)范技能描述解決的是“模型怎么找到我”技能實(shí)現(xiàn)解決的是“找到之后怎么穩(wěn)定跑完”。我在 agent-skills 里給每個(gè)技能定義了一套標(biāo)準(zhǔn)鉤子相當(dāng)于給技能執(zhí)行流程立了個(gè)規(guī)矩環(huán)境準(zhǔn)備在前、核心邏輯居中、結(jié)果校驗(yàn)在后、出錯(cuò)有兜底。以 Python 為例一個(gè)技能類大致長(zhǎng)這樣from pydantic import BaseModel class SkillInput(BaseModel): text: str max_points: int 200 class SummarySkill: name summary_skill description 當(dāng)用戶提供文章或報(bào)告需要提煉核心觀點(diǎn)時(shí)使用... def before_run(self, payload: SkillInput): # 前置檢查確認(rèn)輸入非空、長(zhǎng)度合規(guī) if not payload.text.strip(): raise ValueError(text cannot be empty) return payload def run(self, payload: SkillInput): # 核心邏輯調(diào)用摘要模型整理要點(diǎn) points self._call_summarizer(payload.text, payload.max_points) return points def after_run(self, output): # 后置校驗(yàn)確保輸出非空且是列表 if not isinstance(output, list) or len(output) 0: raise RuntimeError(summary output is invalid) return output def on_error(self, exc: Exception): # 兜底邏輯記錄錯(cuò)誤并返回可讀信息 return {error: str(exc), fallback: None}這套鉤子的價(jià)值在于它把每個(gè)技能的“生命周期”固定下來(lái)執(zhí)行引擎只管按順序調(diào)用鉤子技能自己管內(nèi)部的業(yè)務(wù)細(xì)節(jié)。以后無(wú)論是加日志、加監(jiān)控還是做重試都落在框架層面而不需要改每個(gè)技能。另一個(gè)我特別想強(qiáng)調(diào)的規(guī)范是參數(shù)校驗(yàn)。不要指望大模型每次都給你傳出完美的參數(shù)它經(jīng)常會(huì)把字符串傳成數(shù)字、把必填字段漏掉。所以每個(gè)技能的入?yún)⒁宦捎?Pydantic 這類 Schema 約束在 before_run 階段就校驗(yàn)掉絕不要等到 run 內(nèi)部再花力氣解析臟參數(shù)。參數(shù)校驗(yàn)的本質(zhì)是把“信任模型”改成“驗(yàn)證模型”這是一種成本極低的防御手段。最后提一個(gè)原則技能盡量做到“冪等或可恢復(fù)”。所謂冪等就是同一個(gè)輸入跑兩次結(jié)果一致所謂可恢復(fù)就是跑到一半掛了下次可以接著跑而不是從頭再來(lái)。冪等能省掉很多重復(fù)執(zhí)行的麻煩可恢復(fù)則能避免外部副作用比如發(fā)了一封重復(fù)郵件帶來(lái)的事故。做不到冪等的時(shí)候至少要保證 on_error 里能明確告訴調(diào)用方“我已經(jīng)做到哪一步了”。2.3 技能注冊(cè)與檢索讓 Agent 快速找到技能有了技能類下一步就是把它們登記到注冊(cè)中心并且讓 Agent 在一個(gè)能接受的時(shí)延內(nèi)找到該用的那個(gè)。這里有個(gè)關(guān)鍵約束隨著技能增多你不能把所有技能描述一股腦塞進(jìn)系統(tǒng) Prompt否則上下文很快爆炸而且模型面對(duì)幾十個(gè)相似描述時(shí)會(huì)眼花繚亂?？尚械姆桨甘恰按趾Y 精排”兩步走。粗篩階段注冊(cè)中心根據(jù)用戶任務(wù)的文本按技能名稱、標(biāo)簽、描述里的關(guān)鍵詞做一輪快速過(guò)濾把幾百個(gè)技能縮小到 TopK我一般取 5 個(gè)。這一步速度極快不需要調(diào)用模型。精排階段把粗篩出的技能描述拼接成一段短列表交給模型做最終選擇讓它判斷哪個(gè)技能最匹配當(dāng)前任務(wù)。精排只關(guān)乎幾十個(gè)候選token 消耗可控選擇準(zhǔn)確率卻比“直接塞所有技能”高不少。如果技能數(shù)量特別大比如超過(guò)一千個(gè)我會(huì)再疊加一個(gè) embedding 向量檢索層。你可以給每個(gè)技能描述生成向量存進(jìn)向量數(shù)據(jù)庫(kù)用戶請(qǐng)求進(jìn)來(lái)后用同一個(gè) embedding 模型編碼請(qǐng)求文本做相似度檢索把最接近的幾十個(gè)技能送入粗排。這種做法在技能數(shù)量大時(shí)能有效提升召回率而且實(shí)現(xiàn)不難。需要注意的坑是技能描述里盡量不要出現(xiàn)和技能用途無(wú)關(guān)的“熱門詞”否則向量檢索會(huì)把無(wú)關(guān)技能拉進(jìn)來(lái)干擾后續(xù)精排。注冊(cè)中心本身建議做成輕量服務(wù)獨(dú)立于 Agent 主進(jìn)程。這樣技能更新不需要重啟主要服務(wù)注冊(cè)中心也可以單獨(dú)做緩存和監(jiān)控。我最初圖省事把技能注冊(cè)表寫(xiě)死在代碼里結(jié)果每次加技能都要重新部署后來(lái)改成獨(dú)立服務(wù)之后加技能的熱更新終于順暢了。3. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 第一個(gè)技能一個(gè)關(guān)鍵詞搜索技能理論說(shuō)了不少現(xiàn)在落地走一遍。我從最簡(jiǎn)單的技能開(kāi)始講關(guān)鍵詞搜索。這個(gè)技能的目標(biāo)不是“給你一個(gè)搜索鏈接”而是“根據(jù)問(wèn)題自動(dòng)生成檢索詞調(diào)用搜索接口并把返回結(jié)果整理成干凈列表”。拆解來(lái)看它包含四個(gè)步驟生成檢索詞、調(diào)用搜索 API、過(guò)濾無(wú)效結(jié)果、返回結(jié)構(gòu)化數(shù)據(jù)。下面是一段簡(jiǎn)化后的實(shí)現(xiàn)骨架class SearchSkill: name search_skill description ( 當(dāng)用戶需要查找最新資料、新聞、文檔或網(wǎng)絡(luò)信息時(shí)使用。 輸入為自然語(yǔ)言問(wèn)題我會(huì)自動(dòng)生成2-3個(gè)具體檢索詞并執(zhí)行搜索 返回按相關(guān)度排序的結(jié)果列表。 ) def before_run(self, payload: SkillInput): if not payload.query.strip(): raise ValueError(query is empty) return payload def run(self, payload: SkillInput): # 1. 用輕量模型將用戶問(wèn)題拆成多個(gè)具體檢索詞 keywords self._expand_queries(payload.query) # 2. 依次調(diào)用搜索API合并返回結(jié)果 raw_results [] for kw in keywords: raw_results.extend(self._call_search_api(kw, top5)) # 3. 過(guò)濾掉重復(fù)和明顯無(wú)關(guān)的條目 return self._dedup_and_filter(raw_results) def after_run(self, output): if not output: return {has_results: False, items: []} return {has_results: True, items: output[:10]}我第一次測(cè)試這個(gè)技能時(shí)發(fā)現(xiàn)模型最常犯的錯(cuò)誤是“檢索詞寫(xiě)得太寬泛”。比如用戶問(wèn)“Agent 框架有哪些新進(jìn)展”模型直接生成一個(gè)“Agent 框架進(jìn)展”這種大而無(wú)當(dāng)?shù)臋z索詞搜出來(lái)的結(jié)果大多不是近期的有效信息。后來(lái)我在技能描述里加了一句明確指示“將檢索詞拆成 2-3 個(gè)具體的短語(yǔ)組合比如‘Agent 框架 2025 開(kāi)源項(xiàng)目’、‘LangChain 新功能 發(fā)布’?！奔恿诉@一句之后搜索結(jié)果的質(zhì)量提升非常明顯。這再次印證了我在 2.1 里說(shuō)的技能描述里寫(xiě)清“怎么做事”往往比單純堆邏輯更能改變模型行為。測(cè)試完整鏈路時(shí)我會(huì)模擬一條用戶消息觀察 Agent 是否選中 SearchSkill以及傳給技能的 query 參數(shù)是否合理。如果模型沒(méi)選中多半是描述里的意圖關(guān)鍵詞還不夠直觀如果選中了但參數(shù)不對(duì)多半是參數(shù) Schema 寫(xiě)得不夠清楚。這兩類問(wèn)題在前期會(huì)反復(fù)出現(xiàn)屬于正常磨合過(guò)程。3.2 組合技能把多個(gè)原子技能編排成復(fù)雜流程單點(diǎn)技能只能解決一步操作真實(shí)任務(wù)往往需要多步配合這時(shí)候就要寫(xiě)“組合技能”。組合技能的核心設(shè)計(jì)是內(nèi)部維護(hù)一個(gè)階段狀態(tài)機(jī)把多個(gè)原子技能按順序串聯(lián)起來(lái)并在每個(gè)階段落盤(pán)中間產(chǎn)物。拿“整理技術(shù)周報(bào)”來(lái)舉例。這個(gè)任務(wù)實(shí)際上要完成三件事搜索本周的技術(shù)熱點(diǎn)、對(duì)每篇熱點(diǎn)生成摘要、把所有摘要匯總成固定格式的周報(bào)。在 agent-skills 里我寫(xiě)了一個(gè) ReportSkill內(nèi)部注冊(cè)了 SearchSkill、SummarySkill、FormatSkill 三個(gè)子技能并定義了三個(gè)階段class ReportSkill: stages [search, summarize, format] def run(self, payload): state self.state_manager.new_session() # stage 1: 搜索熱點(diǎn) if state.stage search: hits self.call_sub_skill(search_skill, payload.topic) state.update({hits: hits, stage: summarize}) self.state_manager.save(state) # stage 2: 逐篇摘要 if state.stage summarize: summaries [ self.call_sub_skill(summary_skill, h[content]) for h in state.hits[:5] ] state.update({summaries: summaries, stage: format}) self.state_manager.save(state) # stage 3: 匯總輸出 if state.stage format: return self.call_sub_skill(format_skill, state.summaries)幾個(gè)關(guān)鍵點(diǎn)需要特別說(shuō)明。第一階段狀態(tài)必須保存在技能實(shí)例之外最好放到獨(dú)立的 state_manager 里否則并發(fā)請(qǐng)求會(huì)串狀態(tài)。我最初把所有狀態(tài)都掛在技能對(duì)象上兩個(gè)請(qǐng)求同時(shí)進(jìn)來(lái)直接互相污染排查了半天才發(fā)現(xiàn)是這個(gè)原因。第二組合技能在描述里必須寫(xiě)清楚“我會(huì)依次做什么”比如描述里寫(xiě)“我會(huì)先搜索本周科技資訊再對(duì)前五篇生成摘要最后匯總為周報(bào)格式”這樣模型調(diào)用后不會(huì)對(duì)中間結(jié)果的形態(tài)產(chǎn)生錯(cuò)誤預(yù)期。第三組合技能內(nèi)部調(diào)用子技能時(shí)仍要復(fù)用子技能本身的參數(shù)校驗(yàn)和錯(cuò)誤處理不要在組合層面重新解析一遍結(jié)果——這既浪費(fèi) token又容易把錯(cuò)誤掩蓋掉。組合技能是 agent-skills 里最實(shí)用的部分。它能讓你把“多步驟任務(wù)”沉淀成可復(fù)用的經(jīng)驗(yàn)而不是讓模型每次臨時(shí)規(guī)劃步驟。從工程效率看這相當(dāng)于把 Agent 的“臨場(chǎng)發(fā)揮”逐步變成“熟能生巧”。3.3 技能評(píng)估怎么判斷技能好不好用技能庫(kù)越擴(kuò)越大你會(huì)面臨一個(gè)更現(xiàn)實(shí)的問(wèn)題怎么判斷技能到底好不好用我在早期一直憑感覺(jué)調(diào)參結(jié)果經(jīng)常是調(diào)完描述后感覺(jué)“應(yīng)該變好了”卻拿不出數(shù)據(jù)證明。后來(lái)我補(bǔ)了一套簡(jiǎn)單的評(píng)估流程分成離線和在線兩部分。離線評(píng)估用歷史任務(wù)做回歸測(cè)試。我會(huì)收集過(guò)去一段時(shí)間內(nèi)真實(shí)用戶給 Agent 的任務(wù)請(qǐng)求把它們作為固定測(cè)試集。每次改完一個(gè)技能就把這批請(qǐng)求重跑一遍統(tǒng)計(jì)三個(gè)核心指標(biāo)技能命中率模型是否選對(duì)了技能、參數(shù)正確率傳給技能的參數(shù)是否合法、任務(wù)完成率技能是否產(chǎn)出合格結(jié)果。只要改動(dòng)不導(dǎo)致這三個(gè)指標(biāo)回退我才敢放心上線。在線評(píng)估則關(guān)注技能調(diào)用鏈路上的效率。我會(huì)在日志里記錄每個(gè)技能實(shí)例的調(diào)用次數(shù)、平均耗時(shí)、平均 token 消耗、失敗次數(shù)、恢復(fù)次數(shù)。這里我特別關(guān)注一個(gè)容易被忽略的指標(biāo)單次技能調(diào)用消耗的平均 token。有些技能描述寫(xiě)得過(guò)長(zhǎng)模型每次選擇它都要閱讀大量無(wú)關(guān)文本久而久之 token 成本很高。優(yōu)化這些描述往往比換更貴的模型還劃算。我整理過(guò)一張參考速查表供你評(píng)估自己技能庫(kù)的健康度指標(biāo)健康范圍低于閾值說(shuō)明技能命中率 85%描述意圖不夠清晰或檢索排序有問(wèn)題參數(shù)正確率 90%參數(shù) Schema 和提示詞需要補(bǔ)強(qiáng)任務(wù)完成率 80%技能內(nèi)部邏輯或容錯(cuò)策略需要迭代平均恢復(fù)率 60%on_error 兜底太弱錯(cuò)誤容易直接暴露給用戶平均 token/調(diào)用越低越好描述冗余或內(nèi)部邏輯重復(fù)讀取無(wú)用信息這套評(píng)估體系不一定面面俱到但它至少能讓我在“優(yōu)化技能”這件事上不再靠感覺(jué)。每次改動(dòng)技能我都能從數(shù)據(jù)里看到是命中率提升了還是 token 下降了這比“看起來(lái)不錯(cuò)”要踏實(shí)得多。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 技能沖突與優(yōu)先級(jí)之爭(zhēng)技能多了之后第一個(gè)遇到的問(wèn)題就是“兩個(gè)技能看起來(lái)都能解決同一個(gè)任務(wù)”。比如我既有“周報(bào)生成技能”又有“日?qǐng)?bào)匯總技能”用戶說(shuō)“幫我整理一下這周的工作”模型可能兩個(gè)都匹配最后選錯(cuò)。這類問(wèn)題的本質(zhì)是技能描述在意圖空間上發(fā)生了重疊。我的處理辦法有兩招。第一招在描述里主動(dòng)加入“沖突排除條款”明確聲明自己的邊界。比如“日?qǐng)?bào)匯總技能”描述里寫(xiě)“僅當(dāng)用戶明確提到‘日?qǐng)?bào)’或‘今日工作’時(shí)使用如果提到‘周報(bào)’‘本周’請(qǐng)改用周報(bào)生成技能”。這看起來(lái)像是在給別的技能做廣告但實(shí)踐證明它恰恰能降低模型的決策困惑。第二招在注冊(cè)中心給技能加一個(gè)優(yōu)先級(jí)字段當(dāng)粗篩得分相近時(shí)按優(yōu)先級(jí)排序。注意優(yōu)先級(jí)不能寫(xiě)死要基于實(shí)際命中率動(dòng)態(tài)調(diào)整某個(gè)技能在同類任務(wù)里命中率更高它的優(yōu)先級(jí)就自動(dòng)上升。4.2 上下文爆炸與技能描述過(guò)長(zhǎng)另一個(gè)高頻問(wèn)題是技能一多系統(tǒng)提示詞越來(lái)越長(zhǎng)。有些技能描述恨不得把用法、示例、注意事項(xiàng)全寫(xiě)進(jìn)去結(jié)果模型在路由時(shí)反而抓不住重點(diǎn)而且每次請(qǐng)求都在空耗 token。這里我給自己定了一個(gè)硬性規(guī)則技能描述控制在 80 到 150 字詳細(xì)說(shuō)明放到技能類內(nèi)部的一個(gè)usage字段里只在執(zhí)行時(shí)才加載。執(zhí)行引擎可以在 before_run 階段讀取 usage 字段作為技能內(nèi)部的運(yùn)行參考但不需要參與路由決策。我還踩過(guò)一個(gè)具體的坑把完整的技能源碼和調(diào)用示例直接貼在描述里?？雌饋?lái)信息很全但模型實(shí)際上根本不會(huì)逐字閱讀真正起作用的只有前一兩句“應(yīng)用場(chǎng)景描述”。后面那些代碼塊反而干擾了語(yǔ)義匹配讓模型對(duì)技能的能力邊界產(chǎn)生錯(cuò)誤預(yù)期。刪掉冗余內(nèi)容之后命中率不但沒(méi)降反而上漲了約 7 個(gè)百分點(diǎn)。4.3 容錯(cuò)與恢復(fù)技能翻車之后怎么辦技能跑得再穩(wěn)總會(huì)有翻車的時(shí)候。參數(shù)校驗(yàn)失敗、外部服務(wù)超時(shí)、模型返回格式不對(duì)、下游接口報(bào)錯(cuò)這些在真實(shí)環(huán)境里避無(wú)可避。我的經(jīng)驗(yàn)是不要追求“永不失敗”而是追求“失敗后可理解、可恢復(fù)”。on_error 鉤子里至少要記錄錯(cuò)誤類型和當(dāng)前階段讓上層 Agent 知道發(fā)生了什么以及能不能換一條路徑繼續(xù)。我總結(jié)了一張問(wèn)題速查表按高頻優(yōu)先級(jí)列在下面錯(cuò)誤類型常見(jiàn)原因解決建議參數(shù) Schema 校驗(yàn)失敗模型漏傳字段或類型錯(cuò)誤強(qiáng)化描述中的“需要輸入什么”并加 before_run 校驗(yàn)外部服務(wù)超時(shí)第三方 API 響應(yīng)過(guò)慢在 run 里加重試機(jī)制超時(shí)閾值設(shè) 2-3 次輸出格式不合預(yù)期模型返回 Markdown 卻需要 JSON在 after_run 里做強(qiáng)校驗(yàn)失敗時(shí)觸發(fā)重新生成階段狀態(tài)丟失并發(fā)會(huì)話污染或狀態(tài)未落盤(pán)狀態(tài)統(tǒng)一走 state_manager禁止掛在技能實(shí)例上子技能執(zhí)行失敗底層技能拋錯(cuò)未捕獲組合技能要把子技能異常捕獲并標(biāo)記階段進(jìn)度針對(duì)超時(shí)和瞬態(tài)錯(cuò)誤我的具體做法是在 run 階段包一層重試裝飾器第一次超時(shí)后重試一次并切換備選服務(wù)比如主搜索源失敗就換備用源。如果第二次仍然失敗直接走 on_error把“已經(jīng)嘗試兩次”的信息返回給上層模型讓它決定是否換一個(gè)技能或者詢問(wèn)用戶。這一套下來(lái)技能庫(kù)的穩(wěn)定性提升明顯用戶面對(duì)“失敗”時(shí)至少不會(huì)看到一團(tuán)亂麻。還有一個(gè)容易忽略的點(diǎn)恢復(fù)策略要區(qū)分“可安全重試”和“不可安全重試”。比如發(fā)送郵件這種有副作用的操作重試前必須確認(rèn)上一步是否真的失敗了否則可能發(fā)兩封郵件。我在可寫(xiě)操作的技能里都會(huì)加一個(gè)execution_id每次執(zhí)行生成唯一 ID下游接口用這個(gè) ID 做去重。這樣即使框架層誤觸發(fā)重試也不會(huì)造成重復(fù)副作用。寫(xiě)在最后的經(jīng)驗(yàn)我把 agent-skills 這套技能庫(kù)陸續(xù)用在幾個(gè) Agent 項(xiàng)目里之后最大的體會(huì)是技能描述花費(fèi)的時(shí)間比技能實(shí)現(xiàn)還要多。大多數(shù)人剛開(kāi)始都急著寫(xiě)邏輯、調(diào)接口真正決定一個(gè) Agent 上限的往往是那些看起來(lái)“只是文字”的描述和約束。你花半小時(shí)打磨一段 150 字的技能描述可能比花三天優(yōu)化內(nèi)部算法更能提升整體任務(wù)成功率。另一個(gè)意外的收獲是技能庫(kù)天然幫你把散落的業(yè)務(wù)邏輯沉淀成了“組織的資產(chǎn)”——新同事接手項(xiàng)目時(shí)不需要讀一堆 Agent 編排代碼只看技能清單就能明白系統(tǒng)能做什么、邊界在哪里。后續(xù)我打算給技能庫(kù)加上評(píng)分反饋機(jī)制讓模型在每次成功調(diào)用后回寫(xiě)一條“這個(gè)技能在什么場(chǎng)景好用”的經(jīng)驗(yàn)記錄慢慢讓 Agent 形成自己的“手感”。這條路走通的話技能庫(kù)就不只是一個(gè)工具集而會(huì)成為 Agent 持續(xù)進(jìn)化的記憶底座。