AI Skill 使用教程從寫好 SKILL.md 到讓智能體正確調(diào)用適合人群使用 AI Agent 的新手、開發(fā)者和團(tuán)隊(duì)成員。本文介紹一種常見的 Agent Skill 組織方式用SKILL.md寫清楚可復(fù)用的工作流程再按需附上參考資料、模板或腳本。不同產(chǎn)品的安裝目錄、發(fā)現(xiàn)機(jī)制和調(diào)用方式可能不同使用前請(qǐng)查看對(duì)應(yīng)工具的說(shuō)明。一、Skill 是什么可以把 Skill 理解為一份給 AI Agent 使用的“專項(xiàng)工作手冊(cè)”。它說(shuō)明遇到哪類任務(wù)時(shí)應(yīng)該采用什么流程、遵守什么規(guī)則、輸出什么結(jié)果。需要時(shí)還可以帶上參考資料、模板或腳本。例如一個(gè)“會(huì)議紀(jì)要整理”Skill 可以規(guī)定先提取會(huì)議結(jié)論和待辦負(fù)責(zé)人或日期缺失時(shí)標(biāo)注“未說(shuō)明”將原文事實(shí)與推測(cè)分開按統(tǒng)一格式輸出。Skill 本身通常不會(huì)自動(dòng)賦予 Agent 新能力。它可以告訴 Agent 如何使用已經(jīng)可用的工具是否能讀寫文件、搜索網(wǎng)頁(yè)或連接應(yīng)用取決于當(dāng)前運(yùn)行環(huán)境提供的權(quán)限和工具。二、Skill、提示詞和工具有什么區(qū)別內(nèi)容主要作用示例提示詞描述當(dāng)前這一輪任務(wù)“總結(jié)這份會(huì)議記錄”Skill保存可反復(fù)使用的任務(wù)流程和約定每次整理會(huì)議紀(jì)要都按同一結(jié)構(gòu)輸出工具讓 Agent 能執(zhí)行具體操作讀取文件、搜索網(wǎng)頁(yè)、運(yùn)行腳本一句話理解提示詞說(shuō)明這次要做什么Skill 提供穩(wěn)定的做法工具提供執(zhí)行能力。三、一個(gè)常見的 Skill 文件結(jié)構(gòu)許多支持 Agent Skills 的工具使用SKILL.md作為入口文件。簡(jiǎn)單的 Skill 只需要這個(gè)文件復(fù)雜流程可以把材料分開放meeting-notes/ ├── SKILL.md # 必需用途、觸發(fā)條件和步驟 ├── references/ │ └── style-guide.md # 可選團(tuán)隊(duì)寫作規(guī)范 ├── assets/ │ └── meeting-template.md # 可選輸出模板 └── scripts/ └── validate.py # 可選重復(fù)性校驗(yàn)?zāi)_本常見分工SKILL.md保留必要說(shuō)明、工作步驟和結(jié)果要求references/放較長(zhǎng)的背景材料或規(guī)范assets/放輸出模板、示例文件等靜態(tài)素材scripts/放可重復(fù)運(yùn)行的腳本或校驗(yàn)程序。剛開始不需要把所有目錄都建出來(lái)先寫清楚一個(gè)可用流程即可。四、編寫第一個(gè) Skill下面以“整理會(huì)議紀(jì)要”為例。新建一個(gè)名為meeting-notes的文件夾并在其中創(chuàng)建SKILL.md--- name: meeting-notes description: 根據(jù)會(huì)議記錄整理結(jié)論、待辦事項(xiàng)和未決問(wèn)題。用戶要求整理、歸納或規(guī)范化會(huì)議記錄時(shí)使用。 --- # 會(huì)議紀(jì)要整理 ## 目標(biāo) 把用戶提供的會(huì)議記錄整理成易檢查的結(jié)構(gòu)化紀(jì)要。 ## 工作步驟 1. 識(shí)別會(huì)議主題、日期和參會(huì)人原文沒(méi)有的信息標(biāo)記“未提供”。 2. 提取明確達(dá)成的結(jié)論不把討論中的設(shè)想寫成已決定事項(xiàng)。 3. 提取待辦事項(xiàng)并記錄負(fù)責(zé)人和截止日期。 4. 將尚未解決的問(wèn)題單獨(dú)列出。 5. 檢查姓名、數(shù)字、日期和行動(dòng)項(xiàng)是否能在原文中找到依據(jù)。 ## 輸出格式 - 會(huì)議主題與日期 - 已確認(rèn)結(jié)論 - 待辦事項(xiàng)事項(xiàng)負(fù)責(zé)人截止日期 - 未決問(wèn)題 ## 邊界 - 只依據(jù)用戶提供的材料不補(bǔ)造事實(shí)。 - 缺少負(fù)責(zé)人或日期時(shí)寫“未說(shuō)明”。 - 不發(fā)送會(huì)議紀(jì)要不修改原始文件。 - 如果材料中包含相互矛盾的信息列出矛盾并請(qǐng)用戶確認(rèn)。這里的name是便于系統(tǒng)識(shí)別的短名稱description要說(shuō)明 Skill 做什么以及何時(shí)應(yīng)該使用。只寫“幫助整理”太寬泛Agent 不容易判斷適用時(shí)機(jī)。五、怎樣讓 Skill 更容易被正確調(diào)用1. 一個(gè) Skill 對(duì)準(zhǔn)一個(gè)明確目標(biāo)不要把“寫文章、調(diào)試代碼、分析表格、整理會(huì)議”全部塞進(jìn)一個(gè) Skill。任務(wù)目標(biāo)差別太大時(shí)分別建立 Skill觸發(fā)條件會(huì)更明確規(guī)則也更容易維護(hù)。2. 在 description 里寫觸發(fā)場(chǎng)景可以用這個(gè)結(jié)構(gòu)[產(chǎn)出或處理什么]。當(dāng)用戶要求[具體任務(wù)或場(chǎng)景]時(shí)使用。例如根據(jù)用戶提供的 CSV 生成數(shù)據(jù)摘要和異常項(xiàng)清單。當(dāng)用戶要求分析、匯總或檢查 CSV 文件時(shí)使用。3. 用步驟替代模糊要求“認(rèn)真分析并給出好結(jié)果”無(wú)法指導(dǎo)具體行動(dòng)。更好的寫法是先檢查字段、再處理空值、然后計(jì)算指標(biāo)、最后說(shuō)明限制條件。4. 寫出停止條件告訴 Agent 什么時(shí)候需要停下來(lái)詢問(wèn)例如材料不足、出現(xiàn)矛盾、需要外部發(fā)送或操作可能修改原始數(shù)據(jù)。六、怎樣安裝和使用 SkillSkill 的文件格式可以相近但每個(gè)平臺(tái)的安裝位置和加載方式并不完全相同。通用步驟如下查看正在使用的 Agent 是否支持SKILL.md或 Agent Skills 格式。按對(duì)應(yīng)平臺(tái)的說(shuō)明把 Skill 文件夾放進(jìn)指定目錄、工作區(qū)或運(yùn)行環(huán)境。檢查 Agent 是否能發(fā)現(xiàn)該 Skill部分工具會(huì)自動(dòng)根據(jù)name和description判斷是否調(diào)用。直接描述具體任務(wù)如果需要明確指定可以在請(qǐng)求中寫“請(qǐng)使用meeting-notesSkill”。檢查輸出是否符合 Skill 的步驟和格式并根據(jù)遺漏調(diào)整說(shuō)明。以 OpenAI 的 Agent Skills 文檔為例Skill 由包含SKILL.md的目錄構(gòu)成可帶參考文件、腳本和素材在 API 執(zhí)行環(huán)境中的掛載方式取決于使用 hosted shell、local shell 或 Agents API。不要把某個(gè)平臺(tái)的安裝路徑直接套用到另一個(gè)工具。七、用真實(shí)任務(wù)迭代 Skill第一次寫出的 Skill 通常只是初稿。可以用幾種不同輸入檢查規(guī)則是否清楚標(biāo)準(zhǔn)情況信息完整的會(huì)議記錄缺項(xiàng)情況沒(méi)有寫日期或負(fù)責(zé)人矛盾情況兩個(gè)段落對(duì)截止時(shí)間寫法不同邊界情況用戶只要求提取某一部分不適用情況用戶問(wèn)的是會(huì)議邀請(qǐng)郵件而不是整理會(huì)議記錄。觀察 Agent 是否在正確任務(wù)中調(diào)用 Skill是否按格式輸出以及遇到缺失信息時(shí)有沒(méi)有亂猜。然后只修改不清楚或容易誤用的說(shuō)明并再次檢查。八、常見問(wèn)題排查Skill 沒(méi)有被調(diào)用檢查description是否包含實(shí)際觸發(fā)場(chǎng)景在任務(wù)中明確說(shuō)“使用某某 Skill”確認(rèn) Skill 已放在正確位置并且當(dāng)前環(huán)境支持這種加載方式。Agent 只遵循了一部分規(guī)則把重要要求改寫成編號(hào)步驟或檢查清單。把主要流程放在SKILL.md不要只藏在未被讀取的附加文件中。SKILL.md 越寫越長(zhǎng)把詳細(xì)規(guī)范、示例或背景資料移到references/并在主文件中說(shuō)明何時(shí)讀取。主文件優(yōu)先保留任務(wù)目標(biāo)、觸發(fā)條件、關(guān)鍵步驟、輸出格式和邊界。不同平臺(tái)上的表現(xiàn)不一致檢查該工具支持的 front matter 字段、目錄約定和加載方式。相同的SKILL.md內(nèi)容不代表每個(gè)平臺(tái)都會(huì)以相同方式加載或調(diào)用。九、安全使用 SkillSkill 文件會(huì)影響 Agent 的判斷和工具使用方式。使用別人提供的 Skill 前先檢查它的指令、腳本和引用文件有沒(méi)有要求上傳或泄露本地資料有沒(méi)有運(yùn)行來(lái)源不明的命令或下載程序有沒(méi)有要求繞過(guò)權(quán)限、確認(rèn)步驟或安全限制腳本會(huì)讀取、覆蓋或刪除哪些文件是否會(huì)把信息發(fā)送給外部服務(wù)只使用任務(wù)所需的最小權(quán)限。涉及發(fā)送、發(fā)布、支付、刪除、生產(chǎn)環(huán)境修改等高影響操作時(shí)應(yīng)保留人工審核和明確確認(rèn)。十、本節(jié)小結(jié)一個(gè)好用的 Skill 不在于寫得很長(zhǎng)而在于目標(biāo)明確、觸發(fā)條件清楚、步驟可執(zhí)行、輸出能檢查、邊界寫完整。先從一個(gè)重復(fù)的小任務(wù)開始用實(shí)際結(jié)果不斷修訂再考慮增加參考資料、模板或腳本。參考資料OpenAI Agent Skills 文檔OpenAIBuild skillsAgent Skills 開放規(guī)范本文關(guān)鍵詞AI Skill、Agent Skills、SKILL.md、AI Agent、智能體工作流、提示詞