Skill技能詳解從概念到發(fā)布發(fā)布日期2026-08-07主題CodeBuddy / Codex / Claude 等 AI 編程助手中的 Skill 機(jī)制一、什么是 SkillSkill技能是 AI 編程助手的一種擴(kuò)展能力系統(tǒng)本質(zhì)上是給 AI 提供的一份“專業(yè)培訓(xùn)手冊 工作流模板”。它把某個特定領(lǐng)域的最佳實(shí)踐、操作流程、參考文檔封裝成一個可復(fù)用的模塊讓通用模型在處理該領(lǐng)域任務(wù)時表現(xiàn)得像專家。舉個直白的類比一個通用 AI 助手好比一個什么都會一點(diǎn)的多面手Skill 則像給它發(fā)了一張專科醫(yī)生執(zhí)業(yè)證——遇到對應(yīng)的病癥時它就知道該按什么流程檢查、關(guān)注哪些要點(diǎn)、輸出什么格式的結(jié)果。與 Slash Command斜杠命令的區(qū)別Slash CommandSkill觸發(fā)方式用戶手動輸入/xxxAI根據(jù)任務(wù)自動識別并調(diào)用也可手動觸發(fā)使用場景固定、重復(fù)的操作需要按需加載的專業(yè)能力資源消耗每次輸入都執(zhí)行漸進(jìn)式加載按需讀取codebuddy中skill的位置其他AI編程工具也同理。二、Skill 的目錄結(jié)構(gòu)與文件格式存放位置Skill 必須放在約定的固定位置否則不會被識別.codebuddy/skills/xxx-skill/ # 項(xiàng)目級倉庫根目錄可團(tuán)隊(duì)共享 ~/.codebuddy/skills/xxx-skill/ # 用戶級個人使用注意Skill不能隨便放在項(xiàng)目根目錄。根目錄放的是AGENTS.md項(xiàng)目全局指令兩者職責(zé)不同。目錄內(nèi)部結(jié)構(gòu)一個 Skill 是獨(dú)立目錄至少包含SKILL.mdrelease-docs/ ├── SKILL.md # 必填核心文件 ├── references/ # 參考資料/檢查清單可選 ├── scripts/ # 可執(zhí)行腳本可選 ├── examples/ # 示例輸出可選 └── assets/ # 模板/靜態(tài)資源可選如圖SKILL.md 文件格式SKILL.md由YAML Frontmatter元數(shù)據(jù)Markdown 指令正文兩部分組成。Frontmatter 常用字段字段必填說明name否技能名稱默認(rèn)取目錄名description否最重要幫助 AI 判斷何時使用要寫清晰具體allowed-tools否工具白名單支持模式匹配如Bash(git:*)disable-model-invocation否true時僅可手動/skill-name觸發(fā)user-invocable否false時從/菜單隱藏context否fork時在獨(dú)立 subagent 上下文執(zhí)行agent/model/hooks否配合context: fork使用最小可用的 SKILL.md 示例--- name: pdf description: PDF 文檔解析和轉(zhuǎn)換專家可將 PDF 提取為 Markdown/HTML 等格式 allowed-tools: Read, Write, Bash, WebFetch --- # PDF 處理專家 你是一個專業(yè)的 PDF 文檔處理專家。 ## 核心能力 - 提取 PDF 文本內(nèi)容 - 轉(zhuǎn)換 PDF 為 Markdown、HTML 等格式 ## 工作流程 1. 讀取文檔 2. 提取內(nèi)容 3. 輸出轉(zhuǎn)換結(jié)果三、Skill 的調(diào)用過程Skill 采用的是漸進(jìn)式信息披露Progressive Disclosure機(jī)制核心目的是節(jié)約上下文窗口token。整個調(diào)用分為三個階段第 1 步啟動注冊只讀元數(shù)據(jù)CodeBuddy 啟動時掃描技能目錄對每個 Skill只讀取 Frontmatter 中的namedescription放入 AI 的已知技能清單。此時不讀取正文消耗極小的上下文。第 2 步按需加載匹配觸發(fā)當(dāng)你在對話中提出任務(wù)時AI 將你的需求與每個 Skill 的description進(jìn)行匹配匹配 → 讀取完整的SKILL.md正文獲得審查流程、維度、報告格式等指令不匹配 → 不加載節(jié)省上下文觸發(fā)方式有兩種自動觸發(fā)AI 根據(jù)description判斷任務(wù)相關(guān)主動調(diào)用手動觸發(fā)用戶顯式輸入/skill-name或指名調(diào)用第 3 步運(yùn)行時引用按需讀取參考資料執(zhí)行任務(wù)時AI 按SKILL.md的指引按需打開references/等目錄里對應(yīng)的文件。比如審查前端代碼就讀frontend-checklist.md。這些清單用到才讀不會在每次對話都加載。調(diào)用過程總覽流程圖下圖完整展示了一次 Skill 調(diào)用的流程┌─────────────────┐ │ 用戶提出任務(wù) │ └────────┬────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 【階段一啟動注冊】 │ │ CodeBuddy 掃描技能目錄 │ │ 只讀取各 Skill 的 name description│ └────────┬────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 【階段二按需加載】 │ │ AI 匹配任務(wù)與 description │ └────────┬─────────────┬──────────────┘ │ 匹配 │ 不匹配 ▼ ▼ ┌──────────────────┐ ┌──────────────────────┐ │ 讀取完整 SKILL.md │ │ 不加載該 Skill │ │ 正文流程/維度/ │ │ 節(jié)省上下文 │ │ 報告格式等 │ └──────────────────────┘ └────────┬─────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 【階段三運(yùn)行時引用】 │ │ 按類型按需讀取 references/ 清單 │ │ 如前端→frontend-checklist.md │ └────────┬────────────────────────────┘ │ ▼ ┌──────────────────┐ │ AI 執(zhí)行審查/任務(wù) │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 輸出結(jié)構(gòu)化結(jié)果 │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ 結(jié)束 │ └──────────────────┘圖中三個方框分別對應(yīng)上文三個階段階段一 啟動注冊 → 階段二 按需加載 → 階段三 運(yùn)行時引用。可以看到references/只有在最后階段、且匹配到對應(yīng)類型時才被讀取。誰在讀取需要澄清一個關(guān)鍵點(diǎn)不是某個固定程序在讀取清單而是 AI 模型LLM本身。references/里的清單、SKILL.md里的指令本質(zhì)都是喂給模型的文本。模型利用推理能力逐項(xiàng)核對、判斷、生成報告。因此你補(bǔ)充清單 給 AI 更多審查依據(jù)清單只是提詞器最終判斷靠模型的智能。四、Skill 的發(fā)布與共享發(fā)布方式取決于你想共享的范圍1. 團(tuán)隊(duì)內(nèi)共享最簡單把.codebuddy/skills/目錄隨代碼倉庫提交團(tuán)隊(duì)成員 clone 后技能自動生效。2. 個人分發(fā)把 Skill 目錄放到用戶的~/.codebuddy/skills/或?qū)憘€安裝腳本。3. 插件市場分發(fā)最正式將 Skill 打包成插件發(fā)布到插件市場可被更廣范圍的用戶安裝且不受skillOverrides設(shè)置影響?？梢娦怨芾韘killOverrides可在 settings 中配置控制 Skill 可見性無需修改 SKILL.md值對模型可見在/菜單on名稱 描述是name-only僅名稱是user-invocable-only隱藏是off隱藏隱藏五、最佳實(shí)踐寫 SKILL.md 的建議description要具體?處理文件→ ?PDF 文檔解析和轉(zhuǎn)換專家...提供詳細(xì)的核心能力、工作流程、工具列表只授予必需的工具權(quán)限最小化安全風(fēng)險如Bash(git:*)精確控制復(fù)雜任務(wù)可補(bǔ)充分級標(biāo)準(zhǔn)、邊界約束、示例報告參考下面實(shí)踐案例安全注意事項(xiàng)??admin-trusted 安全閘門來自非內(nèi)置來源的 Skill 的 frontmatterhooks默認(rèn)不會注冊。需在~/.codebuddy/settings.json中設(shè)置allowUntrustedFrontmatterHooks: true才能啟用——這是為了防范惡意 Skill。六、實(shí)踐案例xinjie-review 技能今天我用本倉庫真實(shí)創(chuàng)建了一個全棧審查技能xinjie-review可作為參考模板。NPM倉庫地址https://www.npmjs.com/package/xinjie-review發(fā)布文章Skill 從零編寫到發(fā)布上線目錄結(jié)構(gòu).codebuddy/skills/xinjie-review/ ├── SKILL.md # 核心定義 ├── README.md # 使用說明 ├── references/ # 分類檢查清單 │ ├── frontend-checklist.md │ ├── backend-checklist.md │ ├── style-checklist.md │ ├── document-checklist.md │ ├── flowchart-checklist.md │ └── dependency-security-checklist.md ├── examples/ │ └── sample-review.md # 示例報告 └── scripts/ └── gen-report.sh # 報告生成腳本設(shè)計要點(diǎn)值得借鑒多類型覆蓋SKILL.md 定義了自動識別類型表支持前端/后端/樣式/文檔/流程圖等混合審查統(tǒng)一分級標(biāo)準(zhǔn)為 阻斷 / 嚴(yán)重 / 建議 / 風(fēng)格 定義了明確的判定標(biāo)準(zhǔn)表和優(yōu)先級規(guī)則保證不同模型判定一致邊界約束明確只審查不擅自修改除非用戶明確要求防止審查過程中意外改動代碼PR/MR 審查流程基于git diff的輸出流程支持 Approve / Request changes 結(jié)論示例參照提供examples/sample-review.md讓 AI 首次輸出格式不走樣實(shí)測效果用該技能審查了一段 Vue 登錄組件準(zhǔn)確識別出 阻斷級v-html渲染接口數(shù)據(jù)XSS 風(fēng)險 嚴(yán)重級await無 try/catch 導(dǎo)致 loading 卡死、調(diào)試日志泄露 建議級魔法數(shù)字、高頻輪詢無緩存同時肯定了定時器正確清理等亮點(diǎn)輸出為帶文件 行號 問題 影響 修復(fù)建議的結(jié)構(gòu)化分級報告。七、總結(jié)Skill 是 AI 編程助手中把專家經(jīng)驗(yàn)封裝為可復(fù)用模塊的機(jī)制核心價值在于讓通用模型在特定領(lǐng)域表現(xiàn)更專業(yè)通過漸進(jìn)式披露節(jié)約上下文實(shí)現(xiàn)團(tuán)隊(duì)/社區(qū)的技能復(fù)用與共享如果你要創(chuàng)建一個 Skill記住三步建目錄 → 寫SKILL.md→ 放到約定位置。官方也提供了skill-creator技能輔助初始化。 感謝閱讀想了解更多 我的博客網(wǎng)站 | 記錄思考分享干貨 我的個人主頁 | 關(guān)于我、開源項(xiàng)目