最近在技術社區里一個話題開始被頻繁提起“聽說一些公司開始做員工skills了”。如果你關注過 Claude Code、Codex、Cursor、OpenCode 這些 AI 編程工具大概率已經見過skills這個英文詞。它并非某一家公司的專屬概念而是正在成為 AI Agent 時代的一種新“知識封裝單元”。但聽到“員工skills”很多人第一反應是這不就是給 AI 寫提示詞嗎公司搞這個和以前沉淀文檔、做 Wiki、搞專家庫有什么區別這篇文章想聊清楚幾件事員工skills到底是什么為什么它和提示詞、Agent、Tools 這些概念有本質差異以及一家公司如果要落地“員工skills”應該從哪個環節開始、有哪些坑、需要什么樣的工程規范。文章會給出一個完整的示例從目錄結構、編寫規范到實際安裝和驗證盡量讓技術讀者看完后不僅理解概念還能在自己的項目里跑通一個最小閉環。1. 這篇文章真正要解決的問題先從一個具體的場景切入。假設你是一家公司的前端負責人團隊 20 個人每天要用 AI 輔助做代碼審查。你發現不同的開發問 AI 的方式完全不一樣有的人會貼上一大段代碼讓 AI“幫我看看有沒有問題”有的人會要求“找出性能隱患和可訪問性問題”還有的人希望 AI 按照團隊自己的 ESLint 規則給出修改建議。結果就是AI 的回答質量參差不齊。團隊成員每次都要寫不同的提示詞有人寫得好有人寫得差。更麻煩的是團隊積累的那些審查經驗比如“圖片必須加懶加載”“按鈕交互必須有 loading 態”“移動端禁止橫向滾動”全部散落在各種文檔和每個人的腦海里AI 根本不知道。這時候如果做一套“前端代碼審查 skills”把這些規則、檢查項、示例代碼全部封裝成一個可復用的技能包團隊成員只要讓 AI 加載這個 skillAI 就能按照團隊一致的規范去審查代碼。這就是“員工skills”要解決的問題把人和團隊的經驗轉化為 AI 可復用的能力模塊而不是靠每個人反復輸入零散的提示詞。所以這篇文章值得一讀的人群包括正在使用 Claude Code、Codex、Cursor、OpenCode 等 AI 編程工具的開發者。團隊里負責 AI 工程化、負責沉淀開發規范的架構師和技術負責人。對 Agent、Skill、Tool 這些概念有困惑想搞清楚它們之間邊界的人。讀完這篇文章你會明白員工skills不是“給 AI 寫幾句提示詞”那么簡單而是一套有結構、有目錄規范、有可執行腳本、有驗證方式的工程化產物。2. Skills 的基礎概念它到底是哪一層的東西要理解員工skills首先得把“skills”和它周圍的幾個概念分清楚。2.1 Skills 是什么從材料信息看當前 AI 工具鏈中影響最廣的 skills 規范之一是 Anthropic 推行的 Agent Skills 格式。這個格式的基本單元是一個目錄目錄里包含一個SKILL.md文件用來描述這個技能的功能、使用場景、工作流程目錄里還可以放各種輔助腳本、模板、參考文檔它們會被 AI 在執行任務時動態加載。一個典型的 skills 目錄結構看起來是這樣的code-review-skill/ ├── SKILL.md └── scripts/ ├── check-eslint.md └── review-frontend.py這里面的關鍵設計是SKILL.md 不是給人類閱讀的而是給 AI 讀取的指令手冊。當 AI 遇到與這個 skill 相關的任務時它會自動讀取 SKILL.md按照里面的規則和流程去執行。這樣一來人類團隊的規范就變成了 AI 的工作指南。2.2 Skills 和提示詞Prompt的區別很多人覺得 skills 就是高級提示詞這種理解對了一半。提示詞是一次性的自然語言指令。它存在于對話上下文里用完就沒了。即使你把自己的提示詞寫得天花亂墜換個會話AI 又忘得一干二凈。Skills 是持久化的能力封裝。它不只是“一段文字指令”還包括執行邏輯、參考資料、腳本工具以及觸發條件。更重要的是skills 是放在項目目錄里的文件可以被版本管理可以被團隊分享可以被 AI 動態發現和加載。打個比方提示詞像你在餐廳臨時告訴廚師“這道菜少放鹽、多放辣、不要香菜”skills 像廚師手里那本標準化菜譜里面規定了每一步的做法、用哪種醬油、什么時候下鍋。2.3 Skills 和 Tools、Agents 的區別這里有一個非常容易混淆的點。Tools 是 AI 可以調用的外部功能。比如“搜索網頁”“讀文件”“執行代碼”“調用某個 API”。它們解決的是“AI 能對外部世界做什么”的問題。在 Claude Code 里Tools 是內置的你可以讓 AI 讀文件、寫文件、執行 Bash 命令。Skills 解決的是“AI 如何按照特定方式做一件事”的問題。它更像一套操作規范告訴你什么時候調用工具、調用哪些工具、按照什么順序、遵循什么標準。同一個 Tool用不同的 Skills 去編排產出的結果會完全不同。Agents 則是更大的概念。Agent 是一個能自主規劃、調用工具、執行任務的系統。Skills 可以理解為 Agent 身上的技能包。一個粗略的層級關系是概念解決的問題形態提示詞告訴 AI 做什么一段文本Tools讓 AI 能操作外部世界函數/API/命令Skills讓 AI 按特定標準完成一類任務規則文檔腳本參考資料Agents自主分析、決策、執行復雜任務一個智能體程序這樣看下來員工skills的真正價值就清晰了它不是給某個具體任務寫一次性提示詞而是把一類可重復的任務固化成 AI 能穩定執行的能力標準。2.4 Skills 和 MCP 的關系還有一個容易混淆的概念是 MCPModel Context Protocol。MCP 解決的是“如何把外部數據源和工具接入 AI”的傳輸協議問題。Skills 和 MCP 不是競爭關系而是不同層次的東西。Skills 可以觸發 AI 去調用 MCP 服務器提供的工具也可以直接使用腳本完成工作。它們是互補的。在實際項目中一個清晰的判斷是如果你只是給 AI 提供“按團隊規范審查代碼”“按固定格式生成會議紀要”這類標準化能力skills 是更輕量、更直接的選擇如果你需要接入公司內部的數據源、API、數據庫MCP 可能更合適。兩者可以同時存在。3. 為什么公司開始把“員工skills”當成一件事來做聊完概念回到文章標題為什么一些公司開始做員工skills了核心驅動因素是AI 工具的普及讓“個人能力”和“組織能力”之間的差距被放大了。過去一個資深工程師的經驗通過代碼評審、技術分享、文檔沉淀來傳遞。這個過程很慢而且損耗很大。新員工要看很久文檔、問很多人才能達到“像老員工一樣做事”的水平。但在 AI 編程工具普及之后團隊里的每一個開發都在和 AI 協作。AI 的輸出質量取決于:你給了它什么上下文它知不知道你的團隊規范有沒有按照你的工程標準去執行。這時候團隊遇到一個尷尬的問題AI 對公共知識很精通但對公司內部的知識一無所知。它不知道你們的命名規范、不知道你們的發布流程、不知道你們常見的線上事故、不知道你們約定俗成的代碼結構。員工skills就是用來解決這個“內部知識斷裂”問題的。公司做員工skills本質上是在做一件事把團隊內部的私域知識轉化為 AI 可以理解、加載、執行的結構化能力包。舉個例子一家公司可能在內部做一套“Java 后端開發 skills”里面包含團隊的項目分層規范Controller / Service / Repository 怎么劃分。接口返回值格式統一 Result 包裝、錯誤碼規范。數據庫操作規范必須走 MyBatis 分頁、禁止在循環里查庫。日志規范INFO 記錄入參出參、WARN 記錄重試、ERROR 記錄異常堆棧。測試要求關鍵業務必須有單元測試覆蓋率不低于多少。一旦這套 skills 建好團隊的 AI 編程工具就能輸出符合公司風格的代碼而不是泛泛的“標準答案”。更進一步公司還可以做“前端代碼審查 skills”“數據庫變更評審 skills”“生產環境故障排查 skills”“技術方案編寫 skills”。每一個 skills 都是對一類高頻重復工作的標準化封裝。4. 員工skills的落地從個人技能到組織能力理解了概念和動機之后下一步要解決的是員工skills到底怎么在公司落地4.1 個人技能的沉淀路徑從一個開發者的視角來看最自然的切入點是我把平時寫的最好的提示詞、最常用的檢查項、最頻繁的回歸流程設計成一個可復用的技能包。這個階段不涉及復雜的組織設計只要個人愿意花一點時間整理即可。典型的做法是第一步找出重復次數最多的任務。比如“幫我用 Vue3 寫一個表格組件”“幫我檢查這個頁面的響應式布局問題”——這是每周都會出現的高頻請求。第二步把這個任務的完成標準拆成步驟和檢查項。比如寫表格組件時必須支持分頁、loading、空狀態、列寬拖動并且使用團隊的BaseTable基類。第三步把這些步驟寫成 SKILL.md放到項目目錄里測試一下 AI 是否真的能按標準執行。4.2 從個人技能到團隊技能個人 skills 的局限在于它只在一個人的項目里有效。要變成團隊能力至少要解決三個問題。第一個問題是存放位置。團隊的 skills 不能散落在每個人的電腦里而是應該放在統一的代碼倉庫中比如team-skills/所有團隊成員共享。第二個問題是命名與分類。如果不對 skills 做統一管理過一段時間就會產生大量功能重疊、命名混亂的技能包。比如“前端審查”“code-review”“vue-check”可能做的是同一件事。第三個問題是更新維護。團隊規范會變skills 也必須跟著變。如果沒人負責維護skills 就會慢慢變成廢棄文檔。一個有實踐價值的做法是由技術負責人或架構師牽頭把團隊里已經驗證有效的個人 skills 收斂到統一倉庫并指定對應的 owner。每個 skill 都要有版本說明和更新日志就像代碼庫一樣管理。4.3 企業級 skills 的工程化如果公司的目標是把 skills 做成真正的組織能力那就需要對 skills 做工程化治理。至少包括規范層定義 skills 目錄結構、文案語言、觸發條件、質量標準。倉庫層建立 skills 的統一代碼倉庫支持版本管理、變更評審、發布。測試層為每個 skill 設計驗證用例確保 AI 加載后能穩定輸出預期結果。運營層統計哪些 skills 被高頻使用、哪些沒人用、哪些效果不好及時淘汰和更新。這四個層次聽起來復雜但實際落地時可以從最小集開始先做一個統一倉庫再定一個簡單的目錄規范最后把團隊的 top-3 高頻任務各封裝成一個 skill。5. 核心流程拆解如何寫一個員工skills上面講了很多理念這一節進入實操層面。我們以“前端代碼審查 skills”為例完整拆解一個員工skills的創建流程。5.1 定義 skill 的目標與邊界寫一個 skill 之前首先要回答三個問題這個 skill 是什么負責哪一類任務這個 skill 不是什么它不處理哪些任務邊界是什么執行這個 skill 后AI 應該交付什么結果以“前端代碼審查”為例它負責審查前端代碼中的性能問題、可訪問性問題、響應式布局問題、規范不符合問題。它不負責不審查后端邏輯、不審查數據庫設計、不替代人工走查視覺細節。交付結果一份按嚴重程度分級的審查報告包含問題描述、示例代碼、修改建議、對應文件路徑。這一步很關鍵。如果邊界不清楚AI 會什么都往這個 skill 里塞。5.2 搭建目錄結構根據 Agent Skills 的通用結構建議先建一個目錄frontend-code-review/ ├── SKILL.md ├── scripts/ │ └── list-files.py └── references/ └── team-frontend-rules.mdSKILL.md是主入口用于告訴 AI 這個技能是干什么的、什么時候啟用、怎么執行。scripts/用于放可執行的輔助腳本。references/用于放團隊規范、代碼示例、參考文檔。5.3 編寫 SKILL.mdSKILL.md的編寫質量直接決定整個 skill 好不好用。下面是一份示例你可以根據團隊實際情況修改。--- name: frontend-code-review description: 按團隊前端規范審查代碼檢查性能、可訪問性、響應式與規范問題輸出分級審查報告。 --- # 前端代碼審查 ## 適用場景 當用戶要求“審查這段前端代碼”“幫我做 code review”“檢查這個組件是否有性能問題”時使用本技能。 ## 不適用場景 - 用戶要求審查后端接口、數據庫邏輯、基礎設施配置。 - 用戶只要求解釋代碼含義不做質量評估。 ## 執行步驟 1. 先確認審查范圍是單個文件還是改動文件列表。 2. 讀取涉及的代碼文件定位組件類型與核心邏輯。 3. 按“性能與渲染”“可訪問性”“響應式與移動端”“代碼規范”四個維度逐項檢查。 4. 參考 references/team-frontend-rules.md 中的團隊規范確認是否存在不一致。 5. 輸出分級審查報告。 ## 審查重點 ### 性能與渲染 - 列表是否使用 key且 key 是否為穩定唯一值。 - 是否存在不必要的 setState 導致重復渲染。 - 圖片是否開啟懶加載。 - 大數據量場景是否使用了虛擬滾動。 ### 可訪問性 - 交互元素是否包含合適的 aria-label。 - 圖片是否提供 alt 文本。 - 是否可以在無鼠標狀態下完成核心操作。 ### 響應式與移動端 - 是否出現固定寬高導致的橫向滾動。 - 是否使用 rem、vw/vh 或響應式斷點。 - 移動端點擊區域是否過小。 ### 代碼規范 - 是否存在違反團隊命名規范的標識符。 - 是否有 console.log 殘留。 - 是否有未使用的 import 或變量。 ## 輸出格式 按以下結構輸出審查報告 1. 審查范圍 2. 嚴重問題必須修復說明原因與修復方式 3. 建議改進值得優化給出具體方案 4. 符合規范的部分簡短說明幫助開發者理解哪些寫得好 5. 修改示例對問題最嚴重的一處給出優化前后的代碼對比這份文檔看起來很樸素但它實際是把團隊經驗結構化成了 AI 可執行的步驟。每個審查重點都是一條規則AI 在審查時會逐條對照。5.3.1 SKILL.md 編寫的六個要點如果沒有寫過 skill第一次寫時很容易踩坑。下面是六個實戰中驗證過的要點。第一個要點觸發條件要明確。SKILL.md 里的“適用場景”要寫得具體否則 AI 可能在不該啟用時亂用或者該用時不用。第二個要點步驟要可執行不要寫太抽象。比如“檢查代碼質量”太模糊“檢查是否存在不必要的 setState 導致重復渲染”就很具體。第三個要點規則要有示例。特別是團隊自定義的規范最好附上“正確寫法”和“錯誤寫法”的代碼片段。第四個要點輸出格式必須定義。如果不定義輸出格式AI 每次給的報告格式都不一樣后期很難統計和消費。第五個要點注意 token 消耗。SKILL.md 會被 AI 加載進上下文太冗長會浪費上下文窗口。所以能用列表表達的就不要寫長篇論述。第六個要點定期版本化。SKILL.md 一旦穩定就給它打一個版本號。后續團隊規范變化時可以對比差異并更新。5.4 創建輔助腳本不是所有的 skill 都需要腳本但如果技能涉及文件掃描、數據統計、格式校驗腳本可以讓 AI 的執行更穩定。以下是一個簡單的 Python 腳本用于從項目中提取待審查的前端文件列表#!/usr/bin/env python3 # 文件路徑frontend-code-review/scripts/list-files.py # 功能掃描項目中的前端源碼文件列出待審查文件。 import os import sys EXCLUDE_DIRS {node_modules, dist, build, .git, .next} FRONT_END_EXTS {.vue, .tsx, .jsx, .ts, .js, .css, .scss, .less} def main(): root sys.argv[1] if len(sys.argv) 1 else . files [] for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in EXCLUDE_DIRS] for f in filenames: if os.path.splitext(f)[1] in FRONT_END_EXTS: files.append(os.path.join(dirpath, f)) files.sort() for file in files: print(file) if __name__ __main__: main()這個腳本本身沒什么難度但它在 skill 中的價值是讓 AI 不依賴自己猜測文件路徑直接拿到準確的文件清單。引用方式很簡單在 SKILL.md 的執行步驟中寫明如果需要審查整個項目中的前端文件先運行以下命令獲取文件清單 bash python3 scripts/list-files.py .然后對清單中的文件進行逐項審查。### 5.5 加入團隊規范文檔 references/team-frontend-rules.md 是團隊知識的集中體現。這一部分無需從零編寫可以直接把團隊已有的前端規范、代碼評審 checklist、常見問題列表整理進去。 markdown # 團隊前端規范摘要 ## 命名規范 - 組件文件名PascalCase如 UserProfile.vue - 普通工具函數camelCase如 formatDateTime.ts - CSS 類名BEM 風格如 block__element--modifier ## 組件規范 - 通用表格必須使用 BaseTable 組件 - 表單必須支持 Enter 鍵提交 - 圖片必須指定寬高避免布局偏移 ## 禁止項 - 禁止在 render 函數中直接 new Date()除非有明確更新需求 - 禁止在循環中使用 await 發起串行請求 - 禁止在組件卸載后更新狀態 ## 常見性能問題 - 大列表未開啟虛擬滾動 - 父子組件未使用 memo / computed 導致無效渲染 - 動態 import 未做 Suspense 邊界處理建議一開始不要追求大而全先聚焦團隊最容易出問題的 5 到 10 條規則后續再逐步擴充。6. 完整示例構建一個“員工skills”并安裝到 AI 編程工具為了讓文章更落地這里給出一個從零到一的最小完整示例。我們會創建一個小型的“新員工入職指引 skills”目標是讓 AI 能夠根據它回答新員工關于公司開發環境、代碼倉庫、提交流程的問題。6.1 創建目錄與文件第一步建立目錄結構mkdir -p team-onboarding-skill/scripts cd team-onboarding-skill第二步創建SKILL.md--- name: team-onboarding description: 回答新員工入職相關問題包括開發環境搭建、代碼倉庫地址、分支規范、提交流程、常見命令。 --- # 新員工入職指引 ## 適用場景 當用戶詢問以下問題時啟用本技能 - “公司代碼倉庫在哪里” - “如何配置開發環境” - “提交代碼的流程是什么” - “有哪些開發規范需要遵守” ## 執行步驟 1. 先判斷用戶所在小組和項目類型。 2. 根據問題類型查閱 references 目錄中的對應文檔。 3. 如果文檔中缺少信息明確告知用戶“該信息未在團隊知識庫中收錄請咨詢對應項目負責人”不要編造。 4. 回答時盡量給出可復制的命令或操作步驟。 ## 回答要求 - 所有命令必須給出完整命令并注明在哪個目錄下執行。 - 涉及敏感信息密碼、Token時提示用戶走公司內部安全通道獲取禁止出現在回答中。 - 如果問題涉及賬號權限引導用戶走權限申請流程不要嘗試繞過權限系統。第三步創建references/development-setup.md放開發環境配置信息# 開發環境搭建 ## 前端項目 依賴節點版本 20使用 pnpm 作為包管理器。 bash nvm use 20 pnpm install pnpm dev后端項目依賴 JDK 21使用 Maven 構建。mvn clean install mvn spring-boot:run環境變量本地開發需要配置以下環境變量API_BASE_URL本地 API 地址APP_ENV設為devLOG_LEVEL設為debug第四步創建 references/git-workflow.md markdown # Git 提交流程 ## 分支命名 - 功能分支feature/xxx - 修復分支fix/xxx - 發布分支release/xxx ## 提交信息 提交信息必須包含 Jira 單號例如 text [PROJ-123] 完成用戶列表功能合并規范功能開發完成后通過 Merge Request 合并到 develop 分支至少 1 人審批。### 6.2 把 skill 安裝到 Claude Code 目前各類 AI 編程工具對 skills 的支持方式大同小異把 skill 目錄放在一個約定的位置AI 就能發現并加載它。 在 Claude Code 中社區的常見做法是將 skills 放在項目根目錄的 .claude/skills/ 下或者用戶級目錄的 ~/.claude/skills/ 下。以剛才創建的 onboarding skill 為例 bash # 假設你的項目在 ~/work/my-project mkdir -p ~/work/my-project/.claude/skills cp -r team-onboarding-skill ~/work/my-project/.claude/skills/安裝完成后你在 Claude Code 對話中輸入“如何開發環境搭起來”或者“我們項目的分支規范是什么”AI 就有機會加載這個 skill按照里面的規則回答。6.3 把 skill 安裝到 Codex在 OpenAI Codex 中社區實踐是使用AGENTS.md配合 skills 目錄的方式。你可以把 skill 放到項目倉庫的skills/目錄下并在說明文檔中引用。更通用的做法是不管工具怎么變化你只需要保證兩點——第一skill 目錄存在于項目倉庫中第二目錄里有一個 AI 能讀取到的主文件SKILL.md 或類似命名。下面是在 Codex CLI 項目中使用 skill 的示意mkdir -p ~/work/my-project/skills cp -r team-onboarding-skill ~/work/my-project/skills/然后在項目根目錄的AGENTS.md中增加一行團隊技能包位于 skills/ 目錄遇到與對應技能相關的問題時請先讀取相關 SKILL.md。6.4 安裝到 Cursor 和 OpenCodeCursor 類 IDE 中skills 的加載通常有兩種實現方式一種是借助.cursor/rules或項目配置文件把技能內容注入上下文另一種是把 skill 作為項目文件由 AI 通過文件讀取能力加載。如果你使用的是 OpenCode社區的做法是把 skill 放在項目內統一的目錄然后通過配置讓 AI 知道這個目錄的存在。以 OpenCode 為例可以在項目的配置說明中寫清楚# OpenCode 項目配置 skills 目錄./skills 規則遇到與本項目技能包相關的任務時必須先查看對應目錄下的 SKILL.md 再回答。這種“配置聲明 文檔說明”的方式雖然不是某個工具的官方標準格式但在目前 skills 生態尚未完全統一的情況下是兼容性最高、最容易上手的做法。7. 運行結果與效果驗證寫完 skill 并安裝到工具之后不能直接宣布完成。你需要驗證兩件事第一AI 能不能正確發現和加載這個 skill第二AI 執行 skill 的結果是否符合預期。7.1 驗證 AI 是否正確加載了 skill最簡單的方法是用一個觸發問題去測試。比如你剛安裝了 onboarding skill在會話中提問請先查看團隊技能包中是否有新員工入職相關的技能如果有請按照其規則回答我的前端項目如何啟動如果 AI 加載成功它的回答應該包含SKILL.md中定義的步驟和 references 中提到的具體命令而不是給出一段泛泛的答非所問。還可以在提問中直接要求請告訴我你在處理這個問題時使用了哪個技能包它的主要規則是什么通過這種元問題你可以確認 AI 是否真的讀取了你的 SKILL.md。7.2 判斷輸出質量驗證輸出質量時不要只看 AI 有沒有“提到”你的規則要看它是否完整執行了你給出的流程。以“前端代碼審查 skills”為例理想的輸出應該包含 SKILL.md 中規定的五個部分審查范圍、嚴重問題、建議改進、符合規范部分、修改示例。如果 AI 只返回了一句“代碼看起來不錯但有一些小問題”說明它沒有嚴格按 skill 執行需要檢查 SKILL.md 的指令是否足夠明確或者觸發條件是否匹配。如果運行失敗排查順序如下第一步檢查 skill 目錄是否真的放在了工具查找的位置。很多情況下AI 沒有加載 skill 只是因為目錄放錯了。第二步檢查 SKILL.md 的 frontmatter 中的 name 和 description 是否準確。description 是 AI 判斷“何時使用該技能”的關鍵信號如果寫得模糊AI 可能不知道該調用它。第三步檢查 SKILL.md 中的執行步驟是否具體是否有 AI 無法執行的動作。第四步檢查 references 文件是否被正確引用。如果 SKILL.md 中寫了讀取某個文件但實際目錄里沒有這個文件AI 可能只按 SKILL.md 的通用內容回答。8. 員工skills常見問題與排查方法這里合并了個人開發者和團隊管理者最常遇到的問題整理成一張排查表。問題現象可能原因排查方式解決方案AI 沒有加載 skill仍然按普通方式回答skill 目錄位置不在工具搜索路徑內確認目錄是否放在.claude/skills、skills等約定位置移動到正確目錄或檢查項目的配置文件AI 加載了 skill但完全不按 SKILL.md 執行SKILL.md 中的步驟不具體AI 無法理解查看 SKILL.md 是否給出可執行動作和輸出格式將步驟拆細加入明確的輸出結構要求輸出結果時好時壞不穩定提示詞依賴太多規則沒有被確定性執行把關鍵規則改為必須執行的 list 形式將“必須檢查項”和“可選檢查項”分開skill 內容太多上下文被消耗過大SKILL.md 和 references 文件過于冗長檢查 skill 目錄大小和文檔篇幅精簡文檔把次要內容折疊到 references 中按需引用團隊多人維護skill 內容混亂缺乏命名規范、目錄結構不統一查看是否存在多個功能重疊的 skill建立統一規范指定唯一 owner技能更新后AI 仍使用舊邏輯AI 會話緩存導致的舊上下文查看會話上下文和工具進程版本重啟會話確認重新加載最新 skill 文件技能涉及數據操作時AI 誤刪數據腳本沒有權限保護AI 直接執行危險命令檢查 skill 中是否包含刪除類指令腳本中增加確認機制和最小權限原則需要特別強調一點如果團隊把 skills 用于生產環境、數據庫操作或權限相關場景務必在 SKILL.md 中明確寫入“執行危險操作前必須向用戶確認”的規則。skills 不會主動降低安全性安全邊界由編寫者自己負責。9. 員工skills落地的最佳實踐如果你們公司或團隊準備開始做員工skills下面幾個實踐建議可以參考。9.1 從高頻痛點起步不要一開始就試圖建立龐大的技能庫。先找 3 到 5 個團隊最高頻、最耗時的任務把它們做成 skills實際用起來再慢慢擴展。高頻任務通常有幾個特征重復發生、規則明確、完成后有明確產物。代碼審查、接口文檔生成、技術方案編寫、測試用例生成、發布檢查清單都是很好的起點。9.2 統一命名與目錄規范在團隊倉庫中約定一套規范比如skills 放在skills/或.claude/skills/目錄。每個 skill 一個目錄目錄名用中劃線連接比如frontend-code-review。每個 skill 必須有 SKILL.md且 frontmatter 中的 name 和 description 必須寫清楚。references 中只放必要文檔不放入與技能無關的資料。9.3 Skill 的維護比創建更重要一個沒有人維護的 skill半年后會變成一文不值的歷史包袱。建議團隊指定每個 skill 的 owner并建立季度審查機制定期檢查這些規則還符合當前團隊規范嗎這個 skill 還有人用嗎有沒有更好的腳本或工具可以替換9.4 安全與權限邊界skills 本質上是代碼團隊應該在代碼審查時同步審查 skills 的腳本內容尤其是涉及文件刪除、數據修改、外部請求的腳本。建議在 SKILL.md 中增加安全約束并在腳本層面遵循最小權限原則。生產環境操作類的 skill必須要求人工二次確認。9.5 先學習再復用對企業里最典型的場景建議先收集老員工在真實項目中如何操作再把這些經驗轉化為 skill 的規則。這種方式沉淀出來的 skill 通常比 AI 自己生成的通用技能有價值得多因為它包含了團隊特有的知識和約束。10. 員工skills的設計誤區最后再來看看員工skills最容易被誤解的幾個點。理解這些誤區能幫你少走彎路。第一個誤區把 skill 當成提示詞收藏夾。有些人把平時積累的提示詞統一封裝成 skill結果發現 AI 的行為沒有本質變化。原因在于skill 的價值不在于“存了一段提示詞”而在于它提供了完整的決策流程和執行標準包括觸發條件、步驟、輸出格式、參考資料。第二個誤區追求大而全的 superpower 式技能包。社區里流行的 superpower skills 確實功能豐富但團隊落地時不要照搬這種方案。因為越大的技能包越難維護越難驗證。企業內部的 skill 應該小而專只做一件事并做好這一件事。第三個誤區期望 AI 100% 執行 skill 規則。即使寫了 SKILL.mdAI 仍然是大模型可能在某些情況下產生偏差。所以重要的技能需要設計驗證用例定期抽檢輸出質量而不是寫完就放手。第四個誤區忽略 skill 的上下文成本。每次調用 skill 都會消耗 token。如果一個技能加載了巨量參考文檔會拖慢響應速度也會降低模型對關鍵規則的注意力。精簡是 skill 設計的長期原則。第五個誤區把員工skills當成純技術任務來做。員工skills的難點不在寫代碼而在把隱形知識顯性化。這需要技術負責人、資深工程師、AI 工程化人員一起參與而不是把它丟給一個人去“開發”就結束了。11. 對開發者的行動建議如果你是一名開發者看完這篇文章后可以按下面的路徑開始實踐。第一步在本地建一個skills目錄選一個自己重復遇到三次以上的任務照著 SKILL.md 格式寫一個最小可用的技能包。第二步把它安裝到你目前使用的 AI 編程工具中跑通一個從觸發到輸出的完整流程。第三步驗證輸出質量調整 SKILL.md 的步驟和規則直到結果穩定。第四步把技能包提交到團隊的代碼倉庫并邀請同事試用。第五步收集反饋優化細節然后基于同樣流程開發第二個、第三個技能包。對于技術負責人或架構師行動建議則是第一步盤點團隊重復性最高的 5 類任務明確每個任務的已有規范和完成標準。第二步定一個簡單的 skills 倉庫規范先保證命名統一、目錄統一、owner 明確。第三步從任務清單中挑一個最有把握的做成第一個員工skills設置驗證用例。第四步復盤效果看它是否真的提高了團隊的效率或一致性再決定要不要繼續投入。員工skills還處于早期它不會是 AI 工具的最終形態但它代表了一個明確的方向知識經驗不再只是給人看的文檔而是可執行、可復用、可驗證的 AI 能力單元。提前把這條路跑通的公司在 AI 落地上的效率差距會越來越大。希望這篇文章能給你一個清晰的起點。如果你的團隊也在嘗試做員工skills可以沿著上面的示例先做一個最小閉環試試看。實踐之后你大概率會發現真正讓 skill 發揮價值的不是格式和工具而是你把自己團隊做事的標準想明白了多少。 員工Skills：把團隊經驗封裝成AI可復用的能力模塊
最近在技術社區里一個話題開始被頻繁提起“聽說一些公司開始做員工skills了”。如果你關注過 Claude Code、Codex、Cursor、OpenCode 這些 AI 編程工具大概率已經見過skills這個英文詞。它并非某一家公司的專屬概念而是正在成為 AI Agent 時代的一種新“知識封裝單元”。但聽到“員工skills”很多人第一反應是這不就是給 AI 寫提示詞嗎公司搞這個和以前沉淀文檔、做 Wiki、搞專家庫有什么區別這篇文章想聊清楚幾件事員工skills到底是什么為什么它和提示詞、Agent、Tools 這些概念有本質差異以及一家公司如果要落地“員工skills”應該從哪個環節開始、有哪些坑、需要什么樣的工程規范。文章會給出一個完整的示例從目錄結構、編寫規范到實際安裝和驗證盡量讓技術讀者看完后不僅理解概念還能在自己的項目里跑通一個最小閉環。1. 這篇文章真正要解決的問題先從一個具體的場景切入。假設你是一家公司的前端負責人團隊 20 個人每天要用 AI 輔助做代碼審查。你發現不同的開發問 AI 的方式完全不一樣有的人會貼上一大段代碼讓 AI“幫我看看有沒有問題”有的人會要求“找出性能隱患和可訪問性問題”還有的人希望 AI 按照團隊自己的 ESLint 規則給出修改建議。結果就是AI 的回答質量參差不齊。團隊成員每次都要寫不同的提示詞有人寫得好有人寫得差。更麻煩的是團隊積累的那些審查經驗比如“圖片必須加懶加載”“按鈕交互必須有 loading 態”“移動端禁止橫向滾動”全部散落在各種文檔和每個人的腦海里AI 根本不知道。這時候如果做一套“前端代碼審查 skills”把這些規則、檢查項、示例代碼全部封裝成一個可復用的技能包團隊成員只要讓 AI 加載這個 skillAI 就能按照團隊一致的規范去審查代碼。這就是“員工skills”要解決的問題把人和團隊的經驗轉化為 AI 可復用的能力模塊而不是靠每個人反復輸入零散的提示詞。所以這篇文章值得一讀的人群包括正在使用 Claude Code、Codex、Cursor、OpenCode 等 AI 編程工具的開發者。團隊里負責 AI 工程化、負責沉淀開發規范的架構師和技術負責人。對 Agent、Skill、Tool 這些概念有困惑想搞清楚它們之間邊界的人。讀完這篇文章你會明白員工skills不是“給 AI 寫幾句提示詞”那么簡單而是一套有結構、有目錄規范、有可執行腳本、有驗證方式的工程化產物。2. Skills 的基礎概念它到底是哪一層的東西要理解員工skills首先得把“skills”和它周圍的幾個概念分清楚。2.1 Skills 是什么從材料信息看當前 AI 工具鏈中影響最廣的 skills 規范之一是 Anthropic 推行的 Agent Skills 格式。這個格式的基本單元是一個目錄目錄里包含一個SKILL.md文件用來描述這個技能的功能、使用場景、工作流程目錄里還可以放各種輔助腳本、模板、參考文檔它們會被 AI 在執行任務時動態加載。一個典型的 skills 目錄結構看起來是這樣的code-review-skill/ ├── SKILL.md └── scripts/ ├── check-eslint.md └── review-frontend.py這里面的關鍵設計是SKILL.md 不是給人類閱讀的而是給 AI 讀取的指令手冊。當 AI 遇到與這個 skill 相關的任務時它會自動讀取 SKILL.md按照里面的規則和流程去執行。這樣一來人類團隊的規范就變成了 AI 的工作指南。2.2 Skills 和提示詞Prompt的區別很多人覺得 skills 就是高級提示詞這種理解對了一半。提示詞是一次性的自然語言指令。它存在于對話上下文里用完就沒了。即使你把自己的提示詞寫得天花亂墜換個會話AI 又忘得一干二凈。Skills 是持久化的能力封裝。它不只是“一段文字指令”還包括執行邏輯、參考資料、腳本工具以及觸發條件。更重要的是skills 是放在項目目錄里的文件可以被版本管理可以被團隊分享可以被 AI 動態發現和加載。打個比方提示詞像你在餐廳臨時告訴廚師“這道菜少放鹽、多放辣、不要香菜”skills 像廚師手里那本標準化菜譜里面規定了每一步的做法、用哪種醬油、什么時候下鍋。2.3 Skills 和 Tools、Agents 的區別這里有一個非常容易混淆的點。Tools 是 AI 可以調用的外部功能。比如“搜索網頁”“讀文件”“執行代碼”“調用某個 API”。它們解決的是“AI 能對外部世界做什么”的問題。在 Claude Code 里Tools 是內置的你可以讓 AI 讀文件、寫文件、執行 Bash 命令。Skills 解決的是“AI 如何按照特定方式做一件事”的問題。它更像一套操作規范告訴你什么時候調用工具、調用哪些工具、按照什么順序、遵循什么標準。同一個 Tool用不同的 Skills 去編排產出的結果會完全不同。Agents 則是更大的概念。Agent 是一個能自主規劃、調用工具、執行任務的系統。Skills 可以理解為 Agent 身上的技能包。一個粗略的層級關系是概念解決的問題形態提示詞告訴 AI 做什么一段文本Tools讓 AI 能操作外部世界函數/API/命令Skills讓 AI 按特定標準完成一類任務規則文檔腳本參考資料Agents自主分析、決策、執行復雜任務一個智能體程序這樣看下來員工skills的真正價值就清晰了它不是給某個具體任務寫一次性提示詞而是把一類可重復的任務固化成 AI 能穩定執行的能力標準。2.4 Skills 和 MCP 的關系還有一個容易混淆的概念是 MCPModel Context Protocol。MCP 解決的是“如何把外部數據源和工具接入 AI”的傳輸協議問題。Skills 和 MCP 不是競爭關系而是不同層次的東西。Skills 可以觸發 AI 去調用 MCP 服務器提供的工具也可以直接使用腳本完成工作。它們是互補的。在實際項目中一個清晰的判斷是如果你只是給 AI 提供“按團隊規范審查代碼”“按固定格式生成會議紀要”這類標準化能力skills 是更輕量、更直接的選擇如果你需要接入公司內部的數據源、API、數據庫MCP 可能更合適。兩者可以同時存在。3. 為什么公司開始把“員工skills”當成一件事來做聊完概念回到文章標題為什么一些公司開始做員工skills了核心驅動因素是AI 工具的普及讓“個人能力”和“組織能力”之間的差距被放大了。過去一個資深工程師的經驗通過代碼評審、技術分享、文檔沉淀來傳遞。這個過程很慢而且損耗很大。新員工要看很久文檔、問很多人才能達到“像老員工一樣做事”的水平。但在 AI 編程工具普及之后團隊里的每一個開發都在和 AI 協作。AI 的輸出質量取決于:你給了它什么上下文它知不知道你的團隊規范有沒有按照你的工程標準去執行。這時候團隊遇到一個尷尬的問題AI 對公共知識很精通但對公司內部的知識一無所知。它不知道你們的命名規范、不知道你們的發布流程、不知道你們常見的線上事故、不知道你們約定俗成的代碼結構。員工skills就是用來解決這個“內部知識斷裂”問題的。公司做員工skills本質上是在做一件事把團隊內部的私域知識轉化為 AI 可以理解、加載、執行的結構化能力包。舉個例子一家公司可能在內部做一套“Java 后端開發 skills”里面包含團隊的項目分層規范Controller / Service / Repository 怎么劃分。接口返回值格式統一 Result 包裝、錯誤碼規范。數據庫操作規范必須走 MyBatis 分頁、禁止在循環里查庫。日志規范INFO 記錄入參出參、WARN 記錄重試、ERROR 記錄異常堆棧。測試要求關鍵業務必須有單元測試覆蓋率不低于多少。一旦這套 skills 建好團隊的 AI 編程工具就能輸出符合公司風格的代碼而不是泛泛的“標準答案”。更進一步公司還可以做“前端代碼審查 skills”“數據庫變更評審 skills”“生產環境故障排查 skills”“技術方案編寫 skills”。每一個 skills 都是對一類高頻重復工作的標準化封裝。4. 員工skills的落地從個人技能到組織能力理解了概念和動機之后下一步要解決的是員工skills到底怎么在公司落地4.1 個人技能的沉淀路徑從一個開發者的視角來看最自然的切入點是我把平時寫的最好的提示詞、最常用的檢查項、最頻繁的回歸流程設計成一個可復用的技能包。這個階段不涉及復雜的組織設計只要個人愿意花一點時間整理即可。典型的做法是第一步找出重復次數最多的任務。比如“幫我用 Vue3 寫一個表格組件”“幫我檢查這個頁面的響應式布局問題”——這是每周都會出現的高頻請求。第二步把這個任務的完成標準拆成步驟和檢查項。比如寫表格組件時必須支持分頁、loading、空狀態、列寬拖動并且使用團隊的BaseTable基類。第三步把這些步驟寫成 SKILL.md放到項目目錄里測試一下 AI 是否真的能按標準執行。4.2 從個人技能到團隊技能個人 skills 的局限在于它只在一個人的項目里有效。要變成團隊能力至少要解決三個問題。第一個問題是存放位置。團隊的 skills 不能散落在每個人的電腦里而是應該放在統一的代碼倉庫中比如team-skills/所有團隊成員共享。第二個問題是命名與分類。如果不對 skills 做統一管理過一段時間就會產生大量功能重疊、命名混亂的技能包。比如“前端審查”“code-review”“vue-check”可能做的是同一件事。第三個問題是更新維護。團隊規范會變skills 也必須跟著變。如果沒人負責維護skills 就會慢慢變成廢棄文檔。一個有實踐價值的做法是由技術負責人或架構師牽頭把團隊里已經驗證有效的個人 skills 收斂到統一倉庫并指定對應的 owner。每個 skill 都要有版本說明和更新日志就像代碼庫一樣管理。4.3 企業級 skills 的工程化如果公司的目標是把 skills 做成真正的組織能力那就需要對 skills 做工程化治理。至少包括規范層定義 skills 目錄結構、文案語言、觸發條件、質量標準。倉庫層建立 skills 的統一代碼倉庫支持版本管理、變更評審、發布。測試層為每個 skill 設計驗證用例確保 AI 加載后能穩定輸出預期結果。運營層統計哪些 skills 被高頻使用、哪些沒人用、哪些效果不好及時淘汰和更新。這四個層次聽起來復雜但實際落地時可以從最小集開始先做一個統一倉庫再定一個簡單的目錄規范最后把團隊的 top-3 高頻任務各封裝成一個 skill。5. 核心流程拆解如何寫一個員工skills上面講了很多理念這一節進入實操層面。我們以“前端代碼審查 skills”為例完整拆解一個員工skills的創建流程。5.1 定義 skill 的目標與邊界寫一個 skill 之前首先要回答三個問題這個 skill 是什么負責哪一類任務這個 skill 不是什么它不處理哪些任務邊界是什么執行這個 skill 后AI 應該交付什么結果以“前端代碼審查”為例它負責審查前端代碼中的性能問題、可訪問性問題、響應式布局問題、規范不符合問題。它不負責不審查后端邏輯、不審查數據庫設計、不替代人工走查視覺細節。交付結果一份按嚴重程度分級的審查報告包含問題描述、示例代碼、修改建議、對應文件路徑。這一步很關鍵。如果邊界不清楚AI 會什么都往這個 skill 里塞。5.2 搭建目錄結構根據 Agent Skills 的通用結構建議先建一個目錄frontend-code-review/ ├── SKILL.md ├── scripts/ │ └── list-files.py └── references/ └── team-frontend-rules.mdSKILL.md是主入口用于告訴 AI 這個技能是干什么的、什么時候啟用、怎么執行。scripts/用于放可執行的輔助腳本。references/用于放團隊規范、代碼示例、參考文檔。5.3 編寫 SKILL.mdSKILL.md的編寫質量直接決定整個 skill 好不好用。下面是一份示例你可以根據團隊實際情況修改。--- name: frontend-code-review description: 按團隊前端規范審查代碼檢查性能、可訪問性、響應式與規范問題輸出分級審查報告。 --- # 前端代碼審查 ## 適用場景 當用戶要求“審查這段前端代碼”“幫我做 code review”“檢查這個組件是否有性能問題”時使用本技能。 ## 不適用場景 - 用戶要求審查后端接口、數據庫邏輯、基礎設施配置。 - 用戶只要求解釋代碼含義不做質量評估。 ## 執行步驟 1. 先確認審查范圍是單個文件還是改動文件列表。 2. 讀取涉及的代碼文件定位組件類型與核心邏輯。 3. 按“性能與渲染”“可訪問性”“響應式與移動端”“代碼規范”四個維度逐項檢查。 4. 參考 references/team-frontend-rules.md 中的團隊規范確認是否存在不一致。 5. 輸出分級審查報告。 ## 審查重點 ### 性能與渲染 - 列表是否使用 key且 key 是否為穩定唯一值。 - 是否存在不必要的 setState 導致重復渲染。 - 圖片是否開啟懶加載。 - 大數據量場景是否使用了虛擬滾動。 ### 可訪問性 - 交互元素是否包含合適的 aria-label。 - 圖片是否提供 alt 文本。 - 是否可以在無鼠標狀態下完成核心操作。 ### 響應式與移動端 - 是否出現固定寬高導致的橫向滾動。 - 是否使用 rem、vw/vh 或響應式斷點。 - 移動端點擊區域是否過小。 ### 代碼規范 - 是否存在違反團隊命名規范的標識符。 - 是否有 console.log 殘留。 - 是否有未使用的 import 或變量。 ## 輸出格式 按以下結構輸出審查報告 1. 審查范圍 2. 嚴重問題必須修復說明原因與修復方式 3. 建議改進值得優化給出具體方案 4. 符合規范的部分簡短說明幫助開發者理解哪些寫得好 5. 修改示例對問題最嚴重的一處給出優化前后的代碼對比這份文檔看起來很樸素但它實際是把團隊經驗結構化成了 AI 可執行的步驟。每個審查重點都是一條規則AI 在審查時會逐條對照。5.3.1 SKILL.md 編寫的六個要點如果沒有寫過 skill第一次寫時很容易踩坑。下面是六個實戰中驗證過的要點。第一個要點觸發條件要明確。SKILL.md 里的“適用場景”要寫得具體否則 AI 可能在不該啟用時亂用或者該用時不用。第二個要點步驟要可執行不要寫太抽象。比如“檢查代碼質量”太模糊“檢查是否存在不必要的 setState 導致重復渲染”就很具體。第三個要點規則要有示例。特別是團隊自定義的規范最好附上“正確寫法”和“錯誤寫法”的代碼片段。第四個要點輸出格式必須定義。如果不定義輸出格式AI 每次給的報告格式都不一樣后期很難統計和消費。第五個要點注意 token 消耗。SKILL.md 會被 AI 加載進上下文太冗長會浪費上下文窗口。所以能用列表表達的就不要寫長篇論述。第六個要點定期版本化。SKILL.md 一旦穩定就給它打一個版本號。后續團隊規范變化時可以對比差異并更新。5.4 創建輔助腳本不是所有的 skill 都需要腳本但如果技能涉及文件掃描、數據統計、格式校驗腳本可以讓 AI 的執行更穩定。以下是一個簡單的 Python 腳本用于從項目中提取待審查的前端文件列表#!/usr/bin/env python3 # 文件路徑frontend-code-review/scripts/list-files.py # 功能掃描項目中的前端源碼文件列出待審查文件。 import os import sys EXCLUDE_DIRS {node_modules, dist, build, .git, .next} FRONT_END_EXTS {.vue, .tsx, .jsx, .ts, .js, .css, .scss, .less} def main(): root sys.argv[1] if len(sys.argv) 1 else . files [] for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in EXCLUDE_DIRS] for f in filenames: if os.path.splitext(f)[1] in FRONT_END_EXTS: files.append(os.path.join(dirpath, f)) files.sort() for file in files: print(file) if __name__ __main__: main()這個腳本本身沒什么難度但它在 skill 中的價值是讓 AI 不依賴自己猜測文件路徑直接拿到準確的文件清單。引用方式很簡單在 SKILL.md 的執行步驟中寫明如果需要審查整個項目中的前端文件先運行以下命令獲取文件清單 bash python3 scripts/list-files.py .然后對清單中的文件進行逐項審查。### 5.5 加入團隊規范文檔 references/team-frontend-rules.md 是團隊知識的集中體現。這一部分無需從零編寫可以直接把團隊已有的前端規范、代碼評審 checklist、常見問題列表整理進去。 markdown # 團隊前端規范摘要 ## 命名規范 - 組件文件名PascalCase如 UserProfile.vue - 普通工具函數camelCase如 formatDateTime.ts - CSS 類名BEM 風格如 block__element--modifier ## 組件規范 - 通用表格必須使用 BaseTable 組件 - 表單必須支持 Enter 鍵提交 - 圖片必須指定寬高避免布局偏移 ## 禁止項 - 禁止在 render 函數中直接 new Date()除非有明確更新需求 - 禁止在循環中使用 await 發起串行請求 - 禁止在組件卸載后更新狀態 ## 常見性能問題 - 大列表未開啟虛擬滾動 - 父子組件未使用 memo / computed 導致無效渲染 - 動態 import 未做 Suspense 邊界處理建議一開始不要追求大而全先聚焦團隊最容易出問題的 5 到 10 條規則后續再逐步擴充。6. 完整示例構建一個“員工skills”并安裝到 AI 編程工具為了讓文章更落地這里給出一個從零到一的最小完整示例。我們會創建一個小型的“新員工入職指引 skills”目標是讓 AI 能夠根據它回答新員工關于公司開發環境、代碼倉庫、提交流程的問題。6.1 創建目錄與文件第一步建立目錄結構mkdir -p team-onboarding-skill/scripts cd team-onboarding-skill第二步創建SKILL.md--- name: team-onboarding description: 回答新員工入職相關問題包括開發環境搭建、代碼倉庫地址、分支規范、提交流程、常見命令。 --- # 新員工入職指引 ## 適用場景 當用戶詢問以下問題時啟用本技能 - “公司代碼倉庫在哪里” - “如何配置開發環境” - “提交代碼的流程是什么” - “有哪些開發規范需要遵守” ## 執行步驟 1. 先判斷用戶所在小組和項目類型。 2. 根據問題類型查閱 references 目錄中的對應文檔。 3. 如果文檔中缺少信息明確告知用戶“該信息未在團隊知識庫中收錄請咨詢對應項目負責人”不要編造。 4. 回答時盡量給出可復制的命令或操作步驟。 ## 回答要求 - 所有命令必須給出完整命令并注明在哪個目錄下執行。 - 涉及敏感信息密碼、Token時提示用戶走公司內部安全通道獲取禁止出現在回答中。 - 如果問題涉及賬號權限引導用戶走權限申請流程不要嘗試繞過權限系統。第三步創建references/development-setup.md放開發環境配置信息# 開發環境搭建 ## 前端項目 依賴節點版本 20使用 pnpm 作為包管理器。 bash nvm use 20 pnpm install pnpm dev后端項目依賴 JDK 21使用 Maven 構建。mvn clean install mvn spring-boot:run環境變量本地開發需要配置以下環境變量API_BASE_URL本地 API 地址APP_ENV設為devLOG_LEVEL設為debug第四步創建 references/git-workflow.md markdown # Git 提交流程 ## 分支命名 - 功能分支feature/xxx - 修復分支fix/xxx - 發布分支release/xxx ## 提交信息 提交信息必須包含 Jira 單號例如 text [PROJ-123] 完成用戶列表功能合并規范功能開發完成后通過 Merge Request 合并到 develop 分支至少 1 人審批。### 6.2 把 skill 安裝到 Claude Code 目前各類 AI 編程工具對 skills 的支持方式大同小異把 skill 目錄放在一個約定的位置AI 就能發現并加載它。 在 Claude Code 中社區的常見做法是將 skills 放在項目根目錄的 .claude/skills/ 下或者用戶級目錄的 ~/.claude/skills/ 下。以剛才創建的 onboarding skill 為例 bash # 假設你的項目在 ~/work/my-project mkdir -p ~/work/my-project/.claude/skills cp -r team-onboarding-skill ~/work/my-project/.claude/skills/安裝完成后你在 Claude Code 對話中輸入“如何開發環境搭起來”或者“我們項目的分支規范是什么”AI 就有機會加載這個 skill按照里面的規則回答。6.3 把 skill 安裝到 Codex在 OpenAI Codex 中社區實踐是使用AGENTS.md配合 skills 目錄的方式。你可以把 skill 放到項目倉庫的skills/目錄下并在說明文檔中引用。更通用的做法是不管工具怎么變化你只需要保證兩點——第一skill 目錄存在于項目倉庫中第二目錄里有一個 AI 能讀取到的主文件SKILL.md 或類似命名。下面是在 Codex CLI 項目中使用 skill 的示意mkdir -p ~/work/my-project/skills cp -r team-onboarding-skill ~/work/my-project/skills/然后在項目根目錄的AGENTS.md中增加一行團隊技能包位于 skills/ 目錄遇到與對應技能相關的問題時請先讀取相關 SKILL.md。6.4 安裝到 Cursor 和 OpenCodeCursor 類 IDE 中skills 的加載通常有兩種實現方式一種是借助.cursor/rules或項目配置文件把技能內容注入上下文另一種是把 skill 作為項目文件由 AI 通過文件讀取能力加載。如果你使用的是 OpenCode社區的做法是把 skill 放在項目內統一的目錄然后通過配置讓 AI 知道這個目錄的存在。以 OpenCode 為例可以在項目的配置說明中寫清楚# OpenCode 項目配置 skills 目錄./skills 規則遇到與本項目技能包相關的任務時必須先查看對應目錄下的 SKILL.md 再回答。這種“配置聲明 文檔說明”的方式雖然不是某個工具的官方標準格式但在目前 skills 生態尚未完全統一的情況下是兼容性最高、最容易上手的做法。7. 運行結果與效果驗證寫完 skill 并安裝到工具之后不能直接宣布完成。你需要驗證兩件事第一AI 能不能正確發現和加載這個 skill第二AI 執行 skill 的結果是否符合預期。7.1 驗證 AI 是否正確加載了 skill最簡單的方法是用一個觸發問題去測試。比如你剛安裝了 onboarding skill在會話中提問請先查看團隊技能包中是否有新員工入職相關的技能如果有請按照其規則回答我的前端項目如何啟動如果 AI 加載成功它的回答應該包含SKILL.md中定義的步驟和 references 中提到的具體命令而不是給出一段泛泛的答非所問。還可以在提問中直接要求請告訴我你在處理這個問題時使用了哪個技能包它的主要規則是什么通過這種元問題你可以確認 AI 是否真的讀取了你的 SKILL.md。7.2 判斷輸出質量驗證輸出質量時不要只看 AI 有沒有“提到”你的規則要看它是否完整執行了你給出的流程。以“前端代碼審查 skills”為例理想的輸出應該包含 SKILL.md 中規定的五個部分審查范圍、嚴重問題、建議改進、符合規范部分、修改示例。如果 AI 只返回了一句“代碼看起來不錯但有一些小問題”說明它沒有嚴格按 skill 執行需要檢查 SKILL.md 的指令是否足夠明確或者觸發條件是否匹配。如果運行失敗排查順序如下第一步檢查 skill 目錄是否真的放在了工具查找的位置。很多情況下AI 沒有加載 skill 只是因為目錄放錯了。第二步檢查 SKILL.md 的 frontmatter 中的 name 和 description 是否準確。description 是 AI 判斷“何時使用該技能”的關鍵信號如果寫得模糊AI 可能不知道該調用它。第三步檢查 SKILL.md 中的執行步驟是否具體是否有 AI 無法執行的動作。第四步檢查 references 文件是否被正確引用。如果 SKILL.md 中寫了讀取某個文件但實際目錄里沒有這個文件AI 可能只按 SKILL.md 的通用內容回答。8. 員工skills常見問題與排查方法這里合并了個人開發者和團隊管理者最常遇到的問題整理成一張排查表。問題現象可能原因排查方式解決方案AI 沒有加載 skill仍然按普通方式回答skill 目錄位置不在工具搜索路徑內確認目錄是否放在.claude/skills、skills等約定位置移動到正確目錄或檢查項目的配置文件AI 加載了 skill但完全不按 SKILL.md 執行SKILL.md 中的步驟不具體AI 無法理解查看 SKILL.md 是否給出可執行動作和輸出格式將步驟拆細加入明確的輸出結構要求輸出結果時好時壞不穩定提示詞依賴太多規則沒有被確定性執行把關鍵規則改為必須執行的 list 形式將“必須檢查項”和“可選檢查項”分開skill 內容太多上下文被消耗過大SKILL.md 和 references 文件過于冗長檢查 skill 目錄大小和文檔篇幅精簡文檔把次要內容折疊到 references 中按需引用團隊多人維護skill 內容混亂缺乏命名規范、目錄結構不統一查看是否存在多個功能重疊的 skill建立統一規范指定唯一 owner技能更新后AI 仍使用舊邏輯AI 會話緩存導致的舊上下文查看會話上下文和工具進程版本重啟會話確認重新加載最新 skill 文件技能涉及數據操作時AI 誤刪數據腳本沒有權限保護AI 直接執行危險命令檢查 skill 中是否包含刪除類指令腳本中增加確認機制和最小權限原則需要特別強調一點如果團隊把 skills 用于生產環境、數據庫操作或權限相關場景務必在 SKILL.md 中明確寫入“執行危險操作前必須向用戶確認”的規則。skills 不會主動降低安全性安全邊界由編寫者自己負責。9. 員工skills落地的最佳實踐如果你們公司或團隊準備開始做員工skills下面幾個實踐建議可以參考。9.1 從高頻痛點起步不要一開始就試圖建立龐大的技能庫。先找 3 到 5 個團隊最高頻、最耗時的任務把它們做成 skills實際用起來再慢慢擴展。高頻任務通常有幾個特征重復發生、規則明確、完成后有明確產物。代碼審查、接口文檔生成、技術方案編寫、測試用例生成、發布檢查清單都是很好的起點。9.2 統一命名與目錄規范在團隊倉庫中約定一套規范比如skills 放在skills/或.claude/skills/目錄。每個 skill 一個目錄目錄名用中劃線連接比如frontend-code-review。每個 skill 必須有 SKILL.md且 frontmatter 中的 name 和 description 必須寫清楚。references 中只放必要文檔不放入與技能無關的資料。9.3 Skill 的維護比創建更重要一個沒有人維護的 skill半年后會變成一文不值的歷史包袱。建議團隊指定每個 skill 的 owner并建立季度審查機制定期檢查這些規則還符合當前團隊規范嗎這個 skill 還有人用嗎有沒有更好的腳本或工具可以替換9.4 安全與權限邊界skills 本質上是代碼團隊應該在代碼審查時同步審查 skills 的腳本內容尤其是涉及文件刪除、數據修改、外部請求的腳本。建議在 SKILL.md 中增加安全約束并在腳本層面遵循最小權限原則。生產環境操作類的 skill必須要求人工二次確認。9.5 先學習再復用對企業里最典型的場景建議先收集老員工在真實項目中如何操作再把這些經驗轉化為 skill 的規則。這種方式沉淀出來的 skill 通常比 AI 自己生成的通用技能有價值得多因為它包含了團隊特有的知識和約束。10. 員工skills的設計誤區最后再來看看員工skills最容易被誤解的幾個點。理解這些誤區能幫你少走彎路。第一個誤區把 skill 當成提示詞收藏夾。有些人把平時積累的提示詞統一封裝成 skill結果發現 AI 的行為沒有本質變化。原因在于skill 的價值不在于“存了一段提示詞”而在于它提供了完整的決策流程和執行標準包括觸發條件、步驟、輸出格式、參考資料。第二個誤區追求大而全的 superpower 式技能包。社區里流行的 superpower skills 確實功能豐富但團隊落地時不要照搬這種方案。因為越大的技能包越難維護越難驗證。企業內部的 skill 應該小而專只做一件事并做好這一件事。第三個誤區期望 AI 100% 執行 skill 規則。即使寫了 SKILL.mdAI 仍然是大模型可能在某些情況下產生偏差。所以重要的技能需要設計驗證用例定期抽檢輸出質量而不是寫完就放手。第四個誤區忽略 skill 的上下文成本。每次調用 skill 都會消耗 token。如果一個技能加載了巨量參考文檔會拖慢響應速度也會降低模型對關鍵規則的注意力。精簡是 skill 設計的長期原則。第五個誤區把員工skills當成純技術任務來做。員工skills的難點不在寫代碼而在把隱形知識顯性化。這需要技術負責人、資深工程師、AI 工程化人員一起參與而不是把它丟給一個人去“開發”就結束了。11. 對開發者的行動建議如果你是一名開發者看完這篇文章后可以按下面的路徑開始實踐。第一步在本地建一個skills目錄選一個自己重復遇到三次以上的任務照著 SKILL.md 格式寫一個最小可用的技能包。第二步把它安裝到你目前使用的 AI 編程工具中跑通一個從觸發到輸出的完整流程。第三步驗證輸出質量調整 SKILL.md 的步驟和規則直到結果穩定。第四步把技能包提交到團隊的代碼倉庫并邀請同事試用。第五步收集反饋優化細節然后基于同樣流程開發第二個、第三個技能包。對于技術負責人或架構師行動建議則是第一步盤點團隊重復性最高的 5 類任務明確每個任務的已有規范和完成標準。第二步定一個簡單的 skills 倉庫規范先保證命名統一、目錄統一、owner 明確。第三步從任務清單中挑一個最有把握的做成第一個員工skills設置驗證用例。第四步復盤效果看它是否真的提高了團隊的效率或一致性再決定要不要繼續投入。員工skills還處于早期它不會是 AI 工具的最終形態但它代表了一個明確的方向知識經驗不再只是給人看的文檔而是可執行、可復用、可驗證的 AI 能力單元。提前把這條路跑通的公司在 AI 落地上的效率差距會越來越大。希望這篇文章能給你一個清晰的起點。如果你的團隊也在嘗試做員工skills可以沿著上面的示例先做一個最小閉環試試看。實踐之后你大概率會發現真正讓 skill 發揮價值的不是格式和工具而是你把自己團隊做事的標準想明白了多少。