最近在整理 AI Agent 相關(guān)技術(shù)方案時頻繁看到 Addy Osmani 這個名字。作為 Google Chrome 團隊的前端工程經(jīng)理他出品的不少技術(shù)資料在 GitHub 上都相當有分量。這次要拆解的項目是一個 GitHub 上 7.9 萬 Star 的生產(chǎn)級 agent skill 合集排在本月熱門 S2 榜單第 6 位可以說是 AI 工程化領(lǐng)域不可忽略的參考資源。本文將圍繞這個項目展開先講清楚 agent 與 skill 的關(guān)系再拆解生產(chǎn)級 skill 應當具備的結(jié)構(gòu)最后基于項目思路給出可復用的實戰(zhàn)流程。無論你是剛接觸 AI Agent 的開發(fā)者還是已經(jīng)在做企業(yè)級智能體落地的工程師這篇文章都能提供一條清晰的行動路徑。1. 背景與核心概念為什么 agent skill 會火起來1.1 什么是 agent skillAgent skill 可以理解為給 AI 智能體準備的“可復用能力包”。它通常包含一份結(jié)構(gòu)化的說明文檔、若干示例、約束規(guī)則以及可選的工具調(diào)用框架目的是讓 Agent 在特定業(yè)務(wù)場景下能穩(wěn)定、可預期地完成一類任務(wù)。舉個例子如果希望 AI 助手能幫團隊完成代碼審查不需要每次都寫一段很長的“請你檢查代碼”提示詞而是準備一個code-review-skill目錄里面寫好審查規(guī)范、檢查清單、輸出格式甚至附上幾個歷史案例。Agent 在執(zhí)行任務(wù)時會讀取這個 skill像專業(yè)工程師一樣按照固定流程完成工作。之所以說它是“生產(chǎn)級”核心在于它不僅關(guān)注單次對話效果還關(guān)注輸入輸出穩(wěn)定性、失敗處理、可維護性和團隊協(xié)作效率。相比臨時拼湊的提示詞生產(chǎn)級 skill 更接近代碼工程。1.2 Agent、Skill 與 Prompt 之間的關(guān)系這里有必要區(qū)分幾個容易被混用的概念概念定位舉例Prompt一段指令文本“請寫一個 Python 函數(shù)”Skill結(jié)構(gòu)化的能力包代碼審查規(guī)則 示例 輸出模板Agent會調(diào)用 skill 的智能體能根據(jù)任務(wù)自動選擇 code-review-skill 的助手可以這么理解Prompt 是一次性的對話輸入Skill 是可復用的“領(lǐng)域插件”Agent 是真正思考、規(guī)劃、執(zhí)行的主體。Skill 是 Agent 與具體業(yè)務(wù)之間的橋梁讓 Agent 不用每次從零理解需求。在 Addy Osmani 的項目中skill 被整理得非常規(guī)范每個 skill 都像一個小型 npm 包有元信息、核心邏輯、測試用例這給團隊內(nèi)部沉淀 AI 能力提供了很好的參考。1.3 為什么開發(fā)者需要掌握生產(chǎn)級 skill在一次生產(chǎn)環(huán)境 AI 項目落地中我遇到過這樣的情況讓 AI 自動生成數(shù)據(jù)庫變更腳本開發(fā)者在提示詞里寫了很多要求但 AI 仍然會偶爾生成不帶 WHERE 條件的 DELETE 語句。這就是只依賴 Prompt 的典型風險。生產(chǎn)級 skill 的價值就在這里它把約束前置、把驗證閉環(huán)、把失敗兜底真正讓 AI 在可控范圍內(nèi)工作。這也是 Addy Osmani 這個項目能收獲近 8 萬 Star 的根本原因——它不是講概念而是提供了可以直接拿到業(yè)務(wù)里用的工程化方案。2. 環(huán)境準備與版本說明在實際操作項目之前需要先準備本地的運行環(huán)境。這個項目主要依賴 Git、Node.js 以及一個支持 skill 機制的 AI Agent 客戶端比如 Claude Code、Cursor 或結(jié)合 OpenClaude 這類工具。這里的版本信息需要特別說明項目迭代較快AI 工具鏈的兼容性變化也比較頻繁所以不要追求固定版本。以我當前使用的環(huán)境為例操作系統(tǒng)macOS 15.x / Ubuntu 22.04 / Windows 11 均可 Git2.30 以上 Node.js18 或 20 LTS 版本 AI Agent 客戶端Claude Code 或兼容 skill 機制的客戶端在開始前請確認 Git 已經(jīng)正常配置git --version node -v如果系統(tǒng)里還沒有安裝相關(guān)工具建議先完成安裝再繼續(xù)。項目倉庫本身并不復雜核心是理解它目錄組織方式而不是必須運行復雜的構(gòu)建流程。3. 項目結(jié)構(gòu)拆解一個生產(chǎn)級 skill 長什么樣3.1 項目整體目錄劃分從 GitHub 倉庫的根目錄看這個項目遵循了非常清晰的“分類 獨立模塊”組織方式。目錄結(jié)構(gòu)大致如下agent-skills/ ├── README.md ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── checks/ │ ├──>--- name: code-review description: Perform a systematic code review for pull requests version: 1.0.0 --- ## Objective Review the given diff and provide actionable feedback. ## Steps 1. Read the diff carefully. 2. Check for security issues, performance problems, and correctness. 3. Validate against the teams coding standards. 4. Write feedback with severity levels. ## Constraints - Do NOT modify the source code directly. - If the diff contains credentials, stop and report immediately. ## Output Format \\\markdown ## Review Summary - Overall: PASS / NEEDS_CHANGES ## Issues - [HIGH] description - [MEDIUM] description ## Suggestions - suggestion \\\這種結(jié)構(gòu)看起來簡單但實際落地時效果特別明顯。它把標準、流程、輸出都固定下來了即使不同的人來用AI 產(chǎn)出的結(jié)果風格也高度一致。3.3 為什么這套結(jié)構(gòu)能稱為“生產(chǎn)級”生產(chǎn)級并不是說代碼寫得多么高深而是指它考慮了真實業(yè)務(wù)環(huán)境中會遇到的問題。第一容錯性。Skill 里明確寫了“如果 diff 中包含憑據(jù)立即停止并上報”這就是把 P0 級事故擋在發(fā)生之前。第二可測試性。項目里為每個 skill 都附帶了校驗腳本或檢查清單Agent 執(zhí)行完會自動對照檢查減少“看起來不錯但實際不能用”的尷尬。第三可維護性。因為 skill 的輸入、輸出、步驟都是結(jié)構(gòu)化定義的后續(xù)更新只需要改對應模塊而不需要大規(guī)模重寫提示詞。第四知識沉淀。每個 skill 可以附帶多個 examples這些 examples 實際上是團隊業(yè)務(wù)經(jīng)驗的編碼化表達。老工程師的審查思路、運維專家的排查順序都可以這樣傳承。4. 實戰(zhàn)篇用 skill 機制構(gòu)建一個代碼審查助手4.1 場景設(shè)定假設(shè)你所在的團隊每周有大量 Pull Request 需要人工審查審查質(zhì)量參差不齊。我們希望基于 Addy Osmani 項目的 skill 思路在本地搭建一個“代碼審查助手”讓 Agent 能自動完成大部分機械性審查工作同時把風險控制在一定范圍內(nèi)。這不是一個完整的商業(yè)系統(tǒng)而是一個伸手就能跑通的本地原型。如果你只需要審查單個文件甚至可以把完整流程壓縮為幾步。4.2 創(chuàng)建項目結(jié)構(gòu)我們先在本地創(chuàng)建一個項目目錄mkdir my-agent-skills cd my-agent-skills mkdir -p skills/code-review/examples接著在skills/code-review目錄下創(chuàng)建SKILL.md內(nèi)容可以直接復用第 3 節(jié)給出的模板也可以按團隊風格做調(diào)整。這里我提供一個稍完整的版本--- name: code-review description: Review a JavaScript or Python code diff for common issues version: 1.0.0 --- ## Context This skill helps an AI agent review code diffs for quality, security, and performance issues. ## Workflow 1. Identify the programming language from the diff. 2. Check for the following categories: - Security risks - Potential runtime errors - Code style violations - Performance bottlenecks 3. Classify each issue by severity: HIGH, MEDIUM, LOW. 4. Return a concise report. ## Rules - Always quote the exact code snippet when reporting an issue. - Propose a concrete fix for each HIGH issue. - If the diff contains API keys or passwords, mark it as BLOCKER. - Do not rewrite the whole file, only highlight issues. ## Output Format Report in the following structure: ### Summary {APPROVE | REQUEST_CHANGES} ### Findings | Severity | Location | Issue | Suggestion | | --- | --- | --- | --- | | HIGH | line 12 | SQL injection risk | Use parameterized queries |4.3 編寫一個簡單的 skill 加載器接下來寫一個小工具讓 Agent 在啟動時能加載這個 skill 內(nèi)容。這里用 Node.js 實現(xiàn)一個最小加載器便于在本地驗證機制// 文件路徑tools/skill-loader.js const fs require(fs); const path require(path); /** * 從 skills 目錄加載一個 skill 的 SKILL.md * param {string} skillName - 技能名稱 * returns {string} skill 文件內(nèi)容 */ function loadSkill(skillName) { const skillPath path.join(__dirname, ../skills, skillName, SKILL.md); try { return fs.readFileSync(skillPath, utf-8); } catch (err) { console.error([skill-loader] Failed to load skill: ${skillName}); process.exit(1); } } const skillName process.argv[2]; if (!skillName) { console.error(Usage: node skill-loader.js skill-name); process.exit(1); } const content loadSkill(skillName); console.log( Loaded skill ); console.log(content);運行方式node tools/skill-loader.js code-review如果一切正常你會在控制臺看到完整的SKILL.md內(nèi)容。這個加載器雖然簡陋但它體現(xiàn)了 skill 機制的核心——把能力包以文件形式組織按需加載。4.4 模擬 Agent 調(diào)用 skill 的流程真實場景中Agent 會通過客戶端工具讀取SKILL.md然后結(jié)合 diff 內(nèi)容執(zhí)行審查。這里我們用一個模擬腳本演示完整流程// 文件路徑scripts/run-code-review.js const fs require(fs); const skillLoader require(../tools/skill-loader); const fakeDiff const db require(db); const userId req.query.userId; const sql SELECT * FROM users WHERE id userId; db.query(sql, (err, result) { res.send(result); }); ; function reviewWithSkill(skillContent, diff) { // 真實場景中這里會調(diào)用 LLM API // 這里僅模擬結(jié)果 console.log(--- Reviewing diff with skill ---); console.log(skillContent.split(\n)[0]); console.log(--- Diff content ---); console.log(diff); const hasPotentialInjection diff.includes(req.query) diff.includes( userId); if (hasPotentialInjection) { console.log(Result: REQUEST_CHANGES); console.log(Issue: Potential SQL injection detected, use parameterized queries.); } else { console.log(Result: APPROVE); } } const skillContent skillLoader.loadSkill(code-review); reviewWithSkill(skillContent, fakeDiff);運行node scripts/run-code-review.js這里并不真正調(diào)用 LLM而是把 diff 傳入后模擬規(guī)則判斷。實際落地時你可以將SKILL.md內(nèi)容拼接到用戶提示詞前面或者通過支持工具調(diào)用的 Agent 框架直接加載。4.5 接入真實 AI Agent如果要接入 Claude Code 這類工具思路是類似的。你可以把 skill 文件路徑配置到 Agent 的上下文目錄然后在對話開始時先輸入請加載 skills/code-review 下的 SKILL.md然后按該 skill 的要求審查以下代碼 diffAgent 會讀取規(guī)則再按規(guī)則輸出。如果 Agent 客戶端支持 skill 插件機制也可以直接把 skill 注冊為可調(diào)用工具。這樣后續(xù)每次審查都能保持同一種格式和檢查標準。這也回答了很多人關(guān)心的一個問題skill 并不是某個特定平臺的專屬功能而是一種通用的結(jié)構(gòu)化思想只要你能讓 Agent 穩(wěn)定讀取并遵守規(guī)則任何客戶端都可以落地。5. 進階實戰(zhàn)從零編寫你自己的生產(chǎn)級 skill5.1 確定 skill 邊界動手寫 skill 之前最重要的一步是劃定邊界。建議一個 skill 只負責一個完整子任務(wù)。比如“代碼審查”是一個 skill“數(shù)據(jù)庫遷移腳本生成”是另一個不要把兩件事混在一起。邊界清晰的 skill 有這些好處容易測試單獨驗證成功率。容易定位問題失敗時能快速知道是哪個環(huán)節(jié)出了問題。方便團隊協(xié)作不同人負責不同 skill。5.2 編寫模板與示例創(chuàng)建templates/basic-skill/SKILL.md作為團隊模板這能讓后續(xù)新增 skill 保持一致質(zhì)量。模板可以這樣寫--- name: {skill-name} description: {short description of what this skill does} version: 0.1.0 --- ## Objective {Describe the exact goal of this skill.} ## When To Use {Define the trigger conditions.} ## Workflow 1. {Step one} 2. {Step two} 3. {Step three} ## Input Requirements {What information is required from the user or environment.} ## Output Requirements {Define the exact output format.} ## Failure Handling {What to do if the task cannot be completed.} ## Examples - {Example 1} - {Example 2}每次創(chuàng)建新 skill 時直接復制模板再填寫內(nèi)容比從零開始快很多也更容易讓團隊養(yǎng)成統(tǒng)一習慣。5.3 高質(zhì)量 skill 的檢查清單寫完 skill 后可以用下面的檢查清單自查檢查項說明目標是否單一一個 skill 只解決一類問題步驟是否可執(zhí)行Agent 按步驟走不會產(chǎn)生歧義是否包含失敗處理出現(xiàn)異常情況時有兜底邏輯輸出格式是否明確結(jié)果能被后續(xù)流程穩(wěn)定解析是否有示例至少一個正例和一個反例是否包含安全邊界遇到敏感信息時如何反應如果以上都滿足這個 skill 才算具備了“生產(chǎn)級”的底子可以投入到真實項目中使用。5.4 從 skill 到業(yè)務(wù)閉環(huán)單一 skill 只是第一步。生產(chǎn)環(huán)境往往需要一個“skill 集合”覆蓋需求分析、編碼、審查、測試、部署運維等環(huán)節(jié)。把這些 skill 組合起來配合 Agent 編排流程才真正形成了企業(yè)級 AI 智能體。從這個角度看Addy Osmani 的項目給我們提供的不只是一些現(xiàn)成 skill更是一套值得長期復用的組織方法論。6. 常見問題與排查思路在實踐過程中我整理了一些出現(xiàn)頻率較高的問題和對應的解決方案。這里按“現(xiàn)象—原因—解決思路”列出方便你快速排查。問題現(xiàn)象常見原因解決思路從 GitHub 拉取倉庫時速度很慢或超時倉庫體積大、網(wǎng)絡(luò)波動使用鏡像入口比如git clone https://gitclone.com/github.com/xxx/xxx或先下載壓縮包再解壓Skill 內(nèi)容加載后格式混亂Markdown 編碼或換行符問題統(tǒng)一使用 UTF-8 編碼并確保文件以 LF 換行符保存Agent 讀了 SKILL.md 后仍然不按規(guī)則執(zhí)行Prompt 中沒有明確要求“必須嚴格遵守”在用戶指令里顯式指出“請按 SKILL.md 的規(guī)則執(zhí)行不要跳過約束”相同 diff 每次審查結(jié)果不一致沒有固定輸出規(guī)范或溫度參數(shù)過高在 skill 中強化輸出模板并在 Agent 配置中降低溫度Skill 文件多后難以維護缺少模塊化管理按第 3 節(jié)的目錄結(jié)構(gòu)組織每個 skill 獨立目錄、獨立版本這里特別說一下 GitHub 訪問問題。很多開發(fā)者會遇到倉庫無法克隆或者下載慢的情況。穩(wěn)妥的做法是設(shè)置 Git 代理如果本機有可用 HTTP 代理。使用國內(nèi)鏡像站例如把github.com替換為gitclone.com或hub.fastgit.xyz這類鏡像的可用性會隨時間變化。直接在瀏覽器下載 zip 包再上傳到服務(wù)器避免命令行克隆超時。不要輕信來路不明的“加速工具”更不要在辦公環(huán)境嘗試繞過網(wǎng)絡(luò)安全策略。安全合規(guī)永遠是第一位的。7. 最佳實踐與工程建議7.1 從業(yè)務(wù)場景反推 skill 設(shè)計很多團隊在引入 agent skill 時會踩一個坑先去大而全地整理一堆 prompt卻發(fā)現(xiàn)業(yè)務(wù)方根本用不上。正確的做法是反推場景。列出當前業(yè)務(wù)里最痛、最重復、最需要標準化的環(huán)節(jié)優(yōu)先為這些環(huán)節(jié)做 skill。比如新需求評審讓 Agent 按固定模板生成需求遺漏點清單。代碼審查讓 Agent 執(zhí)行規(guī)范檢查、安全掃描、性能提醒。故障排查讓 Agent 按時間線收集日志、定位異常、輸出根因假設(shè)。數(shù)據(jù)報表生成讓 Agent 從數(shù)據(jù)庫查詢固定口徑的數(shù)據(jù)并生成報表說明。抓準場景后再考慮這個 skill 的結(jié)構(gòu)、輸入輸出、校驗方式。這樣既能快速見效也能在團隊內(nèi)積累信任。7.2 給 Skill 加上版本管理和灰度策略生產(chǎn)級 skill 不該是“寫一版用一年”的靜態(tài)文件。AI 大模型能力在升級、業(yè)務(wù)規(guī)則在變化skill 也需要持續(xù)迭代。建議把 skill 納入 Git 管理用版本號標記每次變更。大型改動可以先在測試環(huán)境里跑一段時間確認效果后再全量推廣。如果 Agent 平臺支持“同時掛載新版舊版”做對比也可以采用灰度策略讓一部分請求走新版另一部分走舊版用數(shù)據(jù)判斷是否回滾。7.3 安全邊界與敏感數(shù)據(jù)處理涉及企業(yè)生產(chǎn)環(huán)境的 skill必須把安全放在首位。這里有幾點建議skill 中明確禁止輸出真實密碼、Token、密鑰等敏感字段。如果任務(wù)需要讀取數(shù)據(jù)庫務(wù)必強調(diào)只允許 SELECT且限制查詢條件。涉及刪除、更新操作時skill 必須要求先備份并提示風險。對“無法確認的數(shù)據(jù)”要求 Agent 停止操作并請求人工確認。這些規(guī)則不能只停留在文檔里而要寫進SKILL.md的 Constraints 部分并且通過示例告訴 Agent 遇到什么情況必須剎車。7.4 構(gòu)建團隊級 skill 知識庫當 skill 數(shù)量多起來之后可以考慮建設(shè)團隊級知識庫。做這件事有幾個關(guān)鍵點統(tǒng)一命名規(guī)范比如{領(lǐng)域}-{場景}-{技能名}。統(tǒng)一文檔結(jié)構(gòu)每個 skill 遵循同一個模板。建立 review 機制新 skill 需要經(jīng)過至少一人復核。統(tǒng)計使用數(shù)據(jù)定期關(guān)注成功率、失敗原因、修改次數(shù)。這套機制本身并不復雜但堅持下來后團隊的 AI 應用水平會明顯區(qū)別于那種“每個人自己寫 prompt”的粗放階段。8. 總結(jié)與下一步學習方向Addy Osmani 這個 7.9 萬 Star 的項目本質(zhì)上是在推動一件事把 AI Agent 從“好玩”推向“可用”從“偶爾正確”推向“穩(wěn)定交付”。它沒有依賴復雜平臺而是選擇了一種極輕量的文件結(jié)構(gòu)——這恰恰是最容易復制到任何團隊的方式。對于開發(fā)者而言現(xiàn)在最值得做的第一步是動手創(chuàng)建屬于你自己的第一個 skill。可以先從最簡單的場景入手比如把團隊的代碼審查標準整理成一個SKILL.md放進倉庫然后讓 Agent 在下一個 PR 審查中試跑。跑通之后再逐步擴展。后續(xù)可以繼續(xù)關(guān)注的方向包括skill 的自動評估與回歸測試、多 skill 組合編排、RAG 與 skill 的結(jié)合、以及大模型能力升級后 skill 的兼容性管理。這些方向中我建議優(yōu)先研究“自動評估”和“組合編排”因為二者直接決定生產(chǎn)環(huán)境里 Agent 的上限。AI Agent 的時代才剛剛開始基于 skill 的工程化方法會是這一波浪潮里非常核心的技能?，F(xiàn)在就打開 GitHub拉取這個項目選擇一個你最有感的 skill 開始實踐吧。相信我跑通一個真正能用的 skill 之后回不去的。