如果你最近在折騰 Agent 應(yīng)用大概率已經(jīng)碰到一個很尷尬的分叉點Demo 做得飛起一旦真正上線Agent 的行為就開始飄。同一個功能用戶早上問和下午問得到的結(jié)果完全兩樣你加了半天提示詞結(jié)果它在無關(guān)請求里也觸發(fā)奇怪的動作。我去年做一個某跨平臺系統(tǒng)的時候就是卡在這個問題上。后來我把思路從“寫提示詞”換成了“給 Agent 配一套工程化 Skills”整個項目的穩(wěn)定性和可維護性立刻拉開了差距。Skills 在我的使用語境里就是“可被 Agent 動態(tài)調(diào)用、有清晰邊界、能獨立維護和測試的能力單元”不是一段寫在系統(tǒng)提示詞里的模糊指令。這篇內(nèi)容不聊論文概念就講我在實際項目里怎么拆解 Skills、怎么設(shè)計工作流以及哪些坑是真的踩過以后才知道的。無論你是剛?cè)腴T想搭第一個 Agent 應(yīng)用還是已經(jīng)在線上被各種隨機行為折磨得頭大這套思路都能直接拿去用。1. 為什么我選擇把 Agent 能力拆成 Skills而不是繼續(xù)堆提示詞1.1 先搞清楚你說的 Skills 到底是什么很多人在做 Agent 的時候習慣把“能力”直接寫進系統(tǒng)提示詞比如“你是一個可以查天氣的助手天氣信息通過調(diào)用某個接口獲取”。這種寫法在演示階段沒什么問題但一旦能力變多提示詞就會越來越長模型對能力的邊界理解越來越模糊最后所有請求都在“嘗試”調(diào)用所有工具結(jié)果各種誤觸。Skills 的意思是把某項能力封裝成一個獨立模塊它有名字、有描述、有輸入輸出協(xié)議有可執(zhí)行的邏輯還有獨立的驗證方式和錯誤處理機制。Agent 本身不再“模糊地知道”自己有哪些能力而是通過一個可被檢索和調(diào)度的機制在需要的時候精確加載對應(yīng)的技能。打個比方系統(tǒng)提示詞方案像是給員工發(fā)一本厚厚的手冊讓他在腦內(nèi)記住所有流程Skills 方案則是給他一個工具墻上面每個工具都貼了標簽這是什么、什么場景用、怎么用、壞了會怎樣。員工不需要背手冊他只管看標簽選工具。這個差異決定了項目的可維護上限。舉個具體例子當時我在做一個知識庫問答 Agent剛起步時有三個功能文檔摘要、關(guān)鍵詞檢索、相似度檢索。用提示詞硬寫也能跑但很快我發(fā)現(xiàn)用戶問“幫我把這段內(nèi)容壓縮一下”的時候模型經(jīng)常也跑去調(diào)用檢索工具返回一堆不相關(guān)的內(nèi)容。把這三個功能各封裝成一個帶明確觸發(fā)條件的 Skill 以后誤觸率明顯下降而且每一個 Skill 都可以單獨測試、單獨修 bug完全不影響其他能力。1.2 工程化路線到底解決了什么工程化 Skills 直接解決了三個讓人頭疼的問題。第一是可測試性。提示詞方案里你想驗證某個能力是否正常必須把整段對話跑一遍出了問題還很難定位是模型的“理解”錯了還是工具調(diào)用鏈路錯了。Skill 方案下每個 Skill 有獨立的輸入輸出校驗和測試用例你可以像測試普通函數(shù)一樣測試它。某次我改了一個清洗文本的 Skill回歸測試直接跑掛 3 個用例這在提示詞方案里幾乎不可能做到這么早發(fā)現(xiàn)問題。第二是權(quán)限邊界。Agent 在復(fù)雜場景里必須知道“哪些事不能做”。如果你把權(quán)限規(guī)則寫進提示詞模型可能會被繞過。Skill 本身可以做成權(quán)限的最小單元某個 Skill 只能訪問某張表另一個 Skill 只能調(diào)用某個只讀接口。技能未加載對應(yīng)的能力就不存在這在安全層面意義很大。第三是上下文壓縮。把十幾個能力的詳細說明都塞進提示詞會浪費大量模型上下文。通過 Skills 機制Agent 只需要維護一份“技能清單”真正的執(zhí)行邏輯放在外部代碼或子提示里只在需要時載入。上下文占用能減少一半以上模型注意力也更集中。2. 技能系統(tǒng)的整體設(shè)計清單、執(zhí)行器與觸發(fā)機制2.1 一份技能定義里到底該寫什么我在項目中把每個 Skill 定義成這樣的結(jié)構(gòu)name、description、input_schema、output_schema、execute函數(shù)、validation邏輯、error_handler。看起來很簡單但每一個字段背后都有講究。name必須唯一且語義清晰不能叫func1這種名字因為你后面要讓大模型通過名字來路由名字就是它的標識符。description是最容易被低估的字段。它不是寫給用戶看的而是寫給模型“選擇器”看的。合格的描述要包含三部分這個技能負責什么任務(wù)、適合什么輸入、不適合什么輸入。例如“從一段長文本中提取結(jié)構(gòu)化摘要適合輸入原文內(nèi)容不適合輸入表格數(shù)據(jù)”。我見過很多項目在這個字段上敷衍寫一句“提取摘要”就完了結(jié)果路由準確率直線下降。模型不是靠讀源碼來理解技能的它全靠描述信息做判斷所以描述的質(zhì)量直接決定整個系統(tǒng)的上限。input_schema和output_schema最好是強類型定義。有些實測方案用 JSON Schema有些用帶類型標注的偽代碼甚至用 Pydantic 這類模型。核心原因是沒有校驗的情況下任意一個技能的錯誤輸出都可能污染后續(xù)流程。我在一個金融問答場景里吃過虧一個技能把數(shù)值返回成了字符串下游做聚合計算直接類型報錯問題查了半天才發(fā)現(xiàn)是上游的輸出類型沒鎖死。execute函數(shù)是技能的實際邏輯。它可以是調(diào)外部 API、執(zhí)行一段代碼、跑一次數(shù)據(jù)庫查詢也可以是調(diào)用一個大模型子任務(wù)。我建議把技能實現(xiàn)完全獨立成函數(shù)不要依賴對話上下文里的臨時變量。這樣既能單測也能在未來把技能遷移到其他 Agent 時省下大量成本。2.2 執(zhí)行器的四種典型形態(tài)根據(jù)技能內(nèi)部做的事情不同我把它們分為四種形態(tài)設(shè)計的時候心態(tài)完全不一樣。第一類是 API 代理型。技能本身不處理業(yè)務(wù)邏輯只是把 Agent 的請求轉(zhuǎn)發(fā)到某個外部服務(wù)再做結(jié)果清洗。比如天氣查詢、股票行情、訂單狀態(tài)查詢。這類技能的關(guān)鍵是做好超時和限流否則外部服務(wù)一抖動整個 Agent 也跟著抖動。第二類是代碼生成與執(zhí)行型。技能內(nèi)部實際上就是一段代碼解釋器或腳本執(zhí)行器Agent 生成代碼技能執(zhí)行代碼并返回結(jié)果比如數(shù)據(jù)計算、格式轉(zhuǎn)換、爬蟲采集。這類技能最危險因為執(zhí)行權(quán)限很難控制。我的做法是讓這類技能運行在獨立沙箱進程里并限制網(wǎng)絡(luò)和文件寫入權(quán)限只開放它真正需要的最小能力。第三類是檢索增強型。它的核心不是生成內(nèi)容而是從外部存儲中找信息。文檔檢索、數(shù)據(jù)庫查詢、圖數(shù)據(jù)庫查詢都算這一類。這類技能我通常會對召回結(jié)果做后處理包括去重、按相關(guān)度排序、限制返回條數(shù)減少無效上下文占用。第四類是流程編排型。這類技能自己不干具體活而是調(diào)用其他技能。比如一個“生成周報”技能內(nèi)部會依次調(diào)用“匯總數(shù)據(jù)”“提取重點”“生成標題”三個子技能。流程編排型技能是天然的工作流入口也是整個系統(tǒng)從“能干活”走向“會干活”的關(guān)鍵。2.3 觸發(fā)與路由如何避免技能“誤傷”技能再多如果路由不準一切都白搭。我在實踐中總結(jié)了三層路由策略。第一層是硬規(guī)則路由。對于邊界特別清晰的技能直接用關(guān)鍵詞或正則做前置過濾。比如“翻譯成英文”這個請求基本可以穩(wěn)定命中翻譯 Skill。硬規(guī)則的好處是零成本且不會誤觸缺點是覆蓋不了所有情況。第二層是模型路由。把技能清單只要name和description交給模型讓它根據(jù)用戶輸入選擇最合適的技能。這種方式靈活但要注意給模型一個“都不合適”的選項。很多人忽略這一點結(jié)果模型被迫在所有技能里硬選一個反而出錯。我在提示里會明確寫“如果沒有任何技能匹配直接返回 no_skill”路由錯誤率立刻下降了很多。第三層是動態(tài)路由。根據(jù)對話歷史或用戶畫像臨時調(diào)整某些技能的可見性和權(quán)重。比如一個訪客用戶我干脆不給他暴露“刪除數(shù)據(jù)”類技能一個企業(yè)用戶進來默認把檢索權(quán)重調(diào)高。這種動態(tài)策略在權(quán)限管理和個性化場景里非常有用。我得提醒一句路由不是越復(fù)雜越好。如果你的技能總數(shù)在十個以內(nèi)模型路由就夠了超過三十個才需要考慮分層路由或引入獨立的檢索模型。過早做復(fù)雜路由只會給自己增加排查負擔。3. 工作流如何把技能編排成真正的業(yè)務(wù)流程3.1 從一句用戶指令到一份工作流定義技能只是積木真正干活靠的是工作流。工作流是一種編排描述它決定了技能按什么順序執(zhí)行、什么條件下跳過、什么條件下重試。我習慣把工作流定義成一個獨立文件而不是寫死在代碼里。這樣做的好處是改流程不需要重新發(fā)布代碼而且可以把流程直接反饋給團隊查看。舉個例子我做一個“會議紀要自動歸檔”功能用戶在對話里說完會議內(nèi)容Agent 需要完成四步清洗速記文本、提取議題和結(jié)論、根據(jù)結(jié)論生成待辦事項、歸檔到項目文檔庫。如果是傳統(tǒng)提示詞方案這四步全在一輪模型調(diào)用里完成任何一個環(huán)節(jié)出問題都要整輪重跑。用工作流方案我會把它們拆成四個 Skill然后用一個順序工作流串起來?，F(xiàn)實操作中中間某一步失敗我可以只重跑那一步而不是重跑整個對話。3.2 線性、并行與動態(tài)分支工作流的編排模式我在實際項目里最常用三種。線性編排是最簡單的技能 A 執(zhí)行完輸出傳給技能 B再傳給技能 C。大部分流程都是這種模式關(guān)鍵是要把技能之間的傳遞標準定義好。我的做法是讓每個技能的輸出都包裝成一個統(tǒng)一結(jié)構(gòu)包含status、data、error三部分。這樣下游技能判斷狀態(tài)時非常簡單不會出現(xiàn)“拿到一個字符串不知道到底是內(nèi)容還是報錯”的尷尬情況。并行編排是把幾個互不依賴的技能同時執(zhí)行最后匯總結(jié)果。比如生成一份市場周報時“銷售數(shù)據(jù)”“用戶反饋”“競品信息”三個技能可以各自獨立跑最后再做匯總。并行執(zhí)行能大幅縮短響應(yīng)時間但如果三個技能運行完之后還要匯總匯總技能必須能容忍某個子技能失敗。我的做法是在并行分支里給每個技能設(shè)置超時超時返回超時占位符匯總技能可以感知到“哪個部分沒拿到”并顯式告訴用戶。動態(tài)分支是我認為最能體現(xiàn)工程價值的模式。工作流不是死板的線性鏈條而是根據(jù)步驟結(jié)果決定下一步走向。例如“內(nèi)容審核”工作流先跑一個敏感詞檢測 Skill如果檢測通過直接結(jié)束如果沒通過再調(diào)用一個人工復(fù)核 Skill甚至進入“拒絕生成”分支。這種 if/else 邏輯放在工作流文件里比讓大模型自己“臨場判斷”要可靠得多因為每個分支都是可測試的。3.3 超時、重試與降級設(shè)計給技能配工作流如果不處理異常那線上的 Agent 會教你做人。以下三件事是我認為每個工作流都必須內(nèi)置的。第一是超時控制。每個技能調(diào)用都要設(shè)置合理超時比如外部 API 型技能給 5 秒代碼生成型技能給 15 秒。超時之后要么終止整個流程要么走降級分支。如果什么超時都不設(shè)一個技能卡住整個 Agent 請求就會掛在那里用戶直接失去耐心。第二是重試策略。不是所有錯誤都值得重試。對于網(wǎng)絡(luò)抖動、臨時限流這類瞬時錯誤我一般建議重試一到兩次間隔用指數(shù)退避對于輸入數(shù)據(jù)錯誤、參數(shù)不合法這類確定性錯誤重試一百次也是浪費。我在工作流定義里會給每個技能聲明retryable和max_retries讓引擎能夠在運行時做出判斷。第三是降級路徑。降級不是做不做的問題而是必須做的。比如知識庫檢索服務(wù)掛了工作流可以降級成“直接調(diào)用基礎(chǔ)模型生成回答并附帶提示檢索服務(wù)暫時不可用”。又比如“生成圖片”技能失敗降級成“返回文字描述占位圖”。降級路徑保證了 Agent 在故障時不至于完全撂挑子這個體驗差異用戶感知是很明顯的。4. 實操在項目里落地一套最小 Skills 工作流4.1 目錄與注冊結(jié)構(gòu)以及運行時加載前面講了不少設(shè)計思路這一節(jié)直接上實操。我在項目里習慣這樣組織技能目錄skills/ registry.yaml document_summary/ manifest.yaml execute.py test_cases.json web_search/ manifest.yaml execute.py test_cases.json workflows/ meeting_notes.yaml weekly_report.yaml runtime/ loader.py workflow_engine.py每個技能獨立一個目錄內(nèi)部放manifest.yaml描述、輸入輸出、觸發(fā)條件、超時重試配置、execute.py真正的執(zhí)行邏輯、test_cases.json本地測試用例。運行時會掃描所有技能目錄讀取manifest.yaml生成一份統(tǒng)一的注冊表保存在內(nèi)存里供 Agent 調(diào)用。registry.yaml由我手工維護一份“技能列表”它的作用不是承載全部技能詳情而是只存namedescription方便在路由時以極小的上下文向模型展示全量技能。模型選定某個技能后運行時再加載對應(yīng)目錄下的完整manifest和執(zhí)行器。這種兩級加載挺有效列表輕量詳情按需加載不浪費 token。# registry.yaml skills: - name: document_summary description: 對長文本內(nèi)容生成結(jié)構(gòu)化摘要適合文檔、文章、會議記錄不適合表格數(shù)據(jù) - name: web_search description: 在互聯(lián)網(wǎng)上檢索相關(guān)信息返回標題與摘要列表適合實時信息查詢 - name: calendar_query description: 查詢用戶日歷中的日程安排支持按日期范圍篩選4.2 技能定義和執(zhí)行器的代碼骨架下面寫一個簡化版但能跑通整個流程的技能定義以document_summary為例。# execute.py (document_summary) import json from typing import Any, Dict def execute(inputs: Dict[str, Any]) - Dict[str, Any]: 執(zhí)行文檔摘要技能。 inputs 里包含 content, max_length 兩個字段。 返回值統(tǒng)一為 {status, data, error} 結(jié)構(gòu)。 content inputs.get(content, ) max_length int(inputs.get(max_length, 2000)) if not isinstance(content, str) or len(content) 50: return { status: failed, data: None, error: content must be a string with length 50, } # 這里可以調(diào)用一個摘要模型或第三方總結(jié)接口簡化起見用占位邏輯 summary _call_summary_model(content, max_length) return { status: success, data: {summary: summary}, error: None, } def _call_summary_model(content: str, max_length: int) - str: # 實際項目里替換成摘要模型調(diào)用 return content[:max_length] ...[truncated]技能定義文件則長這樣# manifest.yaml name: document_summary version: 1.2.0 description: 對長文本內(nèi)容生成結(jié)構(gòu)化摘要適合文檔、文章、會議記錄不適合表格數(shù)據(jù) input_schema: type: object properties: content: type: string minLength: 50 max_length: type: integer default: 2000 required: - content output_schema: type: object properties: summary: type: string timeout_seconds: 15 retryable: true max_retries: 2這里我特別說一下為什么manifest.yaml里也要寫timeout_seconds和retryable而不是在代碼里寫死。答案很簡單工作流引擎在處理流程時需要在不加載執(zhí)行器的情況下就能判斷“這個技能能不能重試、最多重試幾次、超時多久”否則引擎就必須執(zhí)行到一半才知道策略這會拖慢流程且不好觀測。把策略外置成元數(shù)據(jù)以后引擎可以在編排階段就把耗時和風險算出來。4.3 用一個小示例跑通整個技能編排流程接下來我用一個非常常見的場景串起來收到一份新會議紀要自動清洗、總結(jié)、生成待辦并歸檔。# workflows/process_meeting_notes.yaml name: process_meeting_notes steps: - id: step_clean skill: text_cleaner inputs: content: ${user_input} - id: step_summary skill: document_summary inputs: content: ${step_clean.output.data.clean_text} max_length: 1500 - id: step_todo skill: todo_extractor inputs: summary: ${step_summary.output.data.summary} - id: step_archive skill: doc_archiver inputs: content: ${step_summary.output.data.summary} todos: ${step_todo.output.data.todos} on_failure: skip_and_notify這個 YAML 描述了一個四步順序工作流。${step_clean.output.data.clean_text}是引用上一個技能的輸出。最關(guān)鍵的是step_archive里配了on_failure: skip_and_notify意思是歸檔失敗時不阻斷整體流程只返回一個提示信息。這種“非關(guān)鍵步驟允許降級”的思路在真實業(yè)務(wù)里非常重要。對應(yīng)的工作流引擎核心偽代碼如下# workflow_engine.py (簡化版) async def run_workflow(workflow, initial_inputs): outputs {} for step in workflow[steps]: skill load_skill(step[skill]) inputs resolve_input_refs(step[inputs], initial_inputs, outputs) result await call_with_policy( skill.execute, inputs, timeoutskill.timeout_seconds, retryableskill.retryable, max_retriesskill.max_retries, ) if result[status] failed: if on_failure in step: outputs[step[id]] handle_failure(step[on_failure]) continue return {status: failed, failed_step: step[id], error: result[error]} outputs[step[id]] result return {status: success, outputs: outputs}這個骨架里核心是resolve_input_refs它負責把${xxx}引用替換成真正的運行時數(shù)據(jù)。實現(xiàn)時需要注意一點當引用的上游步驟失敗時當前步驟不能直接崩掉而是要走上層的on_failure分支。5. 常見問題與排障技巧實錄5.1 技能之間互相干擾輸出格式對不上這是我把技能分裝之后遇到的第一個高頻問題。技能 A 輸出的是一個列表技能 B 卻當成字符串拼接結(jié)果整個流程炸掉或者輸出混亂。根本原因在于技能之間的契約沒有統(tǒng)一標準。排障思路很簡單我給每個技能配了test_cases.json里面固定寫清楚期望輸入和期望輸出。任何一個技能調(diào)整輸出格式馬上跑全部依賴它的下游技能測試格式斷裂在代碼評審階段就暴露了。這里要說個細節(jié)技能的輸出永遠不要裸返回str或dict哪怕只有一個字段也建議包成{status, data, error}省得下游判斷時還要嘗試解析。5.2 模型總是不選正確的技能有時我把技能清單丟給模型它卻選錯了。這里有兩個方向排查。第一優(yōu)先級是看description寫得好不好。我之前踩過坑把document_summary的描述寫成“總結(jié)文檔”結(jié)果用戶問“幫我概括一下這篇文章”的時候模型完全沒意識到該用這個技能因為它沒有建立“文章”和“文檔”的關(guān)聯(lián)。后來我把描述改成“對長文本內(nèi)容生成結(jié)構(gòu)化摘要適合文檔、文章、會議記錄不適合表格數(shù)據(jù)”命中率立刻上升。記住描述要寫正例和反例反例尤其重要。第二優(yōu)先級是看路由策略是否過于簡單。如果技能數(shù)量超過二十個模型單看清單確實容易混淆。我的經(jīng)驗是給容易混淆的技能配上“互斥說明”例如在清單里額外加一行提示“document_summary 處理長文本整體總結(jié)keyword_search 做關(guān)鍵詞定位兩者不要混用”。這種顯式說明在關(guān)鍵路徑上很管用。5.3 長上下文拖慢技能調(diào)用甚至出現(xiàn)幻覺技能執(zhí)行過程中上下文越長模型判斷就越不穩(wěn)定。尤其是檢索增強型技能如果你把搜索結(jié)果按原始長度直接塞給下一個技能很快上下文就爆了模型還會引用不存在的信息。我后來的處理標準是檢索結(jié)果先做裁剪每條結(jié)果保留標題加最多兩百字摘要且最多傳入前五條。這個裁剪邏輯單獨封裝成一個post_processor掛載在檢索技能內(nèi)部不進工作流主鏈路。另一個經(jīng)驗是如果一個技能確實需要長上下文盡量在技能內(nèi)部獨立調(diào)用模型子任務(wù)而不是把長上下文傳遞到 Agent 主線程。這樣主線程保持短小響應(yīng)速度和穩(wěn)定性都更好。5.4 技能升級后舊工作流出現(xiàn)兼容問題這個坑幾乎每個人都會踩。某次我升級了text_cleaner的清洗規(guī)則輸出文本里多了一個字段結(jié)果下游document_summary因為輸入格式校驗失敗直接報錯。排查半天才發(fā)現(xiàn)是版本不匹配。解決辦法是給manifest.yaml加version字段工作流定義里按需聲明最低技能版本。引擎在加載時先做版本校驗如果當前技能版本不滿足要求直接走降級流程。同時每個技能升級時把test_cases.json一并更新保證測試覆蓋新字段。操作上我還會保留舊版本技能目錄等新版本穩(wěn)定運行幾天后再清理這樣回滾也很快。6. 一點后續(xù)可以擴展的方向技能和工作流的組合做熟練之后還可以繼續(xù)往兩個方向擴展。一個是把技能加進自己的插件生態(tài)中做成可分發(fā)、可共享、可遠程加載的單元。另一個是結(jié)合更復(fù)雜的監(jiān)控和可觀測體系跟蹤每次路由是否合理、每個技能耗時是否波動讓 Agent 的行為能數(shù)字化度量。當然這些都屬于系統(tǒng)越來越龐大以后的事。如果你現(xiàn)在剛起步先把十來個技能用好把工作流跑穩(wěn)就已經(jīng)超過大多數(shù)停留在提示詞階段的項目了。我個人在實際操作中最大的體會是Agent 能力的上限不由模型決定而由你給它的工程骨架決定。Skills 和工作流這套體系本質(zhì)上是把“怎么干活”從模型手里接管過來變成穩(wěn)定可控的底層代碼。初期多花一點時間把骨架搭好后面每一輪功能迭代都會順暢很多。如果你正被線上 Agent 的隨機行為折磨不妨從這個方向試一試。