計指南：從臨時腳本到崗位說明書)
最近我在項目里把一堆臨時拼湊的 prompt 腳本收攏成了 3 個規(guī)范的 skills折騰了一周多整個流程才算真正穩(wěn)定下來。這段時間我在 Claude、Codex 這些 Agent 環(huán)境里反復(fù)測試 skills也翻了不少社區(qū)里的技能包最直觀的感受是很多人把 skill 理解為“高級 prompt”其實它更接近一份給 AI 的崗位說明書。今天這篇就圍繞 skills 這個主題把它的設(shè)計思路、目錄規(guī)范、完整案例和常見坑一次說清楚。如果你正在用 Agent 處理代碼、文檔、數(shù)據(jù)分析這類重復(fù)性工作這篇應(yīng)該能幫你少走不少彎路。1. Skills 到底是什么不是工具是給 Agent 的“崗位說明書”1.1 從一段臨時指令到一份崗位說明書大部分人第一次接觸 skills是從類似“給一段代碼寫單元測試”“幫我生成一篇周報”這種需求開始的。常規(guī)做法是把需求寫進(jìn) prompt模型靠著上下文里的幾句說明完成任務(wù)。問題是這些話每次都要重新講而且不同人對同一個任務(wù)的偏好差異很大。Skills 做的事情是把這些“臨時指令”標(biāo)準(zhǔn)化成一套可復(fù)用的協(xié)議。一個 skill 內(nèi)部通常包含任務(wù)拆解步驟、執(zhí)行策略、必要腳本和參考資料。Agent 在運(yùn)行時看到任務(wù)描述會先判斷是否匹配某個 skill匹配成功后再把這份完整協(xié)議注入上下文按協(xié)議干活。打個比方普通 prompt 是你在路邊抓到個臨時工交代“把地掃了”skills 則是一份新人手冊里面寫著用什么掃把、按什么路線掃、垃圾分幾類、驗收標(biāo)準(zhǔn)是什么。這套手冊只要寫一次以后每次召喚都能用。所以我在項目里不再寫“幫我審閱這篇文章”而是給 Agent 掛一個blog-reviewskill。它自己會知道該調(diào)用哪些腳本、該檢查哪些點、輸出格式長什么樣。整個過程看起來像是 Agent“學(xué)會了”一項技能實際上是技能本身包含了一整套可執(zhí)行的上下文。1.2 Skills 與 Function Calling、插件不是一回事有一個問題幾乎每次討論都會遇到skills 和 function calling、插件到底有什么區(qū)別Function Calling 的本質(zhì)是將函數(shù)轉(zhuǎn)成 JSON Schema讓模型根據(jù)用戶意圖選擇函數(shù)并填充參數(shù)。它適合“調(diào)接口”“查數(shù)據(jù)庫”“執(zhí)行某個動作”這類邊界清晰的原子操作。問題是它不負(fù)責(zé)描述完成任務(wù)的整體流程也不包含業(yè)務(wù)規(guī)范。比如“生成單元測試”這個任務(wù)靠一個函數(shù)調(diào)用很難表達(dá)清楚測試風(fēng)格、覆蓋率要求、mock 策略這些細(xì)節(jié)。Skills 更像是把這些細(xì)節(jié)全部打包進(jìn)去的“微 Agent”。它可以在自己的步驟里調(diào)用腳本、讀取目錄、檢查輸出甚至嵌套調(diào)用其他外部工具。相比插件系統(tǒng)skills 的觸發(fā)方式也更貼近模型推理系統(tǒng)先給模型一個技能清單模型根據(jù)場景自行判斷該不該加載某個技能而不是由一個固定的按鈕去激活。當(dāng)然它們并不互斥。實際工程里我經(jīng)常在一個 skill 內(nèi)部去調(diào)用 function calling 暴露的外部 API也可以讓 skill 的腳本調(diào)用現(xiàn)有插件。Skills 提供的是編排層function calling 是最底層的原子操作。把兩者放在對立面是理解上的誤區(qū)。1.3 為什么大家都在談 Skills熱詞背后的真實需求這段時間“前端開發(fā) skills”“codex skills”“superpower skills”這些搜索詞熱度一直很高核心原因并不復(fù)雜Agent 的能力上限不再只取決于模型本身而越來越取決于它有沒有一套高質(zhì)量的任務(wù)協(xié)議。同樣一個代碼審查任務(wù)直接讓模型“看下這段代碼”和給模型一個封裝好的code-reviewskill輸出質(zhì)量差距非常大。后者會把審查維度、優(yōu)先級、項目特定規(guī)范全部帶進(jìn)來產(chǎn)出的結(jié)論可落地得多。這種差距一旦被體驗過就很難回去了。另一個原因是技能的可傳播性。一個寫得好的 skill可以直接推到團(tuán)隊倉庫里復(fù)用。前端的同事不用重新調(diào)教模型拉下來放到指定目錄就能享受同樣的能力。這種知識復(fù)利讓 skills 迅速從個人效率工具演變成了團(tuán)隊資產(chǎn)自然有越來越多人在找技能、寫技能、分享技能。2. 解剖一個 Skill目錄結(jié)構(gòu)、SKILL.md 與元數(shù)據(jù)規(guī)范2.1 一個標(biāo)準(zhǔn)的 Skill 目錄長什么樣在主流的 Agent 平臺里一個 Skill 通常是一個獨立目錄目錄名就是技能名里面放一個 SKILL.md 核心文件再按需配幾個輔助目錄。我第一次看到這個結(jié)構(gòu)的時候覺得它太簡單了后來寫多了才發(fā)現(xiàn)克制才是它最難得的地方。常見的目錄結(jié)構(gòu)是這樣my-skill/ ├── SKILL.md ├── scripts/ │ ├── check_links.py │ └── count_stats.py ├── assets/ │ └── style-guide.pdf └── references/ └── review-checklist.mdSKILL.md是技能的主控文檔負(fù)責(zé)告訴模型“這個技能解決什么問題、按什么步驟做、必須遵守什么邊界”。scripts/放的是可以被模型調(diào)用或手動執(zhí)行的腳本用來完成文檔描述之外的確定性計算。assets/放圖片、PDF、模板等非文本資源。references/放參考資料和清單給模型更多上下文支撐。這個結(jié)構(gòu)設(shè)計的核心思路是把“判斷”和“計算”分開。需要推理、判斷的部分寫進(jìn) SKILL.md交給模型需要穩(wěn)定、精確的部分寫進(jìn) scripts交給代碼。這樣既能發(fā)揮模型的理解能力又能保住確定性操作的可靠性。2.2 SKILL.md 的元數(shù)據(jù)description 和 when_to_use 決定觸發(fā)邊界SKILL.md 頂部通常是一段 YAML frontmatter用鍵值對描述技能基本信息。最關(guān)鍵的兩個字段是description和when_to_use。--- name: code-review description: 對代碼變更進(jìn)行結(jié)構(gòu)化審查覆蓋邏輯、性能、可測試性和代碼風(fēng)格。 when_to_use: 當(dāng)用戶要求審查代碼、PR、diff 或補(bǔ)丁時使用僅需解釋單行代碼含義時不使用。 version: 1.0.0 ---先說description。它會出現(xiàn)在模型的技能索引里是模型判斷“要不要調(diào)用這個技能”的主要依據(jù)。描述寫得越寬泛誤觸發(fā)的概率越高。我見過有人把 description 寫成“處理代碼相關(guān)任務(wù)”結(jié)果用戶問“這段 Python 語法怎么改”都會觸發(fā)代碼審查技能白白浪費(fèi)上下文。when_to_use的作用是反向劃邊界明確“什么時候不該用”。這個字段在社區(qū)早期很容易被忽略但它實際上是降低誤觸發(fā)最有效的工具。好的when_to_use還要寫否定項如果任務(wù)只是修改一句話、不涉及完整交付物就不要強(qiáng)行套技能流程。這兩個字段寫清楚整個技能就成功了一半。因為模型在決策是否加載技能的時候只會看到這幾行摘要而不是整份 SKILL.md。摘要寫得不準(zhǔn)后面再精彩也白搭。2.3 scripts、references、assets讓 Skill 能調(diào)“手腳”SKILL.md 負(fù)責(zé)說“怎么做”但有些事只靠文字約束做不靠譜。比如檢查文章里有沒有殘留的 TODO、統(tǒng)計代碼塊的數(shù)目、把日期規(guī)范化這些都是確定性操作用腳本幾秒鐘就能完成而且不會因為模型狀態(tài)波動出現(xiàn)漏檢。所以我在寫 skill 的時候凡是能落到腳本里的規(guī)則絕不寫進(jìn) SKILL.md 讓模型“自由發(fā)揮”。舉個例子一個文檔技能要求“所有內(nèi)部鏈接必須可訪問”與其在文檔里反復(fù)強(qiáng)調(diào)不如讓腳本去抓鏈接狀態(tài)碼再把結(jié)果喂給模型做判斷。模型只需要負(fù)責(zé)分析結(jié)果、提出修復(fù)建議而不是憑感覺猜測鏈接好不好用。references/目錄里放的是參考資料通常是模型在任務(wù)執(zhí)行過程中需要查閱的規(guī)范文檔、模板段落、歷史案例。注意控制這些文件總長度因為它們最后是要被塞進(jìn)上下文的。一個 200KB 的 PDF 如果直接作為資源引入會瞬間吃光上下文額度。更好的做法是提前提取關(guān)鍵段落或者讓腳本按需讀取而不是一股腦全部注入。3. 從零寫一個能實際跑起來的 Skill博客審校技能完整流程3.1 拿“博客審?！碑?dāng)練手項目先拆能力邊界紙上談兵講再多結(jié)構(gòu)不如親手寫一個。我這邊選一個適合練手的場景博客文章發(fā)布前審校。這個任務(wù)每個人都懂但真要讓 Agent 穩(wěn)定產(chǎn)出可用結(jié)果需要把能力邊界先拆清楚。我定義的審校范圍是檢查文章結(jié)構(gòu)、術(shù)語一致性、代碼示例完整性、數(shù)據(jù)引用可查性、結(jié)論和論據(jù)的匹配度。不屬于這個范圍的比如深度改寫、風(fēng)格重寫、SEO 關(guān)鍵詞布局我明確不碰。邊界畫清楚后技能才不會變成一個什么都想干、什么都干不好的四不像。有了邊界再想技能的工作流先通讀全文建立整體認(rèn)知再用腳本做機(jī)械檢查隨后按嚴(yán)重程度輸出分級問題列表最后給出具體的修改建議。工作流決定了 SKILL.md 的執(zhí)行步驟和輔助腳本的形態(tài)。3.2 建立目錄與編寫 SKILL.md我習(xí)慣在目錄里放一個干凈的可執(zhí)行 demo再慢慢迭代。先建好項目目錄mkdir -p ~/.claude/skills/blog-review/{scripts,references}不同的 Agent 環(huán)境掃描路徑會有一點差異但邏輯一致把技能目錄放到 agent 會掃描的路徑下它就能通過 SKILL.md 識別到技能。接著寫核心文件SKILL.md。我會把執(zhí)行步驟寫得足夠具體但不會死板到剝奪模型自己的判斷空間--- name: blog-review description: 對中文技術(shù)博客做發(fā)布前質(zhì)檢覆蓋結(jié)構(gòu)、術(shù)語、代碼示例、數(shù)據(jù)引用和可讀性。 when_to_use: 當(dāng)用戶要求“審?！薄皺z查”“優(yōu)化”一篇博客或技術(shù)文章且完整文章內(nèi)容已在上下文中時使用。當(dāng)用戶只是問某個段落寫得好不好不需要全文審校時不使用。 version: 1.0.0 --- # 博客審校技能 ## 任務(wù)目標(biāo) 在不改變作者原意和行文風(fēng)格的前提下找出文章中的事實錯誤、邏輯斷點、術(shù)語不統(tǒng)一、代碼示例可運(yùn)行性等問題輸出一份分級修改清單。 ## 執(zhí)行步驟 1. 通讀全文判斷文章類型、目標(biāo)讀者和核心結(jié)論。 2. 檢查標(biāo)題層級是否有跳級、標(biāo)題是否能概括對應(yīng)段落內(nèi)容。 3. 檢查術(shù)語首次出現(xiàn)的專有名詞是否解釋全文是否保持一致。 4. 檢查代碼示例能否獨立運(yùn)行、有無占位內(nèi)容、縮進(jìn)和語法是否完整。 5. 檢查數(shù)據(jù)引用來源是否標(biāo)注數(shù)字前后是否矛盾。 6. 檢查邏輯鏈每個結(jié)論是否有論據(jù)支撐是否存在明顯跳躍。 7. 輸出分級清單按【嚴(yán)重】【建議】【可選】分類每條標(biāo)注位置和修改建議。 ## 輸出格式 每個問題一行格式為 [嚴(yán)重級別] 位置問題描述。修改建議具體做法。 ## 硬性約束 - 不要改動原文風(fēng)格不要代替作者做內(nèi)容擴(kuò)寫。 - 不要輸出模糊評價例如“整體不錯”“部分內(nèi)容可優(yōu)化”必須落到具體位置和具體問題。 - 如果文章本身沒有明顯問題明確寫“未發(fā)現(xiàn)嚴(yán)重問題”不要為了顯得專業(yè)而硬湊問題。寫完這個文件后我意識到一個問題SKILL.md 里的步驟不是越多越好更不是越細(xì)越好。步驟過細(xì)會讓模型變得機(jī)械把全文審校做成逐字逐句的“挑刺”步驟過粗又起不到約束作用。這里的平衡點是只約束關(guān)鍵檢查項和產(chǎn)出格式給模型保留判斷順序和取舍的空間。3.3 配套腳本與審校清單為了讓機(jī)械檢查自動化我寫了一個輔助腳本專門掃描文章中的代碼塊檢查是否存在明顯的占位內(nèi)容#!/usr/bin/env python3 掃描 Markdown 中的代碼塊找出常見的占位內(nèi)容或遺留標(biāo)記。 import re import sys FENCE_PATTERN re.compile(r(\w*)\n(.*?), re.S) def extract_code_blocks(text: str): return FENCE_PATTERN.findall(text) def lint_code_blocks(text: str): problems [] placeholders re.compile(rTODO|待補(bǔ)充|your code here|\.\.\., re.I) for lang, code in extract_code_blocks(text): if placeholders.search(code): problems.append(f[{lang}] 代碼塊中存在占位內(nèi)容需要補(bǔ)充或說明。) return problems if __name__ __main__: content sys.stdin.read() for problem in lint_code_blocks(content): print(problem)腳本寫出來很簡單但它的價值是把“代碼塊里有沒有 TODO”“有沒有明顯省略號”這種高頻檢查項從模型的“經(jīng)驗判斷”變成了確定性的程序檢查。我在實際使用中還會給這個腳本加更多規(guī)則比如檢查內(nèi)鏈狀態(tài)、統(tǒng)計文章字?jǐn)?shù)、提取所有標(biāo)題生成目錄。核心思路不變能腳本化的檢查不靠模型瞎猜。references/review-checklist.md是給人看的審校清單也可以作為模型的補(bǔ)充參考- [ ] 標(biāo)題是否準(zhǔn)確反映文章核心內(nèi)容 - [ ] H1/H2/H3 層級是否跳級 - [ ] 首個技術(shù)術(shù)語是否給出解釋 - [ ] 每個代碼示例是否可獨立運(yùn)行 - [ ] 數(shù)據(jù)來源是否標(biāo)注并可查 - [ ] 結(jié)論是否被論據(jù)支撐 - [ ] 是否有重復(fù)段落或互相矛盾的內(nèi)容這個清單我平時寫博客不一定全走但一旦讓 Agent 做正式審校就會要求它嚴(yán)格對照清單過一遍。當(dāng) SKILL.md 的指令和參考資料里的清單相互配合時輸出穩(wěn)定性明顯提升。3.4 把它接入 Agent 并跑通最小用例目錄建好、文件寫完接入 Agent 實際上只是把它放進(jìn)掃描路徑的問題。但這一步有不少細(xì)節(jié)值得注意。第一路徑放對之后必須做一次“冷啟動測試”開一個新的會話直接把一篇待審校的文章丟給 Agent看它是否會主動觸發(fā)blog-reviewskill。如果它沒有觸發(fā)多半是 description 或 when_to_use 寫得不夠清晰這時候我會優(yōu)先改這兩個字段而不是改 SKILL.md 正文。第二要測試負(fù)樣本給 Agent 一個簡單問題例如“把這句話改得更通順”看它會不會誤觸發(fā)。誤觸發(fā)雖然是上下文浪費(fèi)但更討厭的是模型會按照審校清單把簡單請求搞得很復(fù)雜最后答非所問。第三最小用例要保留。我每次寫完 skill 都會留一份測試文章和對應(yīng)的預(yù)期輸出后續(xù)迭代時只要跑一遍用例就能確認(rèn)改動沒有把原有能力搞壞。這種回歸測試觀念在寫技能的時候很容易被忽略但它帶來的穩(wěn)定性收益非常大。4. 常見平臺接入、場景擴(kuò)展與工作流整合4.1 不同 Agent 環(huán)境下的加載路徑以我實際用過的環(huán)境為例Claude 和 Codex 在 skills 的加載路徑上存在差異。有些環(huán)境支持一條命令把技能注冊進(jìn)配置有些環(huán)境則要求你把技能目錄放到固定位置。不過核心邏輯是相同的Agent 啟動后會掃描技能目錄解析所有 SKILL.md 的元數(shù)據(jù)建立一份技能索引然后在對話中按需注入正文。我踩過的坑是把技能目錄放進(jìn)了“示例文件夾”結(jié)果 Agent 根本沒有掃描它。所以引入新技能后的第一件事不是立刻去驗證技能內(nèi)容而是確認(rèn)它出現(xiàn)在 Agent 的技能清單里。具體怎么做取決于你用哪套環(huán)境但判斷標(biāo)準(zhǔn)都一樣技能被正確索引才談得上觸發(fā)和執(zhí)行。另外regardless of 用什么環(huán)境我都會堅持一個原則技能包要小而精。市面上總有“技能大合集”類的包動輒幾十個 skill 一起裝進(jìn)去?？蓡栴}在于技能索引膨脹后模型選錯技能的概率會顯著上升啟動時的上下文也會被索引占掉不少空間。我只裝當(dāng)前業(yè)務(wù)真正用得到的 3 到 5 個技能效果遠(yuǎn)好過囤一堆。4.2 “Superpowers”這類技能包到底要不要用社區(qū)里現(xiàn)在流行“superpowers”這類技能包把各種生產(chǎn)力流程封裝成大量技能合集。熱詞里也總能看到所以它確實解決了一部分人“不知道有哪些 skills、怎么找 skills”的痛點。我的建議是可以看可以借鑒但不要整套照搬。這類技能包的問題是技能之間往往有依賴關(guān)系或者內(nèi)置了大量通用設(shè)定。直接塞進(jìn)你的環(huán)境要么索引爆炸要么風(fēng)格和你的工作流不一致。更理智的做法是把合集當(dāng)作“技能靈感庫”從里面挑兩三個真正貼合你任務(wù)的單獨拆出來改造。比如我看到某個“superpowers”包里有一個“撰寫技術(shù)方案”的 skill設(shè)計得不錯但我不會直接復(fù)制而是會把它的執(zhí)行步驟拆開替換成我們團(tuán)隊自己的模板和評審標(biāo)準(zhǔn)。這樣既吸收了別人的經(jīng)驗又不至于被別人的假設(shè)綁架。4.3 三個實戰(zhàn)場景前端開發(fā)、論文寫作、分鏡生成Skills 能覆蓋的領(lǐng)域遠(yuǎn)比“寫代碼”寬泛。我按熱詞里的三個典型場景簡單拆一下。前端開發(fā)場景里最常見的 skill 是代碼評審和單測生成。把團(tuán)隊的測試框架約定、覆蓋率門檻、命名規(guī)范寫進(jìn) SKILL.md模型遇到“給這段組件寫測試”時就不再泛泛地生成測試用例而是會按團(tuán)隊的風(fēng)格和約定產(chǎn)出更符合落地要求的代碼。這種技能對團(tuán)隊協(xié)作尤其有用因為約定被固化下來了。論文寫作場景我用過一個“文獻(xiàn)格式檢查”的技能。它把參考文獻(xiàn)的格式規(guī)則、引文順序要求、圖表編號規(guī)范寫進(jìn)技能里配合一個檢查腳本能在論文生成后快速找出格式不一致的地方。比起每次重新描述規(guī)則這種技能可以一次性沉淀幾年的寫作規(guī)范。分鏡生成是另一個很有意思的案例。有人把“腳本轉(zhuǎn)分鏡表”做成了 skill里面規(guī)定了鏡頭編號、景別、時長、機(jī)位、對白等字段模型拿到劇本后能直接輸出標(biāo)準(zhǔn)表格。這個任務(wù)本身并不復(fù)雜難點在于字段定義和表頭規(guī)范而這些恰好是 skills 最擅長固化的東西。我自己的體會是凡是“需要反復(fù)解釋業(yè)務(wù)規(guī)則”的任務(wù)都值得考慮封裝成 skill。判斷標(biāo)準(zhǔn)很簡單如果你發(fā)現(xiàn)自己連續(xù)三次對 Agent 說同一段要求那就是該寫 skill 的信號了。5. 常見問題速查與調(diào)試技巧5.1 安裝新 Skills來源檢查、目錄放置與首輪測試不管你是自己寫技能還是從網(wǎng)上下載社區(qū)技能安裝一個新 skill 的通用路徑就三件事確認(rèn)來源、放到正確的掃描目錄、跑通最小用例。來源檢查放在第一位因為 skill 的本質(zhì)是可執(zhí)行內(nèi)容。SKILL.md 里的指令會進(jìn)入模型上下文scripts/ 里的腳本會在你機(jī)器上運(yùn)行。一個來路不明的技能包里面可能藏著惡意腳本你很難通過看名字判斷出來。所以我會堅持只用自己寫的或者來源可靠、且經(jīng)過逐行審查的技能。目錄放置前面 4.1 已經(jīng)提過不同環(huán)境路徑不同核心是讓它出現(xiàn)在 Agent 的技能索引里。最后一件事是跑最小用例無論多小的 skill都要用一個真實任務(wù)驗證它能被正確觸發(fā)、能產(chǎn)出預(yù)期格式的結(jié)果。這三步缺一不可我見過的絕大多數(shù)安裝問題都出在跳過來源檢查或跳過首輪測試上。5.2 高頻翻車現(xiàn)場與排查思路下面這個表格是我這段時間最常碰到的幾個問題現(xiàn)象可能原因解決思路該觸發(fā)時不觸發(fā)description 沒有覆蓋實際任務(wù)場景用用戶的真實措辭重寫描述不該觸發(fā)時總觸發(fā)when_to_use 缺少否定條件在 when_to_use 中明確“何時不用”每次調(diào)用都要吃大量上下文skills 太大references 注入過重精簡正文腳本按需讀取外部資料輸出格式總是變SKILL.md 的格式說明不夠具體給出一個輸出模板最好配示例腳本報錯導(dǎo)致任務(wù)中斷腳本只測了理想路徑補(bǔ)充異常處理給腳本做邊界輸入測試觸發(fā)問題的根子大多在元數(shù)據(jù)上。我會直接把 SKILL.md 里所有內(nèi)容刪掉只留 frontmatter然后單獨測試 description 和 when_to_use 是否能精準(zhǔn)匹配需求。這兩段過了再恢復(fù)正文。這種“減到不能再減”的調(diào)試方式比盲目改正文高效得多。5.3 調(diào)試 Skills 的四步套路被我用到最多的調(diào)試套路大致分成四步。第一步驗證腳本本身。任何腳本先脫離 Agent 單獨跑輸入輸出都確認(rèn)無誤再接回去。如果腳本本身就有一堆 bug那模型再聰明也救不回來。第二步構(gòu)造最小樣本。不要一上來就用完整的博客文章、上萬行代碼去測試取一個包含典型問題的片段就夠了。這樣每次調(diào)試的反饋回路非常短能快速看出來 SKILL.md 的指令有沒有被執(zhí)行到位。第三步檢查注入結(jié)果。很多 Agent 環(huán)境支持查看最終發(fā)給模型的 system prompt里面有 skill 被加載后的完整內(nèi)容。我會檢查SKILL.md 正文有沒有被截斷、腳本輸出有沒有粘貼對位置、references 的大小是否超出預(yù)期。第四步做回歸記錄。修一次記錄一次“什么問題、改了什么、結(jié)果如何”。這么做看起來麻煩但它讓我在技能迭代多次之后依然清楚每一處改動的原因不至于改著改著把原來的能力弄丟。5.4 安全邊界技能腳本本質(zhì)上就是可執(zhí)行代碼最后想認(rèn)真提醒一點很多人把 skills 當(dāng)成“另一段 prompt”忽略了一個事實——skills 里可以帶腳本腳本會在你本地環(huán)境執(zhí)行。這意味著從不可信渠道獲取 skills等同于直接運(yùn)行陌生人的代碼。我的安全底線是不跑來路不明的技能所有第三方技能必須先人工閱讀 SKILL.md 和全部腳本涉及網(wǎng)絡(luò)請求的腳本要格外小心確認(rèn)它不會把本地數(shù)據(jù)傳出去。曾經(jīng)有人分享過某個“效率小技能”實際腳本會讀取系統(tǒng)環(huán)境變量這種事不是危言聳聽。某些高風(fēng)險領(lǐng)域也一樣比如逆向、滲透、樣本分析相關(guān)的技能。這類技能通常被安全團(tuán)隊用于內(nèi)部審計和授權(quán)測試設(shè)計良好時可以把流程規(guī)范化但前提一定是目標(biāo)具備合法授權(quán)、運(yùn)行環(huán)境是隔離的。普通人不要在未經(jīng)授權(quán)的情況下套用這類技能這不是技術(shù)問題是底線問題。我自己實際用下來最值錢的體會是把 skills 當(dāng)成“判斷力的復(fù)利容器”。每次在 Agent 上調(diào)試出來的標(biāo)準(zhǔn)做法沉淀成一個技能下一次任務(wù)就會從一開始站在上次結(jié)果的肩膀上。與其耗時間追求一個萬能的大技能包不如把手頭三五個高頻任務(wù)打磨到極致。我還在持續(xù)整理手頭的技能集合后面也會繼續(xù)分享怎么寫好 SKILL.md、怎么給技能做版本管理和回歸測試。這東西越早開始積累越值。 AI Agent Skills設(shè)計指南：從臨時腳本到崗位說明書
最近我在項目里把一堆臨時拼湊的 prompt 腳本收攏成了 3 個規(guī)范的 skills折騰了一周多整個流程才算真正穩(wěn)定下來。這段時間我在 Claude、Codex 這些 Agent 環(huán)境里反復(fù)測試 skills也翻了不少社區(qū)里的技能包最直觀的感受是很多人把 skill 理解為“高級 prompt”其實它更接近一份給 AI 的崗位說明書。今天這篇就圍繞 skills 這個主題把它的設(shè)計思路、目錄規(guī)范、完整案例和常見坑一次說清楚。如果你正在用 Agent 處理代碼、文檔、數(shù)據(jù)分析這類重復(fù)性工作這篇應(yīng)該能幫你少走不少彎路。1. Skills 到底是什么不是工具是給 Agent 的“崗位說明書”1.1 從一段臨時指令到一份崗位說明書大部分人第一次接觸 skills是從類似“給一段代碼寫單元測試”“幫我生成一篇周報”這種需求開始的。常規(guī)做法是把需求寫進(jìn) prompt模型靠著上下文里的幾句說明完成任務(wù)。問題是這些話每次都要重新講而且不同人對同一個任務(wù)的偏好差異很大。Skills 做的事情是把這些“臨時指令”標(biāo)準(zhǔn)化成一套可復(fù)用的協(xié)議。一個 skill 內(nèi)部通常包含任務(wù)拆解步驟、執(zhí)行策略、必要腳本和參考資料。Agent 在運(yùn)行時看到任務(wù)描述會先判斷是否匹配某個 skill匹配成功后再把這份完整協(xié)議注入上下文按協(xié)議干活。打個比方普通 prompt 是你在路邊抓到個臨時工交代“把地掃了”skills 則是一份新人手冊里面寫著用什么掃把、按什么路線掃、垃圾分幾類、驗收標(biāo)準(zhǔn)是什么。這套手冊只要寫一次以后每次召喚都能用。所以我在項目里不再寫“幫我審閱這篇文章”而是給 Agent 掛一個blog-reviewskill。它自己會知道該調(diào)用哪些腳本、該檢查哪些點、輸出格式長什么樣。整個過程看起來像是 Agent“學(xué)會了”一項技能實際上是技能本身包含了一整套可執(zhí)行的上下文。1.2 Skills 與 Function Calling、插件不是一回事有一個問題幾乎每次討論都會遇到skills 和 function calling、插件到底有什么區(qū)別Function Calling 的本質(zhì)是將函數(shù)轉(zhuǎn)成 JSON Schema讓模型根據(jù)用戶意圖選擇函數(shù)并填充參數(shù)。它適合“調(diào)接口”“查數(shù)據(jù)庫”“執(zhí)行某個動作”這類邊界清晰的原子操作。問題是它不負(fù)責(zé)描述完成任務(wù)的整體流程也不包含業(yè)務(wù)規(guī)范。比如“生成單元測試”這個任務(wù)靠一個函數(shù)調(diào)用很難表達(dá)清楚測試風(fēng)格、覆蓋率要求、mock 策略這些細(xì)節(jié)。Skills 更像是把這些細(xì)節(jié)全部打包進(jìn)去的“微 Agent”。它可以在自己的步驟里調(diào)用腳本、讀取目錄、檢查輸出甚至嵌套調(diào)用其他外部工具。相比插件系統(tǒng)skills 的觸發(fā)方式也更貼近模型推理系統(tǒng)先給模型一個技能清單模型根據(jù)場景自行判斷該不該加載某個技能而不是由一個固定的按鈕去激活。當(dāng)然它們并不互斥。實際工程里我經(jīng)常在一個 skill 內(nèi)部去調(diào)用 function calling 暴露的外部 API也可以讓 skill 的腳本調(diào)用現(xiàn)有插件。Skills 提供的是編排層function calling 是最底層的原子操作。把兩者放在對立面是理解上的誤區(qū)。1.3 為什么大家都在談 Skills熱詞背后的真實需求這段時間“前端開發(fā) skills”“codex skills”“superpower skills”這些搜索詞熱度一直很高核心原因并不復(fù)雜Agent 的能力上限不再只取決于模型本身而越來越取決于它有沒有一套高質(zhì)量的任務(wù)協(xié)議。同樣一個代碼審查任務(wù)直接讓模型“看下這段代碼”和給模型一個封裝好的code-reviewskill輸出質(zhì)量差距非常大。后者會把審查維度、優(yōu)先級、項目特定規(guī)范全部帶進(jìn)來產(chǎn)出的結(jié)論可落地得多。這種差距一旦被體驗過就很難回去了。另一個原因是技能的可傳播性。一個寫得好的 skill可以直接推到團(tuán)隊倉庫里復(fù)用。前端的同事不用重新調(diào)教模型拉下來放到指定目錄就能享受同樣的能力。這種知識復(fù)利讓 skills 迅速從個人效率工具演變成了團(tuán)隊資產(chǎn)自然有越來越多人在找技能、寫技能、分享技能。2. 解剖一個 Skill目錄結(jié)構(gòu)、SKILL.md 與元數(shù)據(jù)規(guī)范2.1 一個標(biāo)準(zhǔn)的 Skill 目錄長什么樣在主流的 Agent 平臺里一個 Skill 通常是一個獨立目錄目錄名就是技能名里面放一個 SKILL.md 核心文件再按需配幾個輔助目錄。我第一次看到這個結(jié)構(gòu)的時候覺得它太簡單了后來寫多了才發(fā)現(xiàn)克制才是它最難得的地方。常見的目錄結(jié)構(gòu)是這樣my-skill/ ├── SKILL.md ├── scripts/ │ ├── check_links.py │ └── count_stats.py ├── assets/ │ └── style-guide.pdf └── references/ └── review-checklist.mdSKILL.md是技能的主控文檔負(fù)責(zé)告訴模型“這個技能解決什么問題、按什么步驟做、必須遵守什么邊界”。scripts/放的是可以被模型調(diào)用或手動執(zhí)行的腳本用來完成文檔描述之外的確定性計算。assets/放圖片、PDF、模板等非文本資源。references/放參考資料和清單給模型更多上下文支撐。這個結(jié)構(gòu)設(shè)計的核心思路是把“判斷”和“計算”分開。需要推理、判斷的部分寫進(jìn) SKILL.md交給模型需要穩(wěn)定、精確的部分寫進(jìn) scripts交給代碼。這樣既能發(fā)揮模型的理解能力又能保住確定性操作的可靠性。2.2 SKILL.md 的元數(shù)據(jù)description 和 when_to_use 決定觸發(fā)邊界SKILL.md 頂部通常是一段 YAML frontmatter用鍵值對描述技能基本信息。最關(guān)鍵的兩個字段是description和when_to_use。--- name: code-review description: 對代碼變更進(jìn)行結(jié)構(gòu)化審查覆蓋邏輯、性能、可測試性和代碼風(fēng)格。 when_to_use: 當(dāng)用戶要求審查代碼、PR、diff 或補(bǔ)丁時使用僅需解釋單行代碼含義時不使用。 version: 1.0.0 ---先說description。它會出現(xiàn)在模型的技能索引里是模型判斷“要不要調(diào)用這個技能”的主要依據(jù)。描述寫得越寬泛誤觸發(fā)的概率越高。我見過有人把 description 寫成“處理代碼相關(guān)任務(wù)”結(jié)果用戶問“這段 Python 語法怎么改”都會觸發(fā)代碼審查技能白白浪費(fèi)上下文。when_to_use的作用是反向劃邊界明確“什么時候不該用”。這個字段在社區(qū)早期很容易被忽略但它實際上是降低誤觸發(fā)最有效的工具。好的when_to_use還要寫否定項如果任務(wù)只是修改一句話、不涉及完整交付物就不要強(qiáng)行套技能流程。這兩個字段寫清楚整個技能就成功了一半。因為模型在決策是否加載技能的時候只會看到這幾行摘要而不是整份 SKILL.md。摘要寫得不準(zhǔn)后面再精彩也白搭。2.3 scripts、references、assets讓 Skill 能調(diào)“手腳”SKILL.md 負(fù)責(zé)說“怎么做”但有些事只靠文字約束做不靠譜。比如檢查文章里有沒有殘留的 TODO、統(tǒng)計代碼塊的數(shù)目、把日期規(guī)范化這些都是確定性操作用腳本幾秒鐘就能完成而且不會因為模型狀態(tài)波動出現(xiàn)漏檢。所以我在寫 skill 的時候凡是能落到腳本里的規(guī)則絕不寫進(jìn) SKILL.md 讓模型“自由發(fā)揮”。舉個例子一個文檔技能要求“所有內(nèi)部鏈接必須可訪問”與其在文檔里反復(fù)強(qiáng)調(diào)不如讓腳本去抓鏈接狀態(tài)碼再把結(jié)果喂給模型做判斷。模型只需要負(fù)責(zé)分析結(jié)果、提出修復(fù)建議而不是憑感覺猜測鏈接好不好用。references/目錄里放的是參考資料通常是模型在任務(wù)執(zhí)行過程中需要查閱的規(guī)范文檔、模板段落、歷史案例。注意控制這些文件總長度因為它們最后是要被塞進(jìn)上下文的。一個 200KB 的 PDF 如果直接作為資源引入會瞬間吃光上下文額度。更好的做法是提前提取關(guān)鍵段落或者讓腳本按需讀取而不是一股腦全部注入。3. 從零寫一個能實際跑起來的 Skill博客審校技能完整流程3.1 拿“博客審?！碑?dāng)練手項目先拆能力邊界紙上談兵講再多結(jié)構(gòu)不如親手寫一個。我這邊選一個適合練手的場景博客文章發(fā)布前審校。這個任務(wù)每個人都懂但真要讓 Agent 穩(wěn)定產(chǎn)出可用結(jié)果需要把能力邊界先拆清楚。我定義的審校范圍是檢查文章結(jié)構(gòu)、術(shù)語一致性、代碼示例完整性、數(shù)據(jù)引用可查性、結(jié)論和論據(jù)的匹配度。不屬于這個范圍的比如深度改寫、風(fēng)格重寫、SEO 關(guān)鍵詞布局我明確不碰。邊界畫清楚后技能才不會變成一個什么都想干、什么都干不好的四不像。有了邊界再想技能的工作流先通讀全文建立整體認(rèn)知再用腳本做機(jī)械檢查隨后按嚴(yán)重程度輸出分級問題列表最后給出具體的修改建議。工作流決定了 SKILL.md 的執(zhí)行步驟和輔助腳本的形態(tài)。3.2 建立目錄與編寫 SKILL.md我習(xí)慣在目錄里放一個干凈的可執(zhí)行 demo再慢慢迭代。先建好項目目錄mkdir -p ~/.claude/skills/blog-review/{scripts,references}不同的 Agent 環(huán)境掃描路徑會有一點差異但邏輯一致把技能目錄放到 agent 會掃描的路徑下它就能通過 SKILL.md 識別到技能。接著寫核心文件SKILL.md。我會把執(zhí)行步驟寫得足夠具體但不會死板到剝奪模型自己的判斷空間--- name: blog-review description: 對中文技術(shù)博客做發(fā)布前質(zhì)檢覆蓋結(jié)構(gòu)、術(shù)語、代碼示例、數(shù)據(jù)引用和可讀性。 when_to_use: 當(dāng)用戶要求“審?！薄皺z查”“優(yōu)化”一篇博客或技術(shù)文章且完整文章內(nèi)容已在上下文中時使用。當(dāng)用戶只是問某個段落寫得好不好不需要全文審校時不使用。 version: 1.0.0 --- # 博客審校技能 ## 任務(wù)目標(biāo) 在不改變作者原意和行文風(fēng)格的前提下找出文章中的事實錯誤、邏輯斷點、術(shù)語不統(tǒng)一、代碼示例可運(yùn)行性等問題輸出一份分級修改清單。 ## 執(zhí)行步驟 1. 通讀全文判斷文章類型、目標(biāo)讀者和核心結(jié)論。 2. 檢查標(biāo)題層級是否有跳級、標(biāo)題是否能概括對應(yīng)段落內(nèi)容。 3. 檢查術(shù)語首次出現(xiàn)的專有名詞是否解釋全文是否保持一致。 4. 檢查代碼示例能否獨立運(yùn)行、有無占位內(nèi)容、縮進(jìn)和語法是否完整。 5. 檢查數(shù)據(jù)引用來源是否標(biāo)注數(shù)字前后是否矛盾。 6. 檢查邏輯鏈每個結(jié)論是否有論據(jù)支撐是否存在明顯跳躍。 7. 輸出分級清單按【嚴(yán)重】【建議】【可選】分類每條標(biāo)注位置和修改建議。 ## 輸出格式 每個問題一行格式為 [嚴(yán)重級別] 位置問題描述。修改建議具體做法。 ## 硬性約束 - 不要改動原文風(fēng)格不要代替作者做內(nèi)容擴(kuò)寫。 - 不要輸出模糊評價例如“整體不錯”“部分內(nèi)容可優(yōu)化”必須落到具體位置和具體問題。 - 如果文章本身沒有明顯問題明確寫“未發(fā)現(xiàn)嚴(yán)重問題”不要為了顯得專業(yè)而硬湊問題。寫完這個文件后我意識到一個問題SKILL.md 里的步驟不是越多越好更不是越細(xì)越好。步驟過細(xì)會讓模型變得機(jī)械把全文審校做成逐字逐句的“挑刺”步驟過粗又起不到約束作用。這里的平衡點是只約束關(guān)鍵檢查項和產(chǎn)出格式給模型保留判斷順序和取舍的空間。3.3 配套腳本與審校清單為了讓機(jī)械檢查自動化我寫了一個輔助腳本專門掃描文章中的代碼塊檢查是否存在明顯的占位內(nèi)容#!/usr/bin/env python3 掃描 Markdown 中的代碼塊找出常見的占位內(nèi)容或遺留標(biāo)記。 import re import sys FENCE_PATTERN re.compile(r(\w*)\n(.*?), re.S) def extract_code_blocks(text: str): return FENCE_PATTERN.findall(text) def lint_code_blocks(text: str): problems [] placeholders re.compile(rTODO|待補(bǔ)充|your code here|\.\.\., re.I) for lang, code in extract_code_blocks(text): if placeholders.search(code): problems.append(f[{lang}] 代碼塊中存在占位內(nèi)容需要補(bǔ)充或說明。) return problems if __name__ __main__: content sys.stdin.read() for problem in lint_code_blocks(content): print(problem)腳本寫出來很簡單但它的價值是把“代碼塊里有沒有 TODO”“有沒有明顯省略號”這種高頻檢查項從模型的“經(jīng)驗判斷”變成了確定性的程序檢查。我在實際使用中還會給這個腳本加更多規(guī)則比如檢查內(nèi)鏈狀態(tài)、統(tǒng)計文章字?jǐn)?shù)、提取所有標(biāo)題生成目錄。核心思路不變能腳本化的檢查不靠模型瞎猜。references/review-checklist.md是給人看的審校清單也可以作為模型的補(bǔ)充參考- [ ] 標(biāo)題是否準(zhǔn)確反映文章核心內(nèi)容 - [ ] H1/H2/H3 層級是否跳級 - [ ] 首個技術(shù)術(shù)語是否給出解釋 - [ ] 每個代碼示例是否可獨立運(yùn)行 - [ ] 數(shù)據(jù)來源是否標(biāo)注并可查 - [ ] 結(jié)論是否被論據(jù)支撐 - [ ] 是否有重復(fù)段落或互相矛盾的內(nèi)容這個清單我平時寫博客不一定全走但一旦讓 Agent 做正式審校就會要求它嚴(yán)格對照清單過一遍。當(dāng) SKILL.md 的指令和參考資料里的清單相互配合時輸出穩(wěn)定性明顯提升。3.4 把它接入 Agent 并跑通最小用例目錄建好、文件寫完接入 Agent 實際上只是把它放進(jìn)掃描路徑的問題。但這一步有不少細(xì)節(jié)值得注意。第一路徑放對之后必須做一次“冷啟動測試”開一個新的會話直接把一篇待審校的文章丟給 Agent看它是否會主動觸發(fā)blog-reviewskill。如果它沒有觸發(fā)多半是 description 或 when_to_use 寫得不夠清晰這時候我會優(yōu)先改這兩個字段而不是改 SKILL.md 正文。第二要測試負(fù)樣本給 Agent 一個簡單問題例如“把這句話改得更通順”看它會不會誤觸發(fā)。誤觸發(fā)雖然是上下文浪費(fèi)但更討厭的是模型會按照審校清單把簡單請求搞得很復(fù)雜最后答非所問。第三最小用例要保留。我每次寫完 skill 都會留一份測試文章和對應(yīng)的預(yù)期輸出后續(xù)迭代時只要跑一遍用例就能確認(rèn)改動沒有把原有能力搞壞。這種回歸測試觀念在寫技能的時候很容易被忽略但它帶來的穩(wěn)定性收益非常大。4. 常見平臺接入、場景擴(kuò)展與工作流整合4.1 不同 Agent 環(huán)境下的加載路徑以我實際用過的環(huán)境為例Claude 和 Codex 在 skills 的加載路徑上存在差異。有些環(huán)境支持一條命令把技能注冊進(jìn)配置有些環(huán)境則要求你把技能目錄放到固定位置。不過核心邏輯是相同的Agent 啟動后會掃描技能目錄解析所有 SKILL.md 的元數(shù)據(jù)建立一份技能索引然后在對話中按需注入正文。我踩過的坑是把技能目錄放進(jìn)了“示例文件夾”結(jié)果 Agent 根本沒有掃描它。所以引入新技能后的第一件事不是立刻去驗證技能內(nèi)容而是確認(rèn)它出現(xiàn)在 Agent 的技能清單里。具體怎么做取決于你用哪套環(huán)境但判斷標(biāo)準(zhǔn)都一樣技能被正確索引才談得上觸發(fā)和執(zhí)行。另外regardless of 用什么環(huán)境我都會堅持一個原則技能包要小而精。市面上總有“技能大合集”類的包動輒幾十個 skill 一起裝進(jìn)去?？蓡栴}在于技能索引膨脹后模型選錯技能的概率會顯著上升啟動時的上下文也會被索引占掉不少空間。我只裝當(dāng)前業(yè)務(wù)真正用得到的 3 到 5 個技能效果遠(yuǎn)好過囤一堆。4.2 “Superpowers”這類技能包到底要不要用社區(qū)里現(xiàn)在流行“superpowers”這類技能包把各種生產(chǎn)力流程封裝成大量技能合集。熱詞里也總能看到所以它確實解決了一部分人“不知道有哪些 skills、怎么找 skills”的痛點。我的建議是可以看可以借鑒但不要整套照搬。這類技能包的問題是技能之間往往有依賴關(guān)系或者內(nèi)置了大量通用設(shè)定。直接塞進(jìn)你的環(huán)境要么索引爆炸要么風(fēng)格和你的工作流不一致。更理智的做法是把合集當(dāng)作“技能靈感庫”從里面挑兩三個真正貼合你任務(wù)的單獨拆出來改造。比如我看到某個“superpowers”包里有一個“撰寫技術(shù)方案”的 skill設(shè)計得不錯但我不會直接復(fù)制而是會把它的執(zhí)行步驟拆開替換成我們團(tuán)隊自己的模板和評審標(biāo)準(zhǔn)。這樣既吸收了別人的經(jīng)驗又不至于被別人的假設(shè)綁架。4.3 三個實戰(zhàn)場景前端開發(fā)、論文寫作、分鏡生成Skills 能覆蓋的領(lǐng)域遠(yuǎn)比“寫代碼”寬泛。我按熱詞里的三個典型場景簡單拆一下。前端開發(fā)場景里最常見的 skill 是代碼評審和單測生成。把團(tuán)隊的測試框架約定、覆蓋率門檻、命名規(guī)范寫進(jìn) SKILL.md模型遇到“給這段組件寫測試”時就不再泛泛地生成測試用例而是會按團(tuán)隊的風(fēng)格和約定產(chǎn)出更符合落地要求的代碼。這種技能對團(tuán)隊協(xié)作尤其有用因為約定被固化下來了。論文寫作場景我用過一個“文獻(xiàn)格式檢查”的技能。它把參考文獻(xiàn)的格式規(guī)則、引文順序要求、圖表編號規(guī)范寫進(jìn)技能里配合一個檢查腳本能在論文生成后快速找出格式不一致的地方。比起每次重新描述規(guī)則這種技能可以一次性沉淀幾年的寫作規(guī)范。分鏡生成是另一個很有意思的案例。有人把“腳本轉(zhuǎn)分鏡表”做成了 skill里面規(guī)定了鏡頭編號、景別、時長、機(jī)位、對白等字段模型拿到劇本后能直接輸出標(biāo)準(zhǔn)表格。這個任務(wù)本身并不復(fù)雜難點在于字段定義和表頭規(guī)范而這些恰好是 skills 最擅長固化的東西。我自己的體會是凡是“需要反復(fù)解釋業(yè)務(wù)規(guī)則”的任務(wù)都值得考慮封裝成 skill。判斷標(biāo)準(zhǔn)很簡單如果你發(fā)現(xiàn)自己連續(xù)三次對 Agent 說同一段要求那就是該寫 skill 的信號了。5. 常見問題速查與調(diào)試技巧5.1 安裝新 Skills來源檢查、目錄放置與首輪測試不管你是自己寫技能還是從網(wǎng)上下載社區(qū)技能安裝一個新 skill 的通用路徑就三件事確認(rèn)來源、放到正確的掃描目錄、跑通最小用例。來源檢查放在第一位因為 skill 的本質(zhì)是可執(zhí)行內(nèi)容。SKILL.md 里的指令會進(jìn)入模型上下文scripts/ 里的腳本會在你機(jī)器上運(yùn)行。一個來路不明的技能包里面可能藏著惡意腳本你很難通過看名字判斷出來。所以我會堅持只用自己寫的或者來源可靠、且經(jīng)過逐行審查的技能。目錄放置前面 4.1 已經(jīng)提過不同環(huán)境路徑不同核心是讓它出現(xiàn)在 Agent 的技能索引里。最后一件事是跑最小用例無論多小的 skill都要用一個真實任務(wù)驗證它能被正確觸發(fā)、能產(chǎn)出預(yù)期格式的結(jié)果。這三步缺一不可我見過的絕大多數(shù)安裝問題都出在跳過來源檢查或跳過首輪測試上。5.2 高頻翻車現(xiàn)場與排查思路下面這個表格是我這段時間最常碰到的幾個問題現(xiàn)象可能原因解決思路該觸發(fā)時不觸發(fā)description 沒有覆蓋實際任務(wù)場景用用戶的真實措辭重寫描述不該觸發(fā)時總觸發(fā)when_to_use 缺少否定條件在 when_to_use 中明確“何時不用”每次調(diào)用都要吃大量上下文skills 太大references 注入過重精簡正文腳本按需讀取外部資料輸出格式總是變SKILL.md 的格式說明不夠具體給出一個輸出模板最好配示例腳本報錯導(dǎo)致任務(wù)中斷腳本只測了理想路徑補(bǔ)充異常處理給腳本做邊界輸入測試觸發(fā)問題的根子大多在元數(shù)據(jù)上。我會直接把 SKILL.md 里所有內(nèi)容刪掉只留 frontmatter然后單獨測試 description 和 when_to_use 是否能精準(zhǔn)匹配需求。這兩段過了再恢復(fù)正文。這種“減到不能再減”的調(diào)試方式比盲目改正文高效得多。5.3 調(diào)試 Skills 的四步套路被我用到最多的調(diào)試套路大致分成四步。第一步驗證腳本本身。任何腳本先脫離 Agent 單獨跑輸入輸出都確認(rèn)無誤再接回去。如果腳本本身就有一堆 bug那模型再聰明也救不回來。第二步構(gòu)造最小樣本。不要一上來就用完整的博客文章、上萬行代碼去測試取一個包含典型問題的片段就夠了。這樣每次調(diào)試的反饋回路非常短能快速看出來 SKILL.md 的指令有沒有被執(zhí)行到位。第三步檢查注入結(jié)果。很多 Agent 環(huán)境支持查看最終發(fā)給模型的 system prompt里面有 skill 被加載后的完整內(nèi)容。我會檢查SKILL.md 正文有沒有被截斷、腳本輸出有沒有粘貼對位置、references 的大小是否超出預(yù)期。第四步做回歸記錄。修一次記錄一次“什么問題、改了什么、結(jié)果如何”。這么做看起來麻煩但它讓我在技能迭代多次之后依然清楚每一處改動的原因不至于改著改著把原來的能力弄丟。5.4 安全邊界技能腳本本質(zhì)上就是可執(zhí)行代碼最后想認(rèn)真提醒一點很多人把 skills 當(dāng)成“另一段 prompt”忽略了一個事實——skills 里可以帶腳本腳本會在你本地環(huán)境執(zhí)行。這意味著從不可信渠道獲取 skills等同于直接運(yùn)行陌生人的代碼。我的安全底線是不跑來路不明的技能所有第三方技能必須先人工閱讀 SKILL.md 和全部腳本涉及網(wǎng)絡(luò)請求的腳本要格外小心確認(rèn)它不會把本地數(shù)據(jù)傳出去。曾經(jīng)有人分享過某個“效率小技能”實際腳本會讀取系統(tǒng)環(huán)境變量這種事不是危言聳聽。某些高風(fēng)險領(lǐng)域也一樣比如逆向、滲透、樣本分析相關(guān)的技能。這類技能通常被安全團(tuán)隊用于內(nèi)部審計和授權(quán)測試設(shè)計良好時可以把流程規(guī)范化但前提一定是目標(biāo)具備合法授權(quán)、運(yùn)行環(huán)境是隔離的。普通人不要在未經(jīng)授權(quán)的情況下套用這類技能這不是技術(shù)問題是底線問題。我自己實際用下來最值錢的體會是把 skills 當(dāng)成“判斷力的復(fù)利容器”。每次在 Agent 上調(diào)試出來的標(biāo)準(zhǔn)做法沉淀成一個技能下一次任務(wù)就會從一開始站在上次結(jié)果的肩膀上。與其耗時間追求一個萬能的大技能包不如把手頭三五個高頻任務(wù)打磨到極致。我還在持續(xù)整理手頭的技能集合后面也會繼續(xù)分享怎么寫好 SKILL.md、怎么給技能做版本管理和回歸測試。這東西越早開始積累越值。