不知道各位有沒(méi)有這樣的體會(huì)同一個(gè)模型在別人手里是高效的開(kāi)發(fā)助手在自己手里卻像個(gè)只會(huì)應(yīng)答的工具人。差別在哪最近我在復(fù)盤(pán)自己的Agent工作流時(shí)答案越來(lái)越清晰——真正決定上限的不是你用什么模型、什么框架而是你給Agent配了哪些Skills。這個(gè)詞最近在Claude Code、Codex、OpenCode這些圈子里的討論度非常高。簡(jiǎn)單說(shuō)Skills就是把一個(gè)領(lǐng)域的操作方法、模板、腳本打包成Agent能直接調(diào)用的能力模塊。今天這篇我就想聊聊agent-skills它到底是什么、跟Agent本身有什么區(qū)別、怎么安裝使用、怎么自己寫(xiě)一個(gè)以及我在實(shí)際使用中踩過(guò)的坑。1. Skills是什么為什么Agent越來(lái)越離不開(kāi)它1.1 從Prompt到SkillsAgent能力封裝方式的進(jìn)化早期我們用AI編程方式是寫(xiě)一段很長(zhǎng)的Prompt把規(guī)則、示例、約束全塞進(jìn)去。這種方式有一個(gè)天然的問(wèn)題Prompt越長(zhǎng)模型越容易丟失重點(diǎn)而且改一次Prompt就要全部重來(lái)想跟別人共享能力更是麻煩。你復(fù)制一段錦囊給朋友對(duì)方還得手動(dòng)改人名、改路徑、改上下文。Skills的出現(xiàn)本質(zhì)上把“一次性指令”升級(jí)成了“可復(fù)用、可分發(fā)、可自動(dòng)觸發(fā)的能力包”。一個(gè)Skill通常是一個(gè)目錄里面有一個(gè)SKILL.md文件作為入口YAML frontmatter里寫(xiě)明技能名稱、描述、適用場(chǎng)景正文部分寫(xiě)執(zhí)行步驟、注意事項(xiàng)還可以附帶Python/Shell腳本、模板文件、參考文檔。Agent在運(yùn)行時(shí)讀取這個(gè)文件判斷當(dāng)前任務(wù)是否需要調(diào)用這個(gè)技能。這個(gè)設(shè)計(jì)很聰明。它把“教模型怎么做”和“給模型工具用”兩件事合到了一起。以前你想讓AI畫(huà)一張架構(gòu)圖要么在對(duì)話里反復(fù)描述格式要求要么寫(xiě)好一段提示詞每次粘貼現(xiàn)在你只需要裝一個(gè)“結(jié)構(gòu)圖Skills”直接說(shuō)“把系統(tǒng)架構(gòu)畫(huà)出來(lái)”Agent就會(huì)自己讀取技能里的規(guī)范、調(diào)用腳本生成圖表。對(duì)用戶來(lái)說(shuō)體驗(yàn)從“教它干活”變成了“它本來(lái)就會(huì)”。從生態(tài)角度看Skills還解決了知識(shí)分發(fā)的問(wèn)題。以前一個(gè)人的提示詞寫(xiě)得再好傳播和復(fù)用都很麻煩現(xiàn)在一個(gè)Skills文件夾可以直接扔到GitHub上別人拉下來(lái)放到指定目錄就能用。這也是為什么最近各種Skills合集、Skills推薦帖子特別火——因?yàn)樗姆职l(fā)成本實(shí)在太低了。1.2 Skill、Agent、Harness和Prompt到底有什么區(qū)別熱詞搜索里“skill和agent的區(qū)別”“harness和agent區(qū)別”是問(wèn)得最多的兩個(gè)問(wèn)題。很多人被這一堆概念繞暈很正常。我自己剛接觸的時(shí)候也花了很久才理清楚。用大白話講Agent是那個(gè)干活的人它能感知輸入、規(guī)劃步驟、調(diào)用工具、給出結(jié)果。Harness是Agent跑起來(lái)的“運(yùn)行環(huán)境加調(diào)度外殼”負(fù)責(zé)管理上下文、執(zhí)行工具調(diào)用循環(huán)、控制權(quán)限。Skill是Agent的“技能包”給Agent注入某個(gè)具體領(lǐng)域的能力本質(zhì)是結(jié)構(gòu)化的指令加素材加腳本。Prompt是臨時(shí)說(shuō)的一句話每次都在上下文中占位置Skill則可以被索引、按需加載平時(shí)不占用對(duì)話上下文。打個(gè)比方Harness是廚房Agent是廚師Skill是菜譜和刀具工具箱Prompt是客人臨時(shí)說(shuō)的一句“少放辣”。廚師還是那個(gè)廚師但菜譜工具箱越全能做出來(lái)的菜就越豐富臨時(shí)交代的事下次還得重新交代。實(shí)際開(kāi)發(fā)中有個(gè)容易踩的坑很多人把Skill當(dāng)Prompt寫(xiě)以為只要在SKILL.md里多寫(xiě)點(diǎn)規(guī)則就行。其實(shí)Skill真正的價(jià)值在于“結(jié)構(gòu)化加可執(zhí)行”。它不只是告訴Agent“你應(yīng)該怎么做”還能給它配套腳本、模板、校驗(yàn)邏輯讓它在執(zhí)行時(shí)有東西可調(diào)用、有標(biāo)準(zhǔn)可對(duì)照。只有Prompt沒(méi)有工具的Skill本質(zhì)上還是在靠模型臨場(chǎng)發(fā)揮。1.3 拆解一個(gè)完整的Skill內(nèi)部結(jié)構(gòu)與其空講概念不如直接看一個(gè)完整的Skill長(zhǎng)什么樣。以熱詞里出現(xiàn)頻率很高的“結(jié)構(gòu)圖Skills”為例這種技能專門(mén)用來(lái)生成架構(gòu)圖、流程圖、拓?fù)鋱D在寫(xiě)技術(shù)文檔、做方案匯報(bào)時(shí)非常實(shí)用。一個(gè)典型的結(jié)構(gòu)圖Skills目錄如下structure-chart-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_mermaid.py │ └── validate_graph.py └── templates/ ├── architecture_template.mmd └── flow_template.drawioSKILL.md是入口里面用YAML frontmatter定義元信息正文定義執(zhí)行流程。我一般會(huì)寫(xiě)成這樣--- name: structure-chart description: 當(dāng)用戶需要架構(gòu)圖、流程圖、拓?fù)鋱D、時(shí)序圖時(shí)使用。 該技能支持mermaid和drawio兩種輸出格式。 --- 1. 分析用戶描述中的系統(tǒng)組件與調(diào)用關(guān)系。 2. 選擇最合適的圖類型架構(gòu)圖用flowchart時(shí)序圖用sequenceDiagram。 3. 生成mermaid代碼并用scripts/validate_graph.py做語(yǔ)法校驗(yàn)。 4. 輸出mermaid源碼與渲染預(yù)覽必要時(shí)同時(shí)提供drawio XML。 5. 所有節(jié)點(diǎn)命名必須語(yǔ)義化不允許出現(xiàn)node1、node2這類無(wú)意義名稱。注意看description這一行它是Agent判斷“什么時(shí)候該用這個(gè)技能”的關(guān)鍵依據(jù)。這里有個(gè)很多人不知道的細(xì)節(jié)Agent不是把所有Skill都讀進(jìn)上下文而是先根據(jù)當(dāng)前任務(wù)和每個(gè)Skill的description做語(yǔ)義匹配匹配上了才加載正文。所以description寫(xiě)得太泛Agent會(huì)猶豫要不要用寫(xiě)得太窄該用的時(shí)候又想不起來(lái)。最好把“什么場(chǎng)景觸發(fā)”“支持什么輸出格式”都寫(xiě)進(jìn)去。scripts目錄放的是可執(zhí)行腳本generate_mermaid.py負(fù)責(zé)把結(jié)構(gòu)化描述轉(zhuǎn)成圖表代碼validate_graph.py負(fù)責(zé)做語(yǔ)法檢查。templates目錄則是常用模板Agent可以基于模板改參數(shù)不用每次從零生成。整套結(jié)構(gòu)下來(lái)Agent拿到手的是一套完整的生產(chǎn)工具鏈而不是一句空泛的“你可以畫(huà)圖”。2. 主流Agent框架的Skills生態(tài)與選型思路2.1 Claude Code、Codex、OpenCode的Skills實(shí)現(xiàn)有什么不同現(xiàn)在幾乎每個(gè)主流Agent框架都在做自己的Skills機(jī)制但實(shí)現(xiàn)方式各有差異。我先說(shuō)Claude Code官方支持把Skills放在兩個(gè)位置用戶級(jí)目錄~/.claude/skills/適用于所有項(xiàng)目項(xiàng)目級(jí)目錄.claude/skills/只對(duì)當(dāng)前倉(cāng)庫(kù)生效。這種“全局加局部”的設(shè)計(jì)很實(shí)用你把通用技能放在用戶級(jí)把項(xiàng)目特定技能放在倉(cāng)庫(kù)里跟著代碼庫(kù)一起提交團(tuán)隊(duì)成員拉下來(lái)就能用。OpenAI Codex也支持類似的自定義能力不過(guò)它的配置方式更偏向通過(guò)配置文件定義Agent的行為和工具集Skills在其中更像“預(yù)設(shè)工作流”的組成部分。OpenCode作為開(kāi)源社區(qū)里很活躍的終端AI編碼助手Skills生態(tài)也發(fā)展得很快GitHub上已經(jīng)有不少人分享自己的OpenCode Skills倉(cāng)庫(kù)。還有一些像Pi Agent、Hermes Agent這類開(kāi)源Agent項(xiàng)目也在往Skills方向靠不過(guò)迭代比較快具體支持情況建議直接看官方文檔。我用一張表把幾個(gè)常見(jiàn)框架的特點(diǎn)列出來(lái)方便按需選型框架Skills機(jī)制主要特點(diǎn)適合場(chǎng)景Claude Code目錄式SKILL.md支持全局/項(xiàng)目級(jí)生態(tài)成熟觸發(fā)方式豐富日常編碼、文檔、運(yùn)維腳本OpenAI Codex配置文件加自定義工作流與OpenAI模型集成緊密偏代碼生成與重構(gòu)OpenCode開(kāi)源生態(tài)Skills倉(cāng)庫(kù)活躍社區(qū)化配置靈活喜歡自己折騰的開(kāi)發(fā)者Hermes Agent開(kāi)源Agent支持模塊化擴(kuò)展可定制程度高研究型項(xiàng)目、AI Agent開(kāi)發(fā)我的建議是別貪多先選一個(gè)主力框架用熟把Skills的編寫(xiě)和調(diào)試流程跑通再橫向?qū)Ρ绕渌摹９ぞ邠Q來(lái)?yè)Q去最容易讓人學(xué)不會(huì)。2.2 superpower skills這類合集包的正確打開(kāi)方式熱詞里“superpower skills安裝”熱度很高。superpower skills是目前社區(qū)里很出名的Skills合集里面打包了幾十個(gè)常用技能從代碼審查到文檔寫(xiě)作都有。很多人以為裝了它就能一步到位結(jié)果裝上之后發(fā)現(xiàn)Agent反而變“笨”了該調(diào)用的沒(méi)調(diào)用不該調(diào)用的亂調(diào)用。問(wèn)題往往出在“全量安裝”。你想想一個(gè)對(duì)話里塞進(jìn)幾十個(gè)技能的元信息Agent每次做語(yǔ)義匹配都要跟幾十個(gè)description比對(duì)決策成本上去了準(zhǔn)確率自然下降。正確做法是把合集當(dāng)成一個(gè)“技能超市”從里面按需挑選真正用得上的幾個(gè)復(fù)制到自己的skills目錄。安裝方式也很簡(jiǎn)單核心就是拉取項(xiàng)目文件按需復(fù)制# 拉取合集倉(cāng)庫(kù) git clone https://github.com/xxx/superpower-skills.git # 把需要的技能目錄復(fù)制到Claude Code全局skills目錄 cp -r superpower-skills/skills/code-review ~/.claude/skills/這套合集還附帶自己的CLI工具可以通過(guò)npx啟動(dòng)用來(lái)管理技能的安裝和更新。但說(shuō)實(shí)話我更推薦手動(dòng)復(fù)制。原因很簡(jiǎn)單手動(dòng)復(fù)制讓你清楚自己到底裝了哪些東西出了問(wèn)題也好排查全自動(dòng)安裝看著省事裝完了你可能都不知道系統(tǒng)里多了什么。2.3 高頻實(shí)戰(zhàn)Skills推薦結(jié)構(gòu)圖、圖片生成、LaTeX排版從熱搜詞來(lái)看大家最關(guān)心的實(shí)用型Skills集中在結(jié)構(gòu)圖、圖片生成、LaTeX排版、前端開(kāi)發(fā)這幾個(gè)方向。這些確實(shí)是我日常使用頻率最高的類型。結(jié)構(gòu)圖Skills前面已經(jīng)說(shuō)過(guò)適合所有需要輸出圖表的技術(shù)文檔場(chǎng)景實(shí)測(cè)能大幅減少畫(huà)圖時(shí)間。圖片生成Skills的本質(zhì)是封裝一個(gè)圖像生成接口讓Agent能根據(jù)文字描述直接調(diào)用模型生成圖片并保存到本地這種Skills在配圖、素材制作場(chǎng)景很管用安裝時(shí)要注意確認(rèn)腳本依賴的圖像模型API Key是否已配置。LaTeX排版Skills則是學(xué)術(shù)黨利器把Markdown或Word內(nèi)容規(guī)范轉(zhuǎn)換成LaTeX文檔處理中文編譯、圖表交叉引用、參考文獻(xiàn)格式用好了能讓排版效率翻倍。前端開(kāi)發(fā)Skills也是高頻需求。一套好的前端Skills會(huì)包含組件規(guī)范、代碼風(fēng)格約束、項(xiàng)目結(jié)構(gòu)說(shuō)明Agent生成代碼時(shí)會(huì)自動(dòng)遵循團(tuán)隊(duì)約定而不是每次都要臨時(shí)說(shuō)“用TypeScript寫(xiě)、組件放src/components下”。這種“把團(tuán)隊(duì)規(guī)范做成Skill”的做法我特別推薦有前端團(tuán)隊(duì)的人嘗試。除了這幾個(gè)我還建議自己組裝一個(gè)“文檔整理Skills”包含日期格式、標(biāo)題規(guī)范、圖片存放路徑等約束。這個(gè)技能不復(fù)雜但能明顯減少文檔返工率。2.4 用一個(gè)可復(fù)用的評(píng)測(cè)流程判斷Skills好壞熱詞里有“skills怎么測(cè)評(píng)”說(shuō)明大家已經(jīng)不滿足于“裝了就完事”還想知道哪個(gè)更靠譜。這確實(shí)是個(gè)好問(wèn)題。我現(xiàn)在的做法是建一套簡(jiǎn)單的評(píng)測(cè)流程每次拿到新Skills都先過(guò)一遍再?zèng)Q定要不要放到主力環(huán)境。我的評(píng)測(cè)方法分四步固定輸入樣本準(zhǔn)備3到5個(gè)該技能最典型的任務(wù)描述最好覆蓋簡(jiǎn)單、中等、復(fù)雜三種難度。跑通過(guò)率每個(gè)任務(wù)執(zhí)行3次看能不能正常跑到流程結(jié)束記錄報(bào)錯(cuò)情況。檢查穩(wěn)定性同一任務(wù)多次執(zhí)行看輸出質(zhì)量是否穩(wěn)定有沒(méi)有時(shí)好時(shí)壞的情況。觀察上下文占用通過(guò)日志看Skill加載時(shí)消耗了多少token占用過(guò)高的技能要謹(jǐn)慎使用。舉一個(gè)實(shí)際例子我之前測(cè)試過(guò)兩個(gè)LaTeX排版Skills一個(gè)聲稱支持中文一個(gè)沒(méi)寫(xiě)。用同一篇中文文檔做輸入聲稱支持中文的那個(gè)第一次跑就成功編譯通過(guò)另一個(gè)生成的內(nèi)容里中文全部亂碼。光看README根本發(fā)現(xiàn)不了這種差異必須實(shí)測(cè)。所以我強(qiáng)烈建議把“先評(píng)測(cè)再上生產(chǎn)”變成自己的固定流程。3. 手把手開(kāi)發(fā)一個(gè)自己的Skills3.1 先定義能力邊界別一上來(lái)就寫(xiě)代碼很多人第一次開(kāi)發(fā)Skills上來(lái)就打開(kāi)編輯器寫(xiě)SKILL.md寫(xiě)著寫(xiě)著發(fā)現(xiàn)內(nèi)容亂成一團(tuán)。我踩過(guò)這個(gè)坑之后養(yǎng)成了一個(gè)習(xí)慣先回答三個(gè)問(wèn)題再動(dòng)筆。第一這個(gè)技能解決什么具體問(wèn)題要用一句話說(shuō)清楚比如“把Git提交記錄整理成周報(bào)草稿”。第二輸入是什么、輸出是什么比如輸入是項(xiàng)目路徑和日期范圍輸出是Markdown格式的周報(bào)。第三哪些情況明確不處理這個(gè)特別關(guān)鍵沒(méi)寫(xiě)清楚邊界Agent就會(huì)過(guò)度發(fā)揮。比如會(huì)議紀(jì)要Skills可以處理轉(zhuǎn)寫(xiě)文本整理但不處理音頻文件本身這個(gè)邊界必須寫(xiě)明白。定義好這三個(gè)問(wèn)題之后建議再寫(xiě)一個(gè)簡(jiǎn)短的“用戶場(chǎng)景示例”。比如用戶說(shuō)“幫我生成本周周報(bào)”Agent應(yīng)該能根據(jù)這個(gè)描述聯(lián)想到應(yīng)該調(diào)用哪個(gè)Skill。這個(gè)示例會(huì)成為你寫(xiě)description的重要參考。我在開(kāi)發(fā)第一個(gè)Skills的時(shí)候就是因?yàn)闆](méi)定義邊界導(dǎo)致每次任務(wù)都很容易被帶偏。后來(lái)補(bǔ)上了“不處理事項(xiàng)”和“典型觸發(fā)示例”兩段準(zhǔn)確率立刻上來(lái)了。這個(gè)經(jīng)驗(yàn)我覺(jué)得值得大家都在項(xiàng)目里落地。3.2 編寫(xiě)SKILL.md與配套腳本下面用一個(gè)“周報(bào)生成Skills”作為完整示例帶大家走一遍編寫(xiě)流程。先建目錄結(jié)構(gòu)weekly-report-skill/ ├── SKILL.md ├── scripts/ │ └── collect_git_log.py └── templates/ └── weekly_report_template.mdSKILL.md這樣寫(xiě)--- name: weekly-report description: 根據(jù)Git提交記錄生成周報(bào)草稿。 當(dāng)用戶提到“周報(bào)”、“本周工作”、“提交記錄”時(shí)使用。 輸入是項(xiàng)目路徑和日期范圍輸出是Markdown格式周報(bào)。 --- 1. 解析用戶提供的項(xiàng)目路徑和日期范圍默認(rèn)最近7天。 2. 調(diào)用scripts/collect_git_log.py獲取該時(shí)間段的Git提交記錄。 3. 按提交類型分類整理功能開(kāi)發(fā)、Bug修復(fù)、重構(gòu)、文檔、其他。 4. 填充到templates/weekly_report_template.md中。 5. 輸出周報(bào)草稿并提示用戶補(bǔ)充遺漏項(xiàng)。 不處理跨倉(cāng)庫(kù)合并統(tǒng)計(jì)一用戶只統(tǒng)計(jì)指定路徑下的倉(cāng)庫(kù)。配套的collect_git_log.py核心邏輯如下import subprocess import sys from datetime import datetime, timedelta def collect_git_log(repo_path: str, days: int 7) - str: since (datetime.now() - timedelta(daysdays)).strftime(%Y-%m-%d) cmd [ git, -C, repo_path, log, f--since{since}, --prettyformat:%s|%ad, --dateformat:%m-%d ] result subprocess.run(cmd, capture_outputTrue, textTrue, encodingutf-8) return result.stdout if __name__ __main__: repo_path sys.argv[1] days int(sys.argv[2]) if len(sys.argv) 2 else 7 print(collect_git_log(repo_path, days))模板文件就是周報(bào)的Markdown骨架預(yù)留了“本周完成”“下周計(jì)劃”“風(fēng)險(xiǎn)與問(wèn)題”幾個(gè)小節(jié)。這一步最核心的思路是把重復(fù)勞動(dòng)交給腳本把質(zhì)量判斷交給模型。腳本負(fù)責(zé)準(zhǔn)確獲取數(shù)據(jù)模型負(fù)責(zé)語(yǔ)義分析和結(jié)構(gòu)化輸出。這樣分工明確技能才穩(wěn)定。3.3 安裝、觸發(fā)與實(shí)測(cè)迭代寫(xiě)完之后把它放到Claude Code的項(xiàng)目級(jí)skills目錄mkdir -p .claude/skills cp -r weekly-report-skill .claude/skills/重啟會(huì)話后在對(duì)話里輸入“幫我把xxx項(xiàng)目的本周提交整理成周報(bào)”正常情況下Agent會(huì)識(shí)別出這個(gè)任務(wù)屬于weekly-report技能自動(dòng)加載SKILL.md并執(zhí)行流程。如果它沒(méi)觸發(fā)可以試試顯式觸發(fā)在Claude Code里用#weekly-report加上任務(wù)描述。不同框架的顯式觸發(fā)方式可能不同建議先查官方文檔確認(rèn)。第一次跑通只是起步真正的功夫在迭代。我建議拿到結(jié)果后反問(wèn)三個(gè)問(wèn)題輸出結(jié)構(gòu)是不是我想要的哪些步驟可以進(jìn)一步自動(dòng)化有沒(méi)有出現(xiàn)腳本報(bào)錯(cuò)或理解偏差每調(diào)整一次就記錄一下改動(dòng)內(nèi)容。以我自己做的周報(bào)Skill為例第一版只支持單倉(cāng)庫(kù)后來(lái)發(fā)現(xiàn)實(shí)際場(chǎng)景經(jīng)常要匯總多個(gè)子倉(cāng)庫(kù)的提交就改成了接收多個(gè)路徑參數(shù)。又跑了幾周發(fā)現(xiàn)“風(fēng)險(xiǎn)與問(wèn)題”這個(gè)模塊永遠(yuǎn)為空因?yàn)樘峤恍畔⒏究床怀鰜?lái)風(fēng)險(xiǎn)索性改成默認(rèn)不填讓用戶手動(dòng)補(bǔ)充。這些細(xì)節(jié)都是只有長(zhǎng)時(shí)間用下來(lái)才能發(fā)現(xiàn)的一次成型不現(xiàn)實(shí)。4. Agent Skills常見(jiàn)問(wèn)題與排錯(cuò)實(shí)錄4.1 遇到“Agent execution terminated due to error”怎么辦熱詞里有一條“agent execution terminated due to error”這是很多人在使用Agent過(guò)程中遇到的最讓人頭大的報(bào)錯(cuò)——任務(wù)跑得好好的突然就終止了也沒(méi)說(shuō)明白是哪里出錯(cuò)。被這個(gè)問(wèn)題坑多了之后我總結(jié)了一套排查方法。先看錯(cuò)誤日志的尾部信息找到terminated之前的最后一條工具調(diào)用記錄。90%的情況下問(wèn)題都出在那個(gè)工具調(diào)用上。然后單獨(dú)在終端里手動(dòng)執(zhí)行這一步的腳本看它能不能獨(dú)立完成。比如周報(bào)Skill里collect_git_log.py報(bào)錯(cuò)你就手動(dòng)跑一遍python scripts/collect_git_log.py /path/to/repo 7如果腳本本身跑不過(guò)說(shuō)明問(wèn)題在腳本環(huán)境依賴沒(méi)裝、Python版本不對(duì)、路徑寫(xiě)死不存在。這幾類問(wèn)題跟Skill本身沒(méi)多大關(guān)系更多是環(huán)境配置問(wèn)題。如果腳本能跑通那多半是模型生成的調(diào)用參數(shù)有問(wèn)題比如傳了不存在的路徑、參數(shù)格式不對(duì)這時(shí)候要回頭檢查SKILL.md里的參數(shù)說(shuō)明是否清晰有沒(méi)有給出示例值。另外一個(gè)常見(jiàn)原因是執(zhí)行超時(shí)。有些Skill流程里包含耗時(shí)較長(zhǎng)的操作比如大型項(xiàng)目代碼掃描、圖片批量處理Agent內(nèi)置的執(zhí)行超時(shí)時(shí)間到了就會(huì)強(qiáng)制終止。解決辦法是把耗時(shí)步驟拆細(xì)或是在Skill腳本里加上階段性日志輸出讓Agent知道任務(wù)還在推進(jìn)。4.2 Skills裝了卻不生效多半是這幾個(gè)原因“為什么我裝了SkillsAgent根本沒(méi)反應(yīng)”這個(gè)問(wèn)題我收到過(guò)很多次。根據(jù)我的經(jīng)驗(yàn)絕大多數(shù)情況跑不出下面四個(gè)原因。第一目錄位置放錯(cuò)了。Claude Code只認(rèn)兩個(gè)skills目錄要么用戶級(jí)~/.claude/skills/要么項(xiàng)目級(jí).claude/skills/。你放到其他目錄框架根本掃描不到。第二SKILL.md格式不對(duì)。YAML frontmatter必須放在文件最頂部且name和description字段不能省。漏了frontmatter這個(gè)Skill不會(huì)被索引。第三description描述語(yǔ)義匹配不上。你要是寫(xiě)一個(gè)LaTeX排版技能但description里全是“文檔撰寫(xiě)”那Agent遇到排版需求時(shí)壓根不會(huì)考慮它。第四框架版本太老。Skills是較新的特性如果長(zhǎng)時(shí)間沒(méi)更新版本可能根本不支持。判斷是不是第一個(gè)原因最簡(jiǎn)單直接在終端里查看框架是否掃描到了該技能ll ~/.claude/skills/ ll .claude/skills/看看你的技能目錄在不在里面沒(méi)有就是位置不對(duì)。格式和描述問(wèn)題打開(kāi)SKILL.md逐行檢查就可以。4.3 多個(gè)Skills產(chǎn)生沖突時(shí)如何收斂當(dāng)你的Skills數(shù)量多到一定程度會(huì)碰到一個(gè)新問(wèn)題兩個(gè)Skills看起來(lái)都能處理同一個(gè)任務(wù)Agent不知道該選哪個(gè)。比如我同時(shí)裝了“通用文檔Skill”和“LaTeX排版Skill”當(dāng)用戶說(shuō)“把這篇報(bào)告排版一下”Agent就需要在兩者之間做選擇。沖突的核心原因是description覆蓋范圍重疊。解決思路不是把其中一個(gè)刪掉而是明確各自的職責(zé)邊界。我的做法是給每個(gè)Skill的description加上“觸發(fā)器關(guān)鍵詞”和“排除條件”。比如排版Skill里寫(xiě)“當(dāng)用戶需要生成LaTeX或PDF文檔時(shí)使用”通用文檔Skill里寫(xiě)“當(dāng)用戶需要撰寫(xiě)Markdown筆記不涉及LaTeX排版時(shí)使用”。這樣描述清晰了Agent的決策就容易了。還需要注意Skills的加載順序。有些框架會(huì)優(yōu)先加載用戶級(jí)目錄里的技能有些則優(yōu)先項(xiàng)目級(jí)目錄。我的一般原則是項(xiàng)目級(jí)Skills應(yīng)該覆蓋項(xiàng)目特有流程用戶級(jí)Skills負(fù)責(zé)通用能力。如果兩者出現(xiàn)規(guī)則沖突項(xiàng)目級(jí)的優(yōu)先級(jí)應(yīng)該更高。具體怎么配置要看框架文檔不同工具策略不一樣。5. 從Skills到完整Agent開(kāi)發(fā)進(jìn)階學(xué)習(xí)路線5.1 我給新人的Agent開(kāi)發(fā)學(xué)習(xí)路線很多人在熱詞里搜“agent開(kāi)發(fā)學(xué)習(xí)路線”。我的建議很直接不要一上來(lái)就看那些復(fù)雜的Agent框架源碼而是從Skills切入這是一個(gè)最低門(mén)檻的學(xué)習(xí)路徑。第一步熟練使用。先選一個(gè)主流框架日常高頻使用重點(diǎn)體驗(yàn)它是怎么調(diào)度模型、怎么調(diào)用工具、怎么處理多輪任務(wù)的。第二步拆解Skill。GitHub上那些成熟的Skills倉(cāng)庫(kù)是最好的學(xué)習(xí)材料自己動(dòng)手裝幾個(gè)拆開(kāi)看里面SKILL.md的寫(xiě)法、腳本的組織方式。第三步自己寫(xiě)Skill。從最簡(jiǎn)單的技能開(kāi)始練到能獨(dú)立設(shè)計(jì)一個(gè)多腳本協(xié)作的完整技能。第四步上升到框架層面。這時(shí)候再去接觸LangGraph、OpenAI Agents這些框架你會(huì)發(fā)現(xiàn)之前用Skills積累的經(jīng)驗(yàn)全都能用上——工具封裝、上下文管理、語(yǔ)義匹配這些概念在框架層面大同小異。這條路線的好處是每個(gè)階段都有產(chǎn)出。第一步提升效率第二步積累經(jīng)驗(yàn)第三步形成自己的技能庫(kù)第四步才真正進(jìn)入Agent開(kāi)發(fā)的核心。相比一開(kāi)始就啃框架文檔這條路友好得多。5.2 記憶、工具調(diào)用與安全做Agent繞不開(kāi)的三件事熱詞里有“agent記憶”“agent安全”說(shuō)明大家關(guān)注的點(diǎn)在從“能用”往“好用、可靠”遷移。這確實(shí)是Agent開(kāi)發(fā)里三個(gè)繞不開(kāi)的課題。記憶方面Skills本身可以承載一部分記憶功能。短期記憶在上下文里長(zhǎng)期記憶得靠外部存儲(chǔ)比如把執(zhí)行過(guò)的任務(wù)記錄寫(xiě)入文件下次執(zhí)行時(shí)讓Agent先讀取這些記錄。我在周報(bào)Skill里的做法就是讓腳本把每次生成的周報(bào)追加到一個(gè)history.md里后續(xù)生成時(shí)可以參考之前的結(jié)構(gòu)和風(fēng)格。工具調(diào)用是Agent的核心能力。Skills要穩(wěn)定工作依賴清晰的參數(shù)定義和可靠的錯(cuò)誤處理。腳本里必須做好異常捕獲不能讓一個(gè)文件不存在就導(dǎo)致整個(gè)任務(wù)終止。每條外部命令執(zhí)行完都要檢查退出碼有問(wèn)題及時(shí)報(bào)錯(cuò)并給出可理解的提示。安全這塊更要重視。Skills本質(zhì)上給了Agent執(zhí)行本地腳本的權(quán)限這就等于打開(kāi)了系統(tǒng)的一扇門(mén)。我的原則是不裝來(lái)歷不明的Skill對(duì)包含腳本的Skill裝之前先通讀一遍代碼Skill內(nèi)腳本遵循最小權(quán)限涉及刪除、覆蓋文件的操作先確認(rèn)再執(zhí)行。特別是搜索熱詞里那些“skills安裝包”里面可能有收集信息、執(zhí)行網(wǎng)絡(luò)請(qǐng)求的腳本一定要先審后裝。5.3 想面Agent方向這些話題值得提前準(zhǔn)備熱詞里有“agent開(kāi)發(fā)面試題”說(shuō)明很多人在準(zhǔn)備Agent方向的崗位面試。結(jié)合我自己的經(jīng)驗(yàn)面試官問(wèn)來(lái)問(wèn)去其實(shí)就集中在幾個(gè)話題上?，F(xiàn)代Agent架構(gòu)是必問(wèn)的要能講清模型、工具、記憶、執(zhí)行循環(huán)這些組件怎么協(xié)作Skills在其中起什么作用。Agent和RAG的區(qū)別也經(jīng)常出現(xiàn)前者偏向多步驟任務(wù)執(zhí)行后者偏向知識(shí)檢索問(wèn)答。工具調(diào)用一致性、eval設(shè)計(jì)也是高頻題可以參考“agent evals”這個(gè)概念來(lái)準(zhǔn)備。harness和agent的區(qū)別在面試?yán)锍霈F(xiàn)的頻率也在上升尤其是問(wèn)你對(duì)Claude Code這類工具的理解時(shí)。準(zhǔn)備這些話題不建議死記硬背。最好的方法還是自己動(dòng)手做一兩個(gè)Agent小項(xiàng)目把Skills、記憶、工具調(diào)用全走一遍。面試官問(wèn)到一個(gè)點(diǎn)你能隨口說(shuō)出實(shí)際踩過(guò)的坑和解決方案這種真實(shí)經(jīng)驗(yàn)遠(yuǎn)比背概念有說(shuō)服力。最后分享一個(gè)我個(gè)人的工作習(xí)慣。我現(xiàn)在接到一個(gè)新需求第一反應(yīng)永遠(yuǎn)是問(wèn)自己這個(gè)活兒我是不是每周都要干如果是我就花半小時(shí)把整個(gè)流程封裝成一個(gè)Skill以后就不重復(fù)勞動(dòng)。反過(guò)來(lái)如果只是偶爾一次的需求那就直接用臨時(shí)Prompt解決不急著封裝。封裝是有成本和維護(hù)負(fù)擔(dān)的裝得太多、寫(xiě)得太泛反而會(huì)讓Agent變“笨”?？刂坪肧kills的數(shù)量和質(zhì)量讓每個(gè)技能都真正解決一類高頻問(wèn)題這才是Agent工作流能持續(xù)提效的核心。