1. 從“skills”這個(gè)熱詞說起它到底是什么為什么突然火了如果你最近在開發(fā)者社區(qū)、技術(shù)群或者社交平臺上頻繁刷到“skills”這個(gè)詞大概率不是指傳統(tǒng)意義上的“技能”泛稱而是特指圍繞Claude Code、Codex、Agents等智能編程助手構(gòu)建的一套可插拔能力擴(kuò)展機(jī)制。簡單來說skills 就是讓 AI 編程助手從“只會(huì)聊天”變成“能按你的規(guī)矩干活”的那一層配置與腳本集合。它可能是一個(gè)封裝好的提示詞模板也可能是一段帶上下文注入的自動(dòng)化流程甚至是一組針對特定項(xiàng)目結(jié)構(gòu)的操作指令集。我最早接觸這個(gè)概念是在給團(tuán)隊(duì)搭建內(nèi)部編碼助手的時(shí)候。當(dāng)時(shí)大家用 Claude Code 或者 Codex 做代碼補(bǔ)全、寫單元測試、生成文檔效率確實(shí)有提升但問題也很明顯每次都要重復(fù)交代項(xiàng)目背景、代碼規(guī)范、目錄結(jié)構(gòu)模型給的答案時(shí)好時(shí)壞風(fēng)格完全不統(tǒng)一。后來發(fā)現(xiàn)社區(qū)里已經(jīng)有人在用“skills”的思路來解決這個(gè)問題——把項(xiàng)目約定、常用操作、領(lǐng)域知識打包成可復(fù)用的模塊讓助手在特定場景下自動(dòng)加載。這一下就把“每次重新調(diào)教”變成了“一次配置長期復(fù)用”。這篇文章適合三類人看第一類是完全沒接觸過 Claude Code 或 Codex但想搞清楚“skills”到底能干什么的開發(fā)者第二類是已經(jīng)在用這些工具但還在靠手動(dòng)復(fù)制粘貼提示詞的進(jìn)階用戶第三類是想把 AI 助手接入團(tuán)隊(duì)工作流需要一套可維護(hù)、可共享配置方案的技術(shù)負(fù)責(zé)人。我會(huì)從設(shè)計(jì)思路、核心細(xì)節(jié)、實(shí)操過程到常見問題把 skills 這套東西拆開講透盡量讓你看完就能動(dòng)手配一套自己的。2. 內(nèi)容整體設(shè)計(jì)與思路拆解為什么是 skills而不是別的方案2.1 從“提示詞工程”到“能力封裝”的必然演進(jìn)早期大家用 AI 編程助手基本停留在“對話式提示詞”階段。比如你想讓模型幫你寫一個(gè) React 組件可能會(huì)輸入“你是一個(gè)資深前端請按照 Airbnb 規(guī)范寫一個(gè)帶 TypeScript 的按鈕組件支持 loading 狀態(tài)和 disabled 狀態(tài)?！?這種方式的問題在于每次都要重新描述一遍上下文而且不同人寫的提示詞質(zhì)量參差不齊導(dǎo)致輸出結(jié)果極不穩(wěn)定。skills 的核心思路就是把這類重復(fù)性的上下文描述、操作流程、約束條件從“每次輸入”變成“一次定義、按需加載”。你可以把它理解成給 AI 助手裝了一個(gè)“項(xiàng)目知識包”當(dāng)助手檢測到你在處理某個(gè)特定任務(wù)時(shí)自動(dòng)把相關(guān)的規(guī)范、示例、甚至可調(diào)用的腳本注入到上下文中。這比單純堆提示詞要高效得多因?yàn)樗墙Y(jié)構(gòu)化的、可版本管理的、可組合的。我試過兩種極端方案一種是把所有規(guī)范寫成一個(gè)超長提示詞每次對話都粘貼一遍另一種是把規(guī)范拆成多個(gè) skills按場景加載。實(shí)測下來后者在 token 消耗、響應(yīng)速度和輸出一致性上都明顯更優(yōu)。尤其是當(dāng)項(xiàng)目變大、規(guī)范變多的時(shí)候長提示詞會(huì)迅速吃掉上下文窗口而 skills 可以做到“用什么加載什么”。2.2 為什么 Claude Code 和 Codex 成了 skills 的主要載體Claude Code 和 Codex 這類工具跟普通聊天窗口最大的區(qū)別在于它們直接運(yùn)行在終端或 IDE 里能讀取項(xiàng)目文件、執(zhí)行命令、查看 git 狀態(tài)。這意味著 skills 不只是文本提示詞還可以包含“讀取某個(gè)配置文件”“運(yùn)行某個(gè)腳本”“檢查某個(gè)目錄結(jié)構(gòu)”這樣的動(dòng)作。比如你可以定義一個(gè) skill讓助手在生成數(shù)據(jù)庫遷移文件之前先自動(dòng)讀取schema.prisma并檢查命名規(guī)范。另一個(gè)原因是這些工具通常支持插件或擴(kuò)展機(jī)制。雖然不同平臺的叫法不一樣有的叫 plugin有的叫 agent但底層邏輯是一致的允許用戶把自定義能力掛載到助手的工作流里。skills 就是掛載內(nèi)容的一種組織形式。社區(qū)里已經(jīng)有人把常用的 skills 打包成市場或倉庫比如“前端開發(fā) skills”“寫論文的 skills”“安卓逆向 skills”等等覆蓋場景非常廣。2.3 方案選型自己寫還是用現(xiàn)成的如果你剛開始接觸我建議先別急著從零寫 skills。社區(qū)里已經(jīng)有大量現(xiàn)成的配置可以參考比如針對 React、Vue、Python 后端、數(shù)據(jù)科學(xué)等場景的 skills 包。你可以先拿一個(gè)現(xiàn)成的跑起來看看它加載了哪些文件、注入了什么上下文、觸發(fā)了什么動(dòng)作然后再根據(jù)自己的項(xiàng)目改。自己寫 skills 的成本主要在兩個(gè)方面一是要搞清楚目標(biāo)工具的加載機(jī)制和配置格式二是要把項(xiàng)目里的隱性知識顯性化。前者是技術(shù)問題后者是工程問題。我的經(jīng)驗(yàn)是先從最痛的一個(gè)點(diǎn)開始比如“每次生成 API 接口都要手動(dòng)補(bǔ)參數(shù)校驗(yàn)”把這個(gè)場景做成一個(gè) skill跑通之后再逐步擴(kuò)展。不要一上來就想著做一個(gè)大而全的 skills 庫那樣很容易半途而廢。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)skills 到底怎么寫、怎么加載3.1 skills 的基本結(jié)構(gòu)元數(shù)據(jù)、觸發(fā)條件、上下文內(nèi)容雖然不同工具的 skills 格式有差異但核心結(jié)構(gòu)基本一致。一個(gè)典型的 skill 通常包含三部分元數(shù)據(jù)名稱、描述、版本、作者、適用場景。這部分決定了 skill 在列表里怎么展示、被搜索時(shí)能不能命中。觸發(fā)條件什么情況下加載這個(gè) skill?？梢允俏募愋推ヅ浔热?tsx文件、目錄匹配比如src/components/、命令匹配比如用戶輸入了“生成組件”也可以是手動(dòng)指定。上下文內(nèi)容真正注入給模型的內(nèi)容。可以是純文本規(guī)范、代碼示例、檢查清單也可以是對外部文件的引用路徑。我自己的習(xí)慣是把每個(gè) skill 寫成一個(gè)獨(dú)立目錄里面放一個(gè)skill.md或skill.json作為入口再按需放一些輔助文件。這樣版本管理方便也容易分享給同事。3.2 觸發(fā)條件的設(shè)計(jì)精準(zhǔn)比寬泛更重要觸發(fā)條件是 skills 里最容易踩坑的地方。我見過有人把觸發(fā)條件寫得太寬結(jié)果助手在任何場景下都加載一堆無關(guān)規(guī)范反而干擾了正常輸出。比如你寫了一個(gè)“前端組件規(guī)范”的 skill觸發(fā)條件設(shè)成“所有.ts文件”那后端代碼也會(huì)被誤傷。比較穩(wěn)妥的做法是按目錄或按文件后綴組合匹配。比如{ trigger: { include: [src/components/**/*.tsx, src/components/**/*.vue], exclude: [**/*.test.tsx, **/*.stories.tsx] } }這樣只有組件目錄下的源文件才會(huì)觸發(fā)測試文件和故事文件不受影響。另外觸發(fā)條件最好支持手動(dòng)覆蓋比如用戶可以通過命令強(qiáng)制加載或跳過某個(gè) skill避免自動(dòng)化邏輯在特殊情況下幫倒忙。3.3 上下文內(nèi)容的組織分層注入避免信息過載上下文內(nèi)容不是越多越好。模型能處理的上下文窗口有限而且無關(guān)信息會(huì)稀釋關(guān)鍵指令的權(quán)重。我的做法是把上下文分成三層第一層硬性約束。比如“必須使用 TypeScript 嚴(yán)格模式”“禁止使用any”“組件必須導(dǎo)出為命名導(dǎo)出”。這些是每次都要強(qiáng)調(diào)的。第二層風(fēng)格指南。比如命名規(guī)范、目錄結(jié)構(gòu)、注釋要求。這些可以按需加載不一定每次都要全量注入。第三層示例代碼。給一兩個(gè)正例和反例讓模型有參照物。示例不要太多否則會(huì)占用大量 token。實(shí)測下來三層結(jié)構(gòu)比一股腦全塞進(jìn)去效果要好很多。尤其是當(dāng)項(xiàng)目規(guī)范很多的時(shí)候分層加載能讓模型更聚焦在當(dāng)前任務(wù)上。注意不要在 skill 里寫與項(xiàng)目無關(guān)的通用知識比如“什么是 React”這種。模型本身已經(jīng)知道這些寫進(jìn)去只會(huì)浪費(fèi)上下文。3.4 與 plugin、agent 的關(guān)系別被名詞繞暈社區(qū)里經(jīng)?；煊?skills、plugin、agent 這幾個(gè)詞其實(shí)它們描述的是不同層次的東西。plugin 通常是工具層面的擴(kuò)展比如給 IDE 裝一個(gè)插件來支持某種語言agent 是行為層面的抽象比如一個(gè)專門負(fù)責(zé)代碼審查的智能體skills 則是能力層面的封裝是 agent 或助手可以調(diào)用的具體技能模塊。你可以這樣理解一個(gè) agent 可能擁有多個(gè) skills而 plugin 是讓 agent 能在特定環(huán)境里運(yùn)行的底層支持。比如你有一個(gè)“代碼審查 agent”它可能加載了“安全審查 skill”“性能審查 skill”“風(fēng)格審查 skill”而這些 skill 又依賴某個(gè) IDE plugin 來讀取文件。搞清楚這層關(guān)系配置的時(shí)候就不會(huì)亂。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)從零搭一套可用的 skills4.1 環(huán)境準(zhǔn)備確認(rèn)工具版本和配置目錄不同版本的 Claude Code 或 Codex 對 skills 的支持程度不一樣。我建議先確認(rèn)你用的工具版本然后找到它的配置目錄。以類 Unix 系統(tǒng)為例常見路徑是~/.config/下的某個(gè)子目錄Windows 則通常在%APPDATA%里。你可以通過工具的幫助命令或官方文檔確認(rèn)具體位置。找到配置目錄后一般會(huì)有一個(gè)skills或plugins子目錄。如果沒有手動(dòng)創(chuàng)建一個(gè)即可。接下來就是往里面放你的 skill 定義文件。有些工具支持熱加載改完立即生效有些需要重啟會(huì)話。我建議第一次配置時(shí)重啟一下確保加載邏輯沒有問題。4.2 寫第一個(gè) skill以“API 接口生成規(guī)范”為例假設(shè)我們有一個(gè) Node.js 后端項(xiàng)目每次生成 API 接口都要遵循一套固定規(guī)范使用 Express 路由、參數(shù)必須用 Joi 校驗(yàn)、返回值統(tǒng)一包裝成{ code, data, message }格式。我們可以把這個(gè)規(guī)范寫成一個(gè) skill。首先創(chuàng)建目錄結(jié)構(gòu)mkdir -p ~/.config/codex/skills/api-generator cd ~/.config/codex/skills/api-generator touch skill.json context.md examples.md然后編輯skill.json{ name: api-generator, description: 生成符合項(xiàng)目規(guī)范的 Express API 接口, version: 1.0.0, trigger: { include: [src/routes/**/*.ts], manual: true }, context: [context.md, examples.md] }context.md里寫硬性約束和風(fēng)格指南# API 生成規(guī)范 - 使用 Express Router不要用 app.get 直接掛載 - 每個(gè)接口必須定義 Joi schema放在同目錄的 schemas/ 下 - 返回值統(tǒng)一為 { code: number, data: any, message: string } - 錯(cuò)誤處理使用項(xiàng)目已有的 AppError 類 - 異步接口必須用 asyncHandler 包裝examples.md里放一個(gè)正例import { Router } from express; import Joi from joi; import { asyncHandler } from ../utils/asyncHandler; import { AppError } from ../utils/AppError; const router Router(); const createUserSchema Joi.object({ name: Joi.string().required(), email: Joi.string().email().required(), }); router.post(/users, asyncHandler(async (req, res) { const { error, value } createUserSchema.validate(req.body); if (error) { throw new AppError(400, error.message); } const user await userService.create(value); res.json({ code: 0, data: user, message: success }); })); export default router;配置完成后在會(huì)話里手動(dòng)加載這個(gè) skill然后讓助手生成一個(gè)新接口看看輸出是否符合規(guī)范。如果不符合就調(diào)整context.md里的措辭或者補(bǔ)充更多示例。4.3 參數(shù)計(jì)算與選擇token 預(yù)算怎么分配skills 的上下文內(nèi)容會(huì)占用模型的 token 預(yù)算。以常見的 128k 上下文窗口為例如果項(xiàng)目代碼本身已經(jīng)占用了 60k那留給 skills 的空間大概只有 60k 左右。我的經(jīng)驗(yàn)是單個(gè) skill 的上下文控制在 2k 到 5k token 之間超過這個(gè)范圍就要考慮拆分。具體怎么估算一個(gè)英文單詞大約 1.3 個(gè) token一個(gè)中文字大約 1.5 到 2 個(gè) token。你可以把context.md和examples.md的內(nèi)容復(fù)制到 token 計(jì)算工具里跑一下。如果發(fā)現(xiàn)某個(gè) skill 太大就把它拆成多個(gè)小 skill按更細(xì)的場景觸發(fā)。比如“API 生成規(guī)范”可以拆成“路由規(guī)范”“校驗(yàn)規(guī)范”“返回值規(guī)范”三個(gè)獨(dú)立 skill按需組合。4.4 實(shí)操現(xiàn)場記錄一次完整的 skill 加載與調(diào)試我第一次配置 skills 的時(shí)候遇到一個(gè)很典型的問題skill 加載了但助手好像“看不見”里面的約束。排查了半天發(fā)現(xiàn)是觸發(fā)條件寫錯(cuò)了——我把include寫成了src/routes/*.ts但實(shí)際文件在src/routes/v1/*.ts通配符沒匹配上。改成src/routes/**/*.ts之后就正常了。另一次是上下文內(nèi)容太長導(dǎo)致助手在生成代碼時(shí)“忘記”了前面的約束。后來我把context.md精簡到 1.5k token 以內(nèi)只保留最關(guān)鍵的幾條問題就解決了。這讓我意識到skills 的效果不取決于你寫了多少而取決于模型能記住多少。與其堆砌規(guī)范不如把最重要的幾條放在最前面并用加粗或列表突出。還有一個(gè)坑是編碼問題。有些工具對非 ASCII 字符支持不好中文內(nèi)容偶爾會(huì)出現(xiàn)亂碼。我的做法是盡量用英文寫 skill 的元數(shù)據(jù)和觸發(fā)條件上下文內(nèi)容可以用中文但保存時(shí)確保是 UTF-8 編碼。5. 常見問題與排查技巧實(shí)錄踩過的坑和解決方案5.1 常見問題速查表問題現(xiàn)象可能原因排查方法解決方案skill 不生效觸發(fā)條件不匹配檢查文件路徑和通配符調(diào)整 include/exclude 規(guī)則助手忽略約束上下文太長或太靠后查看 token 占用和內(nèi)容順序精簡內(nèi)容關(guān)鍵約束前置加載報(bào)錯(cuò)配置文件格式錯(cuò)誤檢查 JSON 語法和編碼用 JSON 校驗(yàn)工具驗(yàn)證多個(gè) skill 沖突觸發(fā)條件重疊查看加載日志調(diào)整觸發(fā)范圍或設(shè)置優(yōu)先級中文亂碼編碼不一致檢查文件編碼統(tǒng)一保存為 UTF-8熱加載不生效工具不支持查看版本文檔重啟會(huì)話或升級版本5.2 獨(dú)家避坑技巧從實(shí)際項(xiàng)目中總結(jié)的幾條經(jīng)驗(yàn)第一條不要把所有規(guī)范都塞進(jìn)一個(gè) skill。我見過有人把整個(gè)團(tuán)隊(duì)的編碼規(guī)范寫成一個(gè) 10k token 的 skill結(jié)果模型根本記不住輸出質(zhì)量反而下降。正確的做法是按場景拆分每個(gè) skill 只解決一個(gè)具體問題。第二條觸發(fā)條件寧窄勿寬。寬泛的觸發(fā)條件會(huì)導(dǎo)致 skill 在不該加載的時(shí)候加載干擾正常輸出。比如“所有 TypeScript 文件”這種條件基本等于全局加載效果很差。建議精確到目錄或文件名模式。第三條定期清理不再使用的 skill。項(xiàng)目在演進(jìn)規(guī)范也在變。過時(shí)的 skill 不僅占用空間還可能和新的規(guī)范沖突。我一般每個(gè)月檢查一次把半年沒用的 skill 歸檔或刪除。第四條用版本控制管理 skills。把 skills 目錄納入 git 管理這樣團(tuán)隊(duì)成員可以共享同一套配置出了問題也能回滾。我還會(huì)在 commit message 里寫清楚這次改了什么、為什么改方便追溯。第五條不要依賴 skills 做代碼審查。skills 是輔助生成的不是替代審查的。模型生成的代碼仍然需要人工檢查尤其是安全相關(guān)的邏輯。我見過有人完全信任 skill 生成的代碼結(jié)果引入了一個(gè) SQL 注入漏洞。這個(gè)教訓(xùn)很深刻。5.3 性能優(yōu)化讓 skills 加載更快、更準(zhǔn)如果你配置了很多 skills可能會(huì)發(fā)現(xiàn)助手啟動(dòng)變慢或者響應(yīng)時(shí)間變長。這通常是因?yàn)榧虞d邏輯在每次會(huì)話開始時(shí)掃描了所有 skill 文件。優(yōu)化方法有幾個(gè)一是把不常用的 skill 設(shè)為手動(dòng)加載不參與自動(dòng)掃描二是把 skill 文件放在 SSD 上減少 IO 延遲三是定期合并重復(fù)的 skill減少文件數(shù)量。另外有些工具支持 skill 的懶加載也就是只有在觸發(fā)條件滿足時(shí)才讀取文件內(nèi)容。如果你的工具支持這個(gè)特性一定要打開。實(shí)測下來懶加載能把啟動(dòng)時(shí)間縮短一半以上。6. 進(jìn)階玩法把 skills 接入團(tuán)隊(duì)工作流6.1 團(tuán)隊(duì)共享用 git 子模塊或包管理器分發(fā)一個(gè)人用 skills 和團(tuán)隊(duì)用 skills 是兩回事。個(gè)人用的時(shí)候配置放在本地就行團(tuán)隊(duì)用的時(shí)候需要一套分發(fā)機(jī)制。我試過兩種方案一種是 git 子模塊把 skills 倉庫作為子模塊掛到每個(gè)項(xiàng)目里另一種是內(nèi)部 npm 包把 skills 打包發(fā)布通過npm install安裝。git 子模塊的好處是版本鎖定明確每個(gè)項(xiàng)目可以用不同版本的 skills缺點(diǎn)是更新麻煩需要手動(dòng)拉取。npm 包的好處是安裝和更新方便缺點(diǎn)是所有項(xiàng)目共用同一版本不夠靈活。我們最后選了混合方案通用規(guī)范做成 npm 包項(xiàng)目特有的規(guī)范放在項(xiàng)目倉庫的.skills/目錄里。6.2 與 CI/CD 結(jié)合在流水線里校驗(yàn) skills 輸出skills 生成的代碼最終要進(jìn)入代碼庫所以可以在 CI 流水線里加一道校驗(yàn)。比如用 ESLint 檢查生成代碼的風(fēng)格用單元測試檢查功能正確性用安全掃描檢查潛在漏洞。如果校驗(yàn)不通過就阻止合并并提示開發(fā)者檢查 skills 配置。我還在流水線里加了一個(gè)步驟統(tǒng)計(jì) skills 的觸發(fā)次數(shù)和生成代碼的通過率。如果某個(gè) skill 的通過率持續(xù)偏低就說明它的上下文內(nèi)容需要優(yōu)化。這個(gè)數(shù)據(jù)驅(qū)動(dòng)的方法比憑感覺調(diào)整要靠譜得多。6.3 未來擴(kuò)展skills 與多模型切換現(xiàn)在很多團(tuán)隊(duì)不只用一種模型可能會(huì)根據(jù)任務(wù)類型切換 Claude、GPT 或其他模型。skills 的設(shè)計(jì)最好能兼容多模型也就是把上下文內(nèi)容和模型調(diào)用解耦。我的做法是把 skill 定義成純文本加元數(shù)據(jù)不綁定具體模型然后在加載層根據(jù)當(dāng)前模型做適配比如調(diào)整提示詞格式或 token 預(yù)算。這樣做的另一個(gè)好處是當(dāng)新模型出現(xiàn)時(shí)不需要重寫 skills只需要在加載層做兼容即可。我試過把同一套 skills 從 Claude 切到另一個(gè)模型上只改了加載配置上下文內(nèi)容基本沒動(dòng)效果也能接受。7. 我個(gè)人在實(shí)際操作中的體會(huì)折騰 skills 這套東西大概有大半年了最大的感受是它不是一個(gè)“配好就完事”的工具而是一個(gè)需要持續(xù)迭代的工作流。項(xiàng)目在變規(guī)范在變模型也在變skills 必須跟著變。我現(xiàn)在的習(xí)慣是每次項(xiàng)目復(fù)盤的時(shí)候順便看一眼 skills 的使用情況把過時(shí)的刪掉把新出現(xiàn)的痛點(diǎn)補(bǔ)上。另一個(gè)體會(huì)是不要追求“全自動(dòng)”。skills 能幫你省掉很多重復(fù)勞動(dòng)但它不能替代你的判斷。該審查的代碼還是要審查該寫的測試還是要寫。把 skills 當(dāng)成一個(gè)靠譜的助手而不是一個(gè)全能的替身心態(tài)會(huì)好很多。最后分享一個(gè)小技巧如果你不確定某個(gè) skill 該怎么寫就去社區(qū)里找現(xiàn)成的拆開看它的結(jié)構(gòu)和措辭。我最早就是靠模仿別人的 skill 文件入門的改著改著就摸清套路了?，F(xiàn)在社區(qū)里針對前端、后端、數(shù)據(jù)、運(yùn)維等場景的 skills 都很豐富拿來改比從零寫快得多。