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