一配置實(shí)戰(zhàn))
最近一直在折騰多Agent的工作流最大的感受是工具越用越多配置越來(lái)越散。Claude Code里配了一套Skills換個(gè)Codex又要重新建一套同一個(gè)任務(wù)在兩個(gè)Agent里表現(xiàn)還不一樣維護(hù)成本直接翻倍。今天想聊的就是怎么把Claude Code和Codex的Skills收編成一套一處維護(hù)、兩邊生效順便把我踩過(guò)的坑和最終落地的方案一起整理出來(lái)。這篇文章適合誰(shuí)看一是已經(jīng)用Claude Code或Codex寫過(guò)自動(dòng)化任務(wù)的開(kāi)發(fā)者二是團(tuán)隊(duì)里多人共用Agent、想讓技能庫(kù)標(biāo)準(zhǔn)化的人三是剛聽(tīng)說(shuō)Skills但被各種零散教程繞暈的新手。內(nèi)容會(huì)從機(jī)制原理講到目錄設(shè)計(jì)再到可直接抄的代碼和腳本最后是問(wèn)題排查盡量讓不同基礎(chǔ)的人都能跟著搭起來(lái)。1. 為什么需要一套Skills多Agent共享1.1 Skills到底是什么為什么Agent越來(lái)越依賴它先說(shuō)清楚Skills這個(gè)概念的定位。它本質(zhì)上是一種“可復(fù)用的技能包”里面放一個(gè)Markdown格式的說(shuō)明文件告訴AI模型“在什么場(chǎng)景下、按什么步驟、用什么工具來(lái)完成一類任務(wù)”。比如你寫一個(gè)“前端組件生成”Skill模型遇到“幫我寫一個(gè)帶搜索功能的表格組件”時(shí)就會(huì)自動(dòng)加載這個(gè)技能包的規(guī)范而不是臨時(shí)憑感覺(jué)生成代碼。這個(gè)機(jī)制比單純?cè)趯?duì)話里寫提示詞強(qiáng)在哪提示詞是一次性的換個(gè)會(huì)話就丟了Skills是持久化的只要放在固定目錄里每次啟動(dòng)Agent都能讀到。而且Skills可以把一套復(fù)雜的操作流程拆成步驟、模板、腳本和檢查清單讓模型輸出更穩(wěn)定、更符合團(tuán)隊(duì)規(guī)范。我自己試下來(lái)的感受是沒(méi)有Skills的時(shí)候Agent像是個(gè)聰明但不熟悉業(yè)務(wù)的新人每次都要重新交代規(guī)矩配好Skills之后它才真正像“老員工”。Claude Code和Codex這兩款工具都在往這個(gè)方向發(fā)力。Claude Code會(huì)把Skills放在用戶級(jí)或項(xiàng)目級(jí)目錄里Codex也支持類似的技能包機(jī)制。但問(wèn)題在于兩邊讀的目錄不一樣支持的文件字段也有細(xì)微差別很多人就在這里開(kāi)始重復(fù)造輪子了。1.2 各自獨(dú)立配置的痛點(diǎn)在哪里一開(kāi)始我也走的是“各配各”的老路在~/.claude/skills里放了一套常用的代碼審查、前端開(kāi)發(fā)、數(shù)據(jù)庫(kù)優(yōu)化技能又在~/.codex/skills里復(fù)制了一份。表面上看起來(lái)很穩(wěn)妥實(shí)際用起來(lái)全是問(wèn)題。第一個(gè)痛點(diǎn)是內(nèi)容漂移。同一份“代碼審查清單”我在Claude Code這邊改了三條規(guī)則Codex那邊還是舊的。等到某次Codex審查結(jié)果和Claude Code對(duì)不上我才發(fā)現(xiàn)兩份配置早就分叉了。第二個(gè)痛點(diǎn)是維護(hù)成本翻倍。每次新增一個(gè)Skill至少要寫兩遍、放兩個(gè)目錄、記兩種命名規(guī)范。如果團(tuán)隊(duì)里有五個(gè)人每個(gè)人再各自維護(hù)自己的副本那配置散落程度簡(jiǎn)直無(wú)法收拾。第三個(gè)痛點(diǎn)是體驗(yàn)不一致。同一個(gè)任務(wù)在兩邊觸發(fā)效果不一樣調(diào)試的時(shí)候還得先搞清楚“這次是哪個(gè)Agent在處理”非常心累。所以“一套Skills多個(gè)Agent共享”不只是一個(gè)偷懶技巧而是一個(gè)真正值得認(rèn)真設(shè)計(jì)的基礎(chǔ)設(shè)施問(wèn)題。目標(biāo)很明確單一來(lái)源、同步生效、可版本管理、可團(tuán)隊(duì)共享。1.3 統(tǒng)一管理的目標(biāo)與適用場(chǎng)景統(tǒng)一管理的核心思路是建立一個(gè)“技能單一來(lái)源倉(cāng)庫(kù)”Single Source of Truth然后用符號(hào)鏈接或同步腳本把同一份技能包暴露給不同Agent各自約定的讀取目錄。這樣你只需要維護(hù)一份內(nèi)容Claude Code和Codex都能讀到并且永遠(yuǎn)保持版本一致。這個(gè)方法不只適用于Claude Code和Codex也適用于任何支持“目錄Markdown技能包”機(jī)制的Agent工具比如一些基于開(kāi)源框架自建的Agent服務(wù)。適合的場(chǎng)景包括個(gè)人開(kāi)發(fā)者同時(shí)在多個(gè)命令行Agent之間切換團(tuán)隊(duì)把技能庫(kù)放在Git倉(cāng)庫(kù)里統(tǒng)一評(píng)審和分發(fā)需要在CI里批量校驗(yàn)技能包格式的工程化團(tuán)隊(duì)。如果你只是偶爾用一下Agent不寫復(fù)雜技能包那這個(gè)方案確實(shí)有點(diǎn)重。但只要你的Skill數(shù)量超過(guò)三五個(gè)或者你身邊有不止一個(gè)人在維護(hù)Agent配置這套方案省下的時(shí)間絕對(duì)值回票價(jià)。2. Skills機(jī)制原理與跨Agent兼容設(shè)計(jì)2.1 Claude Code的Skills機(jī)制Claude Code對(duì)Skills的支持核心就是一個(gè)目錄約定它會(huì)在用戶級(jí)目錄~/.claude/skills/和項(xiàng)目級(jí)目錄.claude/skills/下掃描子目錄每個(gè)子目錄代表一個(gè)Skill里面必須有一個(gè)SKILL.md作為入口文件。這個(gè)文件用Markdown寫成頂部帶一段YAML frontmatter用來(lái)聲明技能名稱、描述等元信息正文則是具體的操作說(shuō)明。運(yùn)行時(shí)Claude Code會(huì)把前端輸入的描述信息交給模型做語(yǔ)義匹配一旦模型判斷當(dāng)前任務(wù)命中某個(gè)Skill就會(huì)把對(duì)應(yīng)的SKILL.md內(nèi)容注入上下文并允許該技能通過(guò)工具讀取同目錄下的附加資源文件比如模板、腳本、檢查清單。這里最關(guān)鍵的一點(diǎn)是模型依賴“description”來(lái)判斷什么時(shí)候該用這個(gè)技能。如果你的description寫得太泛模型就會(huì)“想用又不敢用”寫得太窄就漏匹配。另外Claude Code還有/skills命令可以查看當(dāng)前環(huán)境里已加載的技能列表調(diào)試時(shí)可以先用這個(gè)命令確認(rèn)技能有沒(méi)有被正確掃描到。這個(gè)命令我?guī)缀趺看握{(diào)Skills都會(huì)用比盲猜高效很多。2.2 Codex的Skills機(jī)制Codex對(duì)Skills的支持思路和Claude Code基本一致也是“目錄 SKILL.md”的格式常見(jiàn)的掃描路徑包括用戶級(jí)目錄~/.codex/skills/和項(xiàng)目級(jí)目錄.codex/skills/。你同樣需要給每個(gè)技能包建一個(gè)獨(dú)立目錄在SKILL.md里寫frontmatter和正文。不過(guò)兩者有個(gè)很實(shí)際的差異Codex對(duì)SKILL.md的字段解析沒(méi)有Claude Code那么豐富。Claude Code可以識(shí)別name、description、allowed-tools、license等字段Codex則更強(qiáng)調(diào)基本的name和description?？绻ぞ吖蚕頃r(shí)如果你在frontmatter里塞了大量Claude私有字段Codex大概率會(huì)忽略它但這不會(huì)報(bào)錯(cuò)只會(huì)導(dǎo)致技能行為不符合預(yù)期。還有一個(gè)差異是上下文組織方式。Codex比較依賴AGENTS.md這類項(xiàng)目規(guī)則文件來(lái)約束全局行為Skills更多承擔(dān)“特定任務(wù)專用流程”的角色。也就是說(shuō)在Codex里Skills和項(xiàng)目規(guī)則是互補(bǔ)關(guān)系而不是替代關(guān)系。這一點(diǎn)在多Agent共享時(shí)要留意Skills負(fù)責(zé)“怎么做某類任務(wù)”AGENTS.md或項(xiàng)目配置負(fù)責(zé)“整個(gè)項(xiàng)目的整體約束”。2.3 兩個(gè)體系之間的差異與兼容點(diǎn)把兩邊的機(jī)制放在一起對(duì)比能清楚看到兼容性的邊界在哪里。我整理了一張表對(duì)比項(xiàng)Claude CodeCodex用戶級(jí)Skills目錄~/.claude/skills/~/.codex/skills/項(xiàng)目級(jí)Skills目錄.claude/skills/.codex/skills/技能入口文件SKILL.mdSKILL.mdfrontmatter公共字段name、description等name、description等高級(jí)私有字段allowed-tools、license、version解析策略保守可能忽略技能加載命令/skills通過(guò)CLI日志或調(diào)試輸出查看從表里可以看出兩邊的兼容基礎(chǔ)就是“目錄 SKILL.md name/description公共字段”。所以統(tǒng)一管理方案的設(shè)計(jì)原則就清晰了frontmatter只寫公共字段復(fù)雜約束寫進(jìn)正文和附加文件里。這樣Claude Code能完整解析Codex也不會(huì)因?yàn)槲粗侄纬霈F(xiàn)奇怪行為。3. 統(tǒng)一Skills倉(cāng)庫(kù)的目錄設(shè)計(jì)與文件規(guī)范3.1 倉(cāng)庫(kù)根目錄結(jié)構(gòu)一個(gè)理想的統(tǒng)一Skills倉(cāng)庫(kù)應(yīng)該從根目錄開(kāi)始就是自解釋的。我的推薦結(jié)構(gòu)是這樣~/ai-skills/ ├── README.md ├── sync.sh ├── sync.ps1 ├── lint.sh └── skills/ ├── code-review/ │ ├── SKILL.md │ ├── checklist.md │ └── scripts/ │ └── extract_diff.py ├── frontend-component/ │ ├── SKILL.md │ ├── templates/ │ │ └── component.tsx │ └── examples/ │ └── sample.md └── db-optimization/ ├── SKILL.md └── references/ └── index-patterns.md根目錄的README.md不是擺設(shè)要寫清楚這個(gè)倉(cāng)庫(kù)是什么、包含哪些技能、如何安裝、如何新增技能。sync.sh和sync.ps1分別是macOS/Linux和Windows下的同步腳本負(fù)責(zé)把skills/下所有技能包鏈接到Claude Code和Codex的目錄。lint.sh用來(lái)統(tǒng)一校驗(yàn)SKILL.md格式CI或本地提交前跑一遍。skills/目錄下每個(gè)子文件夾就是一個(gè)技能包。技能包命名我建議一律用小寫字母加連字符比如code-review、frontend-component不要用空格、中文或駝峰。原因很簡(jiǎn)單目錄名可能出現(xiàn)在文件路徑、腳本變量和日志里越是簡(jiǎn)單通用的命名越不容易踩坑。3.2 SKILL.md的frontmatter怎么寫SKILL.md的frontmatter是整個(gè)技能包的核心因?yàn)锳gent主要靠它來(lái)判斷“何時(shí)觸發(fā)”和“基本信息”。為了兼顧C(jī)laude Code和Codex我推薦只使用公共基礎(chǔ)字段--- name: frontend-component description: 當(dāng)用戶需要生成或修改前端React組件、頁(yè)面、樣式文件時(shí)使用。包含組件模板、樣式規(guī)范、測(cè)試文件生成等場(chǎng)景。 ---name字段是技能包的唯一標(biāo)識(shí)最好和目錄名保持一致。description字段是最關(guān)鍵的部分它直接決定模型能不能在合適的時(shí)機(jī)激活這個(gè)技能。寫description時(shí)要注意寫場(chǎng)景不寫功能說(shuō)明書。不要寫“這是一個(gè)前端組件生成技能支持XXX功能”而要寫“當(dāng)用戶需要……時(shí)使用適用于……場(chǎng)景”。如果你需要給某個(gè)技能加版本號(hào)、作者或許可證建議放在附加文件里比如在技能包目錄里建一個(gè)meta.yaml而不是塞進(jìn)SKILL.md的frontmatter。原因我前面講過(guò)Codex對(duì)未知字段的處理比較保守與其賭工具兼容性不如在結(jié)構(gòu)上徹底繞開(kāi)。3.3 描述信息與觸發(fā)匹配的優(yōu)化技巧description的寫法值得單獨(dú)拿出來(lái)說(shuō)因?yàn)檫@是“同樣的技能包在不同Agent里表現(xiàn)差異最大”的地方。我踩過(guò)最典型的坑是把description寫成了功能清單比如“支持代碼審查、支持漏洞掃描、支持性能評(píng)估”結(jié)果Claude Code很容易誤觸發(fā)而Codex又經(jīng)常漏觸發(fā)。后來(lái)我總結(jié)出一套寫法場(chǎng)景前置 需求樣例 邊界說(shuō)明。場(chǎng)景前置就是開(kāi)頭直接說(shuō)“當(dāng)用戶需要……時(shí)”需求樣例就是列舉幾種用戶可能的說(shuō)法幫助模型建立聯(lián)想邊界說(shuō)明就是誠(chéng)實(shí)交代“不要用這個(gè)技能處理哪些情況”避免過(guò)度觸發(fā)。舉個(gè)例子同樣是“數(shù)據(jù)庫(kù)優(yōu)化”技能低質(zhì)量的description可能是“數(shù)據(jù)庫(kù)優(yōu)化工具包”合格的description大概是description: 當(dāng)用戶需要分析SQL慢查詢、優(yōu)化索引結(jié)構(gòu)、設(shè)計(jì)數(shù)據(jù)庫(kù)表或排查查詢性能問(wèn)題時(shí)使用。典型說(shuō)法包括“幫我看看這條SQL為什么慢”“這個(gè)表要不要加索引”“數(shù)據(jù)庫(kù)查詢很卡”。這樣的description既給了觸發(fā)詞又給了“為什么”和“什么時(shí)候不該用”的邊界。模型在語(yǔ)義匹配時(shí)參考信息越多命中率越高。4. 落地實(shí)操?gòu)牧愦罱ü蚕鞸kills方案4.1 初始化統(tǒng)一Skills倉(cāng)庫(kù)下面是一套可以直接照著做的步驟我默認(rèn)你已經(jīng)裝好了Claude Code和Codex CLI且系統(tǒng)是macOS或Linux。Windows用戶的差異我會(huì)在后面單獨(dú)說(shuō)。第一步創(chuàng)建倉(cāng)庫(kù)目錄和基本結(jié)構(gòu)mkdir -p ~/ai-skills/skills cd ~/ai-skills git init第二步創(chuàng)建根目錄README簡(jiǎn)單說(shuō)明倉(cāng)庫(kù)用途和用法順手把目錄結(jié)構(gòu)畫進(jìn)去。這一步不是形式主義團(tuán)隊(duì)協(xié)作時(shí)它能幫新成員三分鐘上手。第三步創(chuàng)建你的第一個(gè)技能包目錄并編寫SKILL.md。以“前端組件生成”技能為例mkdir -p skills/frontend-component/templates在skills/frontend-component/SKILL.md里寫入--- name: frontend-component description: 當(dāng)用戶需要生成或修改前端React組件、頁(yè)面、樣式文件時(shí)使用。典型訴求包括“寫一個(gè)表格組件”“加一個(gè)篩選器”“把這個(gè)彈窗改成受控組件”。 --- # 前端組件生成 ## 適用場(chǎng)景 - 根據(jù)需求描述生成新的React組件 - 修改已有組件的結(jié)構(gòu)、樣式或交互邏輯 - 生成配套的樣式文件和基礎(chǔ)測(cè)試 ## 執(zhí)行步驟 1. 確認(rèn)組件類型是展示組件還是容器組件是否需要狀態(tài)管理。 2. 檢查項(xiàng)目里是否已有類似組件避免重復(fù)實(shí)現(xiàn)。 3. 按照模板生成組件代碼入口組件放在 templates/component.tsx。 4. 生成樣式文件命名與組件保持一致。 5. 生成基礎(chǔ)測(cè)試文件覆蓋默認(rèn)渲染和核心交互。 ## 輸出要求 - 組件代碼必須使用TypeScript。 - 樣式文件使用CSS Modules。 - 如果需求不明確先列出問(wèn)題清單不要擅自假設(shè)。第四步提交初始版本git add . git commit -m init: add frontend-component skill到這里統(tǒng)一倉(cāng)庫(kù)的雛形就有了。后面所有的新技能都按照同樣的結(jié)構(gòu)往里加保持“一個(gè)技能包一個(gè)目錄目錄內(nèi)必有SKILL.md”這條鐵律。4.2 用符號(hào)鏈接打通Claude Code與Codex倉(cāng)庫(kù)建好之后關(guān)鍵的一步是讓Claude Code和Codex都能讀到同一份技能包。我沒(méi)有選擇“復(fù)制文件過(guò)去”而是用符號(hào)鏈接symlink。原因很簡(jiǎn)單符號(hào)鏈接不復(fù)制內(nèi)容只創(chuàng)建一個(gè)引用路徑。你改了源文件兩邊立即生效徹底解決內(nèi)容漂移問(wèn)題。在macOS或Linux下先確保兩邊的skills目錄存在然后逐個(gè)建立鏈接mkdir -p ~/.claude/skills mkdir -p ~/.codex/skills ln -sfn ~/ai-skills/skills/frontend-component ~/.claude/skills/frontend-component ln -sfn ~/ai-skills/skills/frontend-component ~/.codex/skills/frontend-component如果技能很多逐個(gè)敲太累直接用通配符循環(huán)for skill in ~/ai-skills/skills/*/; do name$(basename $skill) ln -sfn $skill ~/.claude/skills/$name ln -sfn $skill ~/.codex/skills/$name done注意ln -sfn里的-n參數(shù)很關(guān)鍵它表示把目標(biāo)當(dāng)作目錄處理防止在已存在同名符號(hào)鏈接時(shí)出現(xiàn)嵌套鏈接的詭異問(wèn)題。我在這上面吃過(guò)虧不加-n會(huì)導(dǎo)致鏈接套鏈接最終Agent掃不到技能。建立鏈接之后可以用下面的命令驗(yàn)證ls -l ~/.claude/skills/ ls -l ~/.codex/skills/如果看到類似frontend-component - /Users/yourname/ai-skills/skills/frontend-component的輸出說(shuō)明鏈接建立成功。注意檢查鏈接目標(biāo)是否存在如果源目錄被移動(dòng)或刪除鏈接會(huì)變成“斷鏈”Agent會(huì)靜默跳過(guò)不會(huì)報(bào)錯(cuò)。4.3 一鍵同步腳本與Git版本管理手工每個(gè)技能敲一次鏈接還是不夠工程化所以我把同步邏輯寫成了一個(gè)腳本統(tǒng)一倉(cāng)庫(kù)里長(zhǎng)期維護(hù)。下面是一個(gè)macOS/Linux的sync.sh版本#!/usr/bin/env bash set -euo pipefail SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) SKILLS_SOURCE$SCRIPT_DIR/skills TARGETS( $HOME/.claude/skills $HOME/.codex/skills ) FAILED0 for target in ${TARGETS[]}; do mkdir -p $target for skill in $SKILLS_SOURCE/*/; do name$(basename $skill) ln -sfn $skill $target/$name echo linked: $name - $target/$name done done if [ $FAILED -ne 0 ]; then echo sync finished with errors exit 1 fi echo sync complete這里用set -euo pipefail防止腳本在中間出錯(cuò)時(shí)繼續(xù)往下跑保證失敗時(shí)能注意到。每次新增技能包后只需要運(yùn)行一次chmod x sync.sh ./sync.shWindows用戶可以用PowerShell腳本$source Join-Path $PSScriptRoot skills $targets ( (Join-Path $HOME .claude\skills), (Join-Path $HOME .codex\skills) ) foreach ($target in $targets) { New-Item -ItemType Directory -Force -Path $target | Out-Null Get-ChildItem -Path $source -Directory | ForEach-Object { $link Join-Path $target $_.Name if (Test-Path $link) { Remove-Item $link -Force } New-Item -ItemType Junction -Path $link -Target $_.FullName | Out-Null Write-Host linked: $($_.Name) - $link } } Write-Host sync complete然后是Git版本管理。我堅(jiān)持把每個(gè)技能包作為獨(dú)立提交提交信息寫清楚“新增了哪個(gè)技能、為什么要加”。如果要發(fā)版可以給倉(cāng)庫(kù)打tag比如v1.0.0。團(tuán)隊(duì)協(xié)作時(shí)成員拉取倉(cāng)庫(kù)后執(zhí)行一次./sync.sh所有技能就都到位了。想再進(jìn)一步可以在倉(cāng)庫(kù)里加一個(gè)lint.sh用腳本校驗(yàn)所有SKILL.md是否包含name和description字段#!/usr/bin/env bash set -euo pipefail for file in skills/*/SKILL.md; do if ! grep -q ^name: $file; then echo missing name in $file exit 1 fi if ! grep -q ^description: $file; then echo missing description in $file exit 1 fi echo ok: $file done這個(gè)腳本放在pre-commit鉤子里每次提交前自動(dòng)跑一遍能攔截掉大量低級(jí)錯(cuò)誤。4.4 在項(xiàng)目中啟用與驗(yàn)證鏈接建好之后不用重啟終端新開(kāi)一個(gè)Claude Code會(huì)話輸入/skills如果能看到frontend-component等技能名說(shuō)明掃描成功。Codex這邊可以運(yùn)行codex進(jìn)入交互模式然后直接問(wèn)一個(gè)和技能描述吻合的問(wèn)題比如“幫我生成一個(gè)帶搜索功能的表格組件”觀察它是否加載了對(duì)應(yīng)技能。如果項(xiàng)目要求“技能只在特定倉(cāng)庫(kù)里生效”而不是全局生效可以把符號(hào)鏈接放到項(xiàng)目級(jí)目錄也就是在項(xiàng)目根目錄下建.claude/skills和.codex/skills同樣是指向統(tǒng)一倉(cāng)庫(kù)里的技能目錄。這種方式更適合多項(xiàng)目多規(guī)則的團(tuán)隊(duì)因?yàn)椴煌?xiàng)目可以按需啟用不同技能集。有一點(diǎn)要提醒項(xiàng)目級(jí)目錄默認(rèn)會(huì)被Git追蹤所以要么把.claude/skills和.codex/skills加入.gitignore要么讓團(tuán)隊(duì)成員各自執(zhí)行同步腳本。我個(gè)人建議把這兩個(gè)目錄加入.gitignore因?yàn)榧寄馨恼嬲搭^是統(tǒng)一倉(cāng)庫(kù)項(xiàng)目里不應(yīng)該再存一份副本。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 Skill沒(méi)有被識(shí)別這是最常遇到的問(wèn)題。技能明明放進(jìn)目錄了Agent卻視而不見(jiàn)。我的排查順序是這樣的第一檢查目錄層級(jí)。SKILL.md必須放在skills/skill-name/下不能直接放在skills/里也不能多包一層。比如skills/code-review/SKILL.md是對(duì)的skills/code-review/skill/SKILL.md是錯(cuò)的。第二檢查frontmatter。用head -5 SKILL.md看一眼確認(rèn)第一行是---緊接著是name和description字段然后再以---結(jié)束。缺失任何一段解析器都會(huì)跳過(guò)整個(gè)文件。第三檢查鏈接是否健康。如果用了符號(hào)鏈接執(zhí)行l(wèi)s -l看鏈接指向是否存在如果指向的目錄被移動(dòng)過(guò)鏈接就會(huì)斷掉Agent會(huì)靜默忽略。此時(shí)重新運(yùn)行同步腳本即可。第四檢查用戶級(jí)目錄是否拼寫正確。Claude Code用戶級(jí)目錄是小寫.claudeCodex是小寫.codex大小寫敏感系統(tǒng)上寫錯(cuò)了就完全掃不到。5.2 描述觸發(fā)不準(zhǔn)技能能被識(shí)別但該觸發(fā)時(shí)不觸發(fā)不該觸發(fā)時(shí)亂觸發(fā)八成是description寫得有問(wèn)題。我之前寫過(guò)一個(gè)“代碼審查”技能的description“代碼審查工具”結(jié)果給Agent說(shuō)“幫我看看這段代碼”的時(shí)候它不觸發(fā)說(shuō)“生成代碼審查報(bào)告”的時(shí)候反而偶爾觸發(fā)。后來(lái)我把description改成了場(chǎng)景化描述“當(dāng)用戶需要檢查代碼質(zhì)量、發(fā)現(xiàn)潛在bug、評(píng)審Pull Request或生成代碼審查意見(jiàn)時(shí)使用。典型說(shuō)法包括‘幫我review一下這段代碼’‘這個(gè)PR有沒(méi)有問(wèn)題’。”改完之后觸發(fā)率明顯提升。如果發(fā)現(xiàn)觸發(fā)過(guò)于頻繁就加一句“僅適用于……場(chǎng)景”明確邊界。還有一個(gè)經(jīng)驗(yàn)是description不要太長(zhǎng)但也別太短。我一般控制在50到150個(gè)漢字之間既給足語(yǔ)義線索又不至于讓模型在匹配時(shí)被多余信息干擾。5.3 符號(hào)鏈接在Windows下的坑Windows默認(rèn)不允許普通用戶直接創(chuàng)建符號(hào)鏈接除非開(kāi)啟開(kāi)發(fā)者模式或以管理員身份運(yùn)行。我在Windows上試過(guò)New-Item -ItemType SymbolicLink時(shí)報(bào)錯(cuò)后來(lái)?yè)Q成Junction類型就順利了。Junction和SymbolicLink的區(qū)別在于Junction只支持目錄且不需要管理員權(quán)限在部分配置下對(duì)于技能包這種純目錄場(chǎng)景完全夠用。PowerShell腳本里用-ItemType Junction就是基于這個(gè)原因。另外Windows下不要用Remove-Item刪除鏈接指向的源目錄它可能遞歸刪除真正的文件這一點(diǎn)要格外小心刪鏈接時(shí)用Remove-Item $link只刪鏈接本身。5.4 Agent執(zhí)行中斷或權(quán)限錯(cuò)誤有時(shí)候Agent能識(shí)別技能但執(zhí)行過(guò)程中報(bào)“agent execution terminated due to error”或者提示命令找不到、文件讀取失敗。我的排查經(jīng)驗(yàn)是確認(rèn)技能包里引用的腳本是否有執(zhí)行權(quán)限。如果SKILL.md里讓模型運(yùn)行scripts/xxx.py請(qǐng)先手動(dòng)執(zhí)行一遍python3 skills/xxx/scripts/xxx.py --help確認(rèn)無(wú)誤再讓Agent調(diào)用。確認(rèn)技能包內(nèi)文件的路徑描述使用相對(duì)路徑并且以技能包目錄為基準(zhǔn)。比如模板文件寫templates/component.tsx不要寫絕對(duì)路徑因?yàn)椴煌瑱C(jī)器上倉(cāng)庫(kù)路徑不一樣。確認(rèn)Agent的工作目錄權(quán)限。有些工具會(huì)限制只能訪問(wèn)項(xiàng)目目錄內(nèi)的文件如果技能文件在用戶主目錄深處可能會(huì)因?yàn)槁窂皆綑?quán)而失敗。我還遇到過(guò)因?yàn)榧寄苣_本里依賴的Python包沒(méi)裝導(dǎo)致的報(bào)錯(cuò)。處理辦法是在技能包目錄里放一個(gè)requirements.txt并在SKILL.md里寫明“使用本技能前需要安裝以下依賴”。能提前寫清楚的事情千萬(wàn)不要留給運(yùn)行時(shí)才猜。6. 個(gè)人心得與擴(kuò)展建議6.1 我踩過(guò)的幾個(gè)坑這個(gè)方案我已經(jīng)跑了幾個(gè)月踩過(guò)的坑比想象中多。最值得說(shuō)的是三個(gè)。第一個(gè)是曾經(jīng)把同一個(gè)技能在Claude Code和Codex里各寫了一份兩邊內(nèi)容漸漸不一致后來(lái)排查問(wèn)題時(shí)才發(fā)現(xiàn)某條規(guī)則只在一半的Agent里生效。用統(tǒng)一倉(cāng)庫(kù)加符號(hào)鏈接之后這個(gè)問(wèn)題徹底消失了因?yàn)槲锢砩暇椭挥幸环菸募５诙€(gè)坑是過(guò)度設(shè)計(jì)。一開(kāi)始我把frontmatter塞滿了version、author、allowed-tools等字段還寫了自定義解析邏輯結(jié)果Codex那邊表現(xiàn)很奇怪。后來(lái)老老實(shí)實(shí)只用name和description復(fù)雜邏輯全部寫進(jìn)正文反而兩邊都穩(wěn)定。跨工具場(chǎng)景里克制比炫技重要。第三個(gè)坑是測(cè)試不充分。新增技能后只驗(yàn)證了一個(gè)Agent另一個(gè)沒(méi)測(cè)結(jié)果某次緊急任務(wù)正好走到另一個(gè)Agent上才發(fā)現(xiàn)技能壓根沒(méi)被識(shí)別?，F(xiàn)在我的習(xí)慣是任何技能變更之后兩邊都會(huì)各跑一次最小測(cè)試用例確認(rèn)觸發(fā)、加載、執(zhí)行三個(gè)環(huán)節(jié)都沒(méi)問(wèn)題再提交。6.2 后續(xù)擴(kuò)展團(tuán)隊(duì)共享、模板體系與自動(dòng)化這套方案天然適合往團(tuán)隊(duì)方向擴(kuò)展。你只需要把~/ai-skills換成團(tuán)隊(duì)共用的Git倉(cāng)庫(kù)再約定好命名規(guī)范和提交流程每個(gè)成員本地執(zhí)行一次同步腳本就能獲得完全一致的技能體驗(yàn)。新成員入職時(shí)跑兩條命令就能把整個(gè)技能庫(kù)配好不需要手動(dòng)復(fù)制任何文件。進(jìn)一步的話可以把技能包里的模板做得更豐富比如前端組件技能里放多種組件模板、數(shù)據(jù)庫(kù)技能里放常用的索引設(shè)計(jì)樣例。Skills的價(jià)值會(huì)隨著模板質(zhì)量和覆蓋場(chǎng)景的增加而指數(shù)級(jí)上升。還可以考慮把lint.sh集成到CI里每次合并新技能時(shí)自動(dòng)校驗(yàn)格式。如果你的Agent工具支持MCP也可以把一些外部數(shù)據(jù)源或內(nèi)部接口封裝成MCP服務(wù)把“技能包負(fù)責(zé)流程、MCP負(fù)責(zé)外部連接”結(jié)合起來(lái)?？傊劝选耙惶譙kills多Agent共享”的地基打好后面加什么擴(kuò)展都會(huì)順手很多。我自己在維護(hù)這個(gè)倉(cāng)庫(kù)時(shí)最大的體會(huì)是工具會(huì)變但“單一來(lái)源 自動(dòng)化同步 版本管理”的思路不會(huì)過(guò)時(shí)。哪怕以后我又換了一個(gè)新的Agent工具只需要把它的技能目錄加進(jìn)同步腳本整個(gè)體系就能立刻復(fù)用這才是這套方案真正值錢的地方。 一套Skills多Agent共享：Claude Code與Codex統(tǒng)一配置實(shí)戰(zhàn)
最近一直在折騰多Agent的工作流最大的感受是工具越用越多配置越來(lái)越散。Claude Code里配了一套Skills換個(gè)Codex又要重新建一套同一個(gè)任務(wù)在兩個(gè)Agent里表現(xiàn)還不一樣維護(hù)成本直接翻倍。今天想聊的就是怎么把Claude Code和Codex的Skills收編成一套一處維護(hù)、兩邊生效順便把我踩過(guò)的坑和最終落地的方案一起整理出來(lái)。這篇文章適合誰(shuí)看一是已經(jīng)用Claude Code或Codex寫過(guò)自動(dòng)化任務(wù)的開(kāi)發(fā)者二是團(tuán)隊(duì)里多人共用Agent、想讓技能庫(kù)標(biāo)準(zhǔn)化的人三是剛聽(tīng)說(shuō)Skills但被各種零散教程繞暈的新手。內(nèi)容會(huì)從機(jī)制原理講到目錄設(shè)計(jì)再到可直接抄的代碼和腳本最后是問(wèn)題排查盡量讓不同基礎(chǔ)的人都能跟著搭起來(lái)。1. 為什么需要一套Skills多Agent共享1.1 Skills到底是什么為什么Agent越來(lái)越依賴它先說(shuō)清楚Skills這個(gè)概念的定位。它本質(zhì)上是一種“可復(fù)用的技能包”里面放一個(gè)Markdown格式的說(shuō)明文件告訴AI模型“在什么場(chǎng)景下、按什么步驟、用什么工具來(lái)完成一類任務(wù)”。比如你寫一個(gè)“前端組件生成”Skill模型遇到“幫我寫一個(gè)帶搜索功能的表格組件”時(shí)就會(huì)自動(dòng)加載這個(gè)技能包的規(guī)范而不是臨時(shí)憑感覺(jué)生成代碼。這個(gè)機(jī)制比單純?cè)趯?duì)話里寫提示詞強(qiáng)在哪提示詞是一次性的換個(gè)會(huì)話就丟了Skills是持久化的只要放在固定目錄里每次啟動(dòng)Agent都能讀到。而且Skills可以把一套復(fù)雜的操作流程拆成步驟、模板、腳本和檢查清單讓模型輸出更穩(wěn)定、更符合團(tuán)隊(duì)規(guī)范。我自己試下來(lái)的感受是沒(méi)有Skills的時(shí)候Agent像是個(gè)聰明但不熟悉業(yè)務(wù)的新人每次都要重新交代規(guī)矩配好Skills之后它才真正像“老員工”。Claude Code和Codex這兩款工具都在往這個(gè)方向發(fā)力。Claude Code會(huì)把Skills放在用戶級(jí)或項(xiàng)目級(jí)目錄里Codex也支持類似的技能包機(jī)制。但問(wèn)題在于兩邊讀的目錄不一樣支持的文件字段也有細(xì)微差別很多人就在這里開(kāi)始重復(fù)造輪子了。1.2 各自獨(dú)立配置的痛點(diǎn)在哪里一開(kāi)始我也走的是“各配各”的老路在~/.claude/skills里放了一套常用的代碼審查、前端開(kāi)發(fā)、數(shù)據(jù)庫(kù)優(yōu)化技能又在~/.codex/skills里復(fù)制了一份。表面上看起來(lái)很穩(wěn)妥實(shí)際用起來(lái)全是問(wèn)題。第一個(gè)痛點(diǎn)是內(nèi)容漂移。同一份“代碼審查清單”我在Claude Code這邊改了三條規(guī)則Codex那邊還是舊的。等到某次Codex審查結(jié)果和Claude Code對(duì)不上我才發(fā)現(xiàn)兩份配置早就分叉了。第二個(gè)痛點(diǎn)是維護(hù)成本翻倍。每次新增一個(gè)Skill至少要寫兩遍、放兩個(gè)目錄、記兩種命名規(guī)范。如果團(tuán)隊(duì)里有五個(gè)人每個(gè)人再各自維護(hù)自己的副本那配置散落程度簡(jiǎn)直無(wú)法收拾。第三個(gè)痛點(diǎn)是體驗(yàn)不一致。同一個(gè)任務(wù)在兩邊觸發(fā)效果不一樣調(diào)試的時(shí)候還得先搞清楚“這次是哪個(gè)Agent在處理”非常心累。所以“一套Skills多個(gè)Agent共享”不只是一個(gè)偷懶技巧而是一個(gè)真正值得認(rèn)真設(shè)計(jì)的基礎(chǔ)設(shè)施問(wèn)題。目標(biāo)很明確單一來(lái)源、同步生效、可版本管理、可團(tuán)隊(duì)共享。1.3 統(tǒng)一管理的目標(biāo)與適用場(chǎng)景統(tǒng)一管理的核心思路是建立一個(gè)“技能單一來(lái)源倉(cāng)庫(kù)”Single Source of Truth然后用符號(hào)鏈接或同步腳本把同一份技能包暴露給不同Agent各自約定的讀取目錄。這樣你只需要維護(hù)一份內(nèi)容Claude Code和Codex都能讀到并且永遠(yuǎn)保持版本一致。這個(gè)方法不只適用于Claude Code和Codex也適用于任何支持“目錄Markdown技能包”機(jī)制的Agent工具比如一些基于開(kāi)源框架自建的Agent服務(wù)。適合的場(chǎng)景包括個(gè)人開(kāi)發(fā)者同時(shí)在多個(gè)命令行Agent之間切換團(tuán)隊(duì)把技能庫(kù)放在Git倉(cāng)庫(kù)里統(tǒng)一評(píng)審和分發(fā)需要在CI里批量校驗(yàn)技能包格式的工程化團(tuán)隊(duì)。如果你只是偶爾用一下Agent不寫復(fù)雜技能包那這個(gè)方案確實(shí)有點(diǎn)重。但只要你的Skill數(shù)量超過(guò)三五個(gè)或者你身邊有不止一個(gè)人在維護(hù)Agent配置這套方案省下的時(shí)間絕對(duì)值回票價(jià)。2. Skills機(jī)制原理與跨Agent兼容設(shè)計(jì)2.1 Claude Code的Skills機(jī)制Claude Code對(duì)Skills的支持核心就是一個(gè)目錄約定它會(huì)在用戶級(jí)目錄~/.claude/skills/和項(xiàng)目級(jí)目錄.claude/skills/下掃描子目錄每個(gè)子目錄代表一個(gè)Skill里面必須有一個(gè)SKILL.md作為入口文件。這個(gè)文件用Markdown寫成頂部帶一段YAML frontmatter用來(lái)聲明技能名稱、描述等元信息正文則是具體的操作說(shuō)明。運(yùn)行時(shí)Claude Code會(huì)把前端輸入的描述信息交給模型做語(yǔ)義匹配一旦模型判斷當(dāng)前任務(wù)命中某個(gè)Skill就會(huì)把對(duì)應(yīng)的SKILL.md內(nèi)容注入上下文并允許該技能通過(guò)工具讀取同目錄下的附加資源文件比如模板、腳本、檢查清單。這里最關(guān)鍵的一點(diǎn)是模型依賴“description”來(lái)判斷什么時(shí)候該用這個(gè)技能。如果你的description寫得太泛模型就會(huì)“想用又不敢用”寫得太窄就漏匹配。另外Claude Code還有/skills命令可以查看當(dāng)前環(huán)境里已加載的技能列表調(diào)試時(shí)可以先用這個(gè)命令確認(rèn)技能有沒(méi)有被正確掃描到。這個(gè)命令我?guī)缀趺看握{(diào)Skills都會(huì)用比盲猜高效很多。2.2 Codex的Skills機(jī)制Codex對(duì)Skills的支持思路和Claude Code基本一致也是“目錄 SKILL.md”的格式常見(jiàn)的掃描路徑包括用戶級(jí)目錄~/.codex/skills/和項(xiàng)目級(jí)目錄.codex/skills/。你同樣需要給每個(gè)技能包建一個(gè)獨(dú)立目錄在SKILL.md里寫frontmatter和正文。不過(guò)兩者有個(gè)很實(shí)際的差異Codex對(duì)SKILL.md的字段解析沒(méi)有Claude Code那么豐富。Claude Code可以識(shí)別name、description、allowed-tools、license等字段Codex則更強(qiáng)調(diào)基本的name和description?？绻ぞ吖蚕頃r(shí)如果你在frontmatter里塞了大量Claude私有字段Codex大概率會(huì)忽略它但這不會(huì)報(bào)錯(cuò)只會(huì)導(dǎo)致技能行為不符合預(yù)期。還有一個(gè)差異是上下文組織方式。Codex比較依賴AGENTS.md這類項(xiàng)目規(guī)則文件來(lái)約束全局行為Skills更多承擔(dān)“特定任務(wù)專用流程”的角色。也就是說(shuō)在Codex里Skills和項(xiàng)目規(guī)則是互補(bǔ)關(guān)系而不是替代關(guān)系。這一點(diǎn)在多Agent共享時(shí)要留意Skills負(fù)責(zé)“怎么做某類任務(wù)”AGENTS.md或項(xiàng)目配置負(fù)責(zé)“整個(gè)項(xiàng)目的整體約束”。2.3 兩個(gè)體系之間的差異與兼容點(diǎn)把兩邊的機(jī)制放在一起對(duì)比能清楚看到兼容性的邊界在哪里。我整理了一張表對(duì)比項(xiàng)Claude CodeCodex用戶級(jí)Skills目錄~/.claude/skills/~/.codex/skills/項(xiàng)目級(jí)Skills目錄.claude/skills/.codex/skills/技能入口文件SKILL.mdSKILL.mdfrontmatter公共字段name、description等name、description等高級(jí)私有字段allowed-tools、license、version解析策略保守可能忽略技能加載命令/skills通過(guò)CLI日志或調(diào)試輸出查看從表里可以看出兩邊的兼容基礎(chǔ)就是“目錄 SKILL.md name/description公共字段”。所以統(tǒng)一管理方案的設(shè)計(jì)原則就清晰了frontmatter只寫公共字段復(fù)雜約束寫進(jìn)正文和附加文件里。這樣Claude Code能完整解析Codex也不會(huì)因?yàn)槲粗侄纬霈F(xiàn)奇怪行為。3. 統(tǒng)一Skills倉(cāng)庫(kù)的目錄設(shè)計(jì)與文件規(guī)范3.1 倉(cāng)庫(kù)根目錄結(jié)構(gòu)一個(gè)理想的統(tǒng)一Skills倉(cāng)庫(kù)應(yīng)該從根目錄開(kāi)始就是自解釋的。我的推薦結(jié)構(gòu)是這樣~/ai-skills/ ├── README.md ├── sync.sh ├── sync.ps1 ├── lint.sh └── skills/ ├── code-review/ │ ├── SKILL.md │ ├── checklist.md │ └── scripts/ │ └── extract_diff.py ├── frontend-component/ │ ├── SKILL.md │ ├── templates/ │ │ └── component.tsx │ └── examples/ │ └── sample.md └── db-optimization/ ├── SKILL.md └── references/ └── index-patterns.md根目錄的README.md不是擺設(shè)要寫清楚這個(gè)倉(cāng)庫(kù)是什么、包含哪些技能、如何安裝、如何新增技能。sync.sh和sync.ps1分別是macOS/Linux和Windows下的同步腳本負(fù)責(zé)把skills/下所有技能包鏈接到Claude Code和Codex的目錄。lint.sh用來(lái)統(tǒng)一校驗(yàn)SKILL.md格式CI或本地提交前跑一遍。skills/目錄下每個(gè)子文件夾就是一個(gè)技能包。技能包命名我建議一律用小寫字母加連字符比如code-review、frontend-component不要用空格、中文或駝峰。原因很簡(jiǎn)單目錄名可能出現(xiàn)在文件路徑、腳本變量和日志里越是簡(jiǎn)單通用的命名越不容易踩坑。3.2 SKILL.md的frontmatter怎么寫SKILL.md的frontmatter是整個(gè)技能包的核心因?yàn)锳gent主要靠它來(lái)判斷“何時(shí)觸發(fā)”和“基本信息”。為了兼顧C(jī)laude Code和Codex我推薦只使用公共基礎(chǔ)字段--- name: frontend-component description: 當(dāng)用戶需要生成或修改前端React組件、頁(yè)面、樣式文件時(shí)使用。包含組件模板、樣式規(guī)范、測(cè)試文件生成等場(chǎng)景。 ---name字段是技能包的唯一標(biāo)識(shí)最好和目錄名保持一致。description字段是最關(guān)鍵的部分它直接決定模型能不能在合適的時(shí)機(jī)激活這個(gè)技能。寫description時(shí)要注意寫場(chǎng)景不寫功能說(shuō)明書。不要寫“這是一個(gè)前端組件生成技能支持XXX功能”而要寫“當(dāng)用戶需要……時(shí)使用適用于……場(chǎng)景”。如果你需要給某個(gè)技能加版本號(hào)、作者或許可證建議放在附加文件里比如在技能包目錄里建一個(gè)meta.yaml而不是塞進(jìn)SKILL.md的frontmatter。原因我前面講過(guò)Codex對(duì)未知字段的處理比較保守與其賭工具兼容性不如在結(jié)構(gòu)上徹底繞開(kāi)。3.3 描述信息與觸發(fā)匹配的優(yōu)化技巧description的寫法值得單獨(dú)拿出來(lái)說(shuō)因?yàn)檫@是“同樣的技能包在不同Agent里表現(xiàn)差異最大”的地方。我踩過(guò)最典型的坑是把description寫成了功能清單比如“支持代碼審查、支持漏洞掃描、支持性能評(píng)估”結(jié)果Claude Code很容易誤觸發(fā)而Codex又經(jīng)常漏觸發(fā)。后來(lái)我總結(jié)出一套寫法場(chǎng)景前置 需求樣例 邊界說(shuō)明。場(chǎng)景前置就是開(kāi)頭直接說(shuō)“當(dāng)用戶需要……時(shí)”需求樣例就是列舉幾種用戶可能的說(shuō)法幫助模型建立聯(lián)想邊界說(shuō)明就是誠(chéng)實(shí)交代“不要用這個(gè)技能處理哪些情況”避免過(guò)度觸發(fā)。舉個(gè)例子同樣是“數(shù)據(jù)庫(kù)優(yōu)化”技能低質(zhì)量的description可能是“數(shù)據(jù)庫(kù)優(yōu)化工具包”合格的description大概是description: 當(dāng)用戶需要分析SQL慢查詢、優(yōu)化索引結(jié)構(gòu)、設(shè)計(jì)數(shù)據(jù)庫(kù)表或排查查詢性能問(wèn)題時(shí)使用。典型說(shuō)法包括“幫我看看這條SQL為什么慢”“這個(gè)表要不要加索引”“數(shù)據(jù)庫(kù)查詢很卡”。這樣的description既給了觸發(fā)詞又給了“為什么”和“什么時(shí)候不該用”的邊界。模型在語(yǔ)義匹配時(shí)參考信息越多命中率越高。4. 落地實(shí)操?gòu)牧愦罱ü蚕鞸kills方案4.1 初始化統(tǒng)一Skills倉(cāng)庫(kù)下面是一套可以直接照著做的步驟我默認(rèn)你已經(jīng)裝好了Claude Code和Codex CLI且系統(tǒng)是macOS或Linux。Windows用戶的差異我會(huì)在后面單獨(dú)說(shuō)。第一步創(chuàng)建倉(cāng)庫(kù)目錄和基本結(jié)構(gòu)mkdir -p ~/ai-skills/skills cd ~/ai-skills git init第二步創(chuàng)建根目錄README簡(jiǎn)單說(shuō)明倉(cāng)庫(kù)用途和用法順手把目錄結(jié)構(gòu)畫進(jìn)去。這一步不是形式主義團(tuán)隊(duì)協(xié)作時(shí)它能幫新成員三分鐘上手。第三步創(chuàng)建你的第一個(gè)技能包目錄并編寫SKILL.md。以“前端組件生成”技能為例mkdir -p skills/frontend-component/templates在skills/frontend-component/SKILL.md里寫入--- name: frontend-component description: 當(dāng)用戶需要生成或修改前端React組件、頁(yè)面、樣式文件時(shí)使用。典型訴求包括“寫一個(gè)表格組件”“加一個(gè)篩選器”“把這個(gè)彈窗改成受控組件”。 --- # 前端組件生成 ## 適用場(chǎng)景 - 根據(jù)需求描述生成新的React組件 - 修改已有組件的結(jié)構(gòu)、樣式或交互邏輯 - 生成配套的樣式文件和基礎(chǔ)測(cè)試 ## 執(zhí)行步驟 1. 確認(rèn)組件類型是展示組件還是容器組件是否需要狀態(tài)管理。 2. 檢查項(xiàng)目里是否已有類似組件避免重復(fù)實(shí)現(xiàn)。 3. 按照模板生成組件代碼入口組件放在 templates/component.tsx。 4. 生成樣式文件命名與組件保持一致。 5. 生成基礎(chǔ)測(cè)試文件覆蓋默認(rèn)渲染和核心交互。 ## 輸出要求 - 組件代碼必須使用TypeScript。 - 樣式文件使用CSS Modules。 - 如果需求不明確先列出問(wèn)題清單不要擅自假設(shè)。第四步提交初始版本git add . git commit -m init: add frontend-component skill到這里統(tǒng)一倉(cāng)庫(kù)的雛形就有了。后面所有的新技能都按照同樣的結(jié)構(gòu)往里加保持“一個(gè)技能包一個(gè)目錄目錄內(nèi)必有SKILL.md”這條鐵律。4.2 用符號(hào)鏈接打通Claude Code與Codex倉(cāng)庫(kù)建好之后關(guān)鍵的一步是讓Claude Code和Codex都能讀到同一份技能包。我沒(méi)有選擇“復(fù)制文件過(guò)去”而是用符號(hào)鏈接symlink。原因很簡(jiǎn)單符號(hào)鏈接不復(fù)制內(nèi)容只創(chuàng)建一個(gè)引用路徑。你改了源文件兩邊立即生效徹底解決內(nèi)容漂移問(wèn)題。在macOS或Linux下先確保兩邊的skills目錄存在然后逐個(gè)建立鏈接mkdir -p ~/.claude/skills mkdir -p ~/.codex/skills ln -sfn ~/ai-skills/skills/frontend-component ~/.claude/skills/frontend-component ln -sfn ~/ai-skills/skills/frontend-component ~/.codex/skills/frontend-component如果技能很多逐個(gè)敲太累直接用通配符循環(huán)for skill in ~/ai-skills/skills/*/; do name$(basename $skill) ln -sfn $skill ~/.claude/skills/$name ln -sfn $skill ~/.codex/skills/$name done注意ln -sfn里的-n參數(shù)很關(guān)鍵它表示把目標(biāo)當(dāng)作目錄處理防止在已存在同名符號(hào)鏈接時(shí)出現(xiàn)嵌套鏈接的詭異問(wèn)題。我在這上面吃過(guò)虧不加-n會(huì)導(dǎo)致鏈接套鏈接最終Agent掃不到技能。建立鏈接之后可以用下面的命令驗(yàn)證ls -l ~/.claude/skills/ ls -l ~/.codex/skills/如果看到類似frontend-component - /Users/yourname/ai-skills/skills/frontend-component的輸出說(shuō)明鏈接建立成功。注意檢查鏈接目標(biāo)是否存在如果源目錄被移動(dòng)或刪除鏈接會(huì)變成“斷鏈”Agent會(huì)靜默跳過(guò)不會(huì)報(bào)錯(cuò)。4.3 一鍵同步腳本與Git版本管理手工每個(gè)技能敲一次鏈接還是不夠工程化所以我把同步邏輯寫成了一個(gè)腳本統(tǒng)一倉(cāng)庫(kù)里長(zhǎng)期維護(hù)。下面是一個(gè)macOS/Linux的sync.sh版本#!/usr/bin/env bash set -euo pipefail SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) SKILLS_SOURCE$SCRIPT_DIR/skills TARGETS( $HOME/.claude/skills $HOME/.codex/skills ) FAILED0 for target in ${TARGETS[]}; do mkdir -p $target for skill in $SKILLS_SOURCE/*/; do name$(basename $skill) ln -sfn $skill $target/$name echo linked: $name - $target/$name done done if [ $FAILED -ne 0 ]; then echo sync finished with errors exit 1 fi echo sync complete這里用set -euo pipefail防止腳本在中間出錯(cuò)時(shí)繼續(xù)往下跑保證失敗時(shí)能注意到。每次新增技能包后只需要運(yùn)行一次chmod x sync.sh ./sync.shWindows用戶可以用PowerShell腳本$source Join-Path $PSScriptRoot skills $targets ( (Join-Path $HOME .claude\skills), (Join-Path $HOME .codex\skills) ) foreach ($target in $targets) { New-Item -ItemType Directory -Force -Path $target | Out-Null Get-ChildItem -Path $source -Directory | ForEach-Object { $link Join-Path $target $_.Name if (Test-Path $link) { Remove-Item $link -Force } New-Item -ItemType Junction -Path $link -Target $_.FullName | Out-Null Write-Host linked: $($_.Name) - $link } } Write-Host sync complete然后是Git版本管理。我堅(jiān)持把每個(gè)技能包作為獨(dú)立提交提交信息寫清楚“新增了哪個(gè)技能、為什么要加”。如果要發(fā)版可以給倉(cāng)庫(kù)打tag比如v1.0.0。團(tuán)隊(duì)協(xié)作時(shí)成員拉取倉(cāng)庫(kù)后執(zhí)行一次./sync.sh所有技能就都到位了。想再進(jìn)一步可以在倉(cāng)庫(kù)里加一個(gè)lint.sh用腳本校驗(yàn)所有SKILL.md是否包含name和description字段#!/usr/bin/env bash set -euo pipefail for file in skills/*/SKILL.md; do if ! grep -q ^name: $file; then echo missing name in $file exit 1 fi if ! grep -q ^description: $file; then echo missing description in $file exit 1 fi echo ok: $file done這個(gè)腳本放在pre-commit鉤子里每次提交前自動(dòng)跑一遍能攔截掉大量低級(jí)錯(cuò)誤。4.4 在項(xiàng)目中啟用與驗(yàn)證鏈接建好之后不用重啟終端新開(kāi)一個(gè)Claude Code會(huì)話輸入/skills如果能看到frontend-component等技能名說(shuō)明掃描成功。Codex這邊可以運(yùn)行codex進(jìn)入交互模式然后直接問(wèn)一個(gè)和技能描述吻合的問(wèn)題比如“幫我生成一個(gè)帶搜索功能的表格組件”觀察它是否加載了對(duì)應(yīng)技能。如果項(xiàng)目要求“技能只在特定倉(cāng)庫(kù)里生效”而不是全局生效可以把符號(hào)鏈接放到項(xiàng)目級(jí)目錄也就是在項(xiàng)目根目錄下建.claude/skills和.codex/skills同樣是指向統(tǒng)一倉(cāng)庫(kù)里的技能目錄。這種方式更適合多項(xiàng)目多規(guī)則的團(tuán)隊(duì)因?yàn)椴煌?xiàng)目可以按需啟用不同技能集。有一點(diǎn)要提醒項(xiàng)目級(jí)目錄默認(rèn)會(huì)被Git追蹤所以要么把.claude/skills和.codex/skills加入.gitignore要么讓團(tuán)隊(duì)成員各自執(zhí)行同步腳本。我個(gè)人建議把這兩個(gè)目錄加入.gitignore因?yàn)榧寄馨恼嬲搭^是統(tǒng)一倉(cāng)庫(kù)項(xiàng)目里不應(yīng)該再存一份副本。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 Skill沒(méi)有被識(shí)別這是最常遇到的問(wèn)題。技能明明放進(jìn)目錄了Agent卻視而不見(jiàn)。我的排查順序是這樣的第一檢查目錄層級(jí)。SKILL.md必須放在skills/skill-name/下不能直接放在skills/里也不能多包一層。比如skills/code-review/SKILL.md是對(duì)的skills/code-review/skill/SKILL.md是錯(cuò)的。第二檢查frontmatter。用head -5 SKILL.md看一眼確認(rèn)第一行是---緊接著是name和description字段然后再以---結(jié)束。缺失任何一段解析器都會(huì)跳過(guò)整個(gè)文件。第三檢查鏈接是否健康。如果用了符號(hào)鏈接執(zhí)行l(wèi)s -l看鏈接指向是否存在如果指向的目錄被移動(dòng)過(guò)鏈接就會(huì)斷掉Agent會(huì)靜默忽略。此時(shí)重新運(yùn)行同步腳本即可。第四檢查用戶級(jí)目錄是否拼寫正確。Claude Code用戶級(jí)目錄是小寫.claudeCodex是小寫.codex大小寫敏感系統(tǒng)上寫錯(cuò)了就完全掃不到。5.2 描述觸發(fā)不準(zhǔn)技能能被識(shí)別但該觸發(fā)時(shí)不觸發(fā)不該觸發(fā)時(shí)亂觸發(fā)八成是description寫得有問(wèn)題。我之前寫過(guò)一個(gè)“代碼審查”技能的description“代碼審查工具”結(jié)果給Agent說(shuō)“幫我看看這段代碼”的時(shí)候它不觸發(fā)說(shuō)“生成代碼審查報(bào)告”的時(shí)候反而偶爾觸發(fā)。后來(lái)我把description改成了場(chǎng)景化描述“當(dāng)用戶需要檢查代碼質(zhì)量、發(fā)現(xiàn)潛在bug、評(píng)審Pull Request或生成代碼審查意見(jiàn)時(shí)使用。典型說(shuō)法包括‘幫我review一下這段代碼’‘這個(gè)PR有沒(méi)有問(wèn)題’。”改完之后觸發(fā)率明顯提升。如果發(fā)現(xiàn)觸發(fā)過(guò)于頻繁就加一句“僅適用于……場(chǎng)景”明確邊界。還有一個(gè)經(jīng)驗(yàn)是description不要太長(zhǎng)但也別太短。我一般控制在50到150個(gè)漢字之間既給足語(yǔ)義線索又不至于讓模型在匹配時(shí)被多余信息干擾。5.3 符號(hào)鏈接在Windows下的坑Windows默認(rèn)不允許普通用戶直接創(chuàng)建符號(hào)鏈接除非開(kāi)啟開(kāi)發(fā)者模式或以管理員身份運(yùn)行。我在Windows上試過(guò)New-Item -ItemType SymbolicLink時(shí)報(bào)錯(cuò)后來(lái)?yè)Q成Junction類型就順利了。Junction和SymbolicLink的區(qū)別在于Junction只支持目錄且不需要管理員權(quán)限在部分配置下對(duì)于技能包這種純目錄場(chǎng)景完全夠用。PowerShell腳本里用-ItemType Junction就是基于這個(gè)原因。另外Windows下不要用Remove-Item刪除鏈接指向的源目錄它可能遞歸刪除真正的文件這一點(diǎn)要格外小心刪鏈接時(shí)用Remove-Item $link只刪鏈接本身。5.4 Agent執(zhí)行中斷或權(quán)限錯(cuò)誤有時(shí)候Agent能識(shí)別技能但執(zhí)行過(guò)程中報(bào)“agent execution terminated due to error”或者提示命令找不到、文件讀取失敗。我的排查經(jīng)驗(yàn)是確認(rèn)技能包里引用的腳本是否有執(zhí)行權(quán)限。如果SKILL.md里讓模型運(yùn)行scripts/xxx.py請(qǐng)先手動(dòng)執(zhí)行一遍python3 skills/xxx/scripts/xxx.py --help確認(rèn)無(wú)誤再讓Agent調(diào)用。確認(rèn)技能包內(nèi)文件的路徑描述使用相對(duì)路徑并且以技能包目錄為基準(zhǔn)。比如模板文件寫templates/component.tsx不要寫絕對(duì)路徑因?yàn)椴煌瑱C(jī)器上倉(cāng)庫(kù)路徑不一樣。確認(rèn)Agent的工作目錄權(quán)限。有些工具會(huì)限制只能訪問(wèn)項(xiàng)目目錄內(nèi)的文件如果技能文件在用戶主目錄深處可能會(huì)因?yàn)槁窂皆綑?quán)而失敗。我還遇到過(guò)因?yàn)榧寄苣_本里依賴的Python包沒(méi)裝導(dǎo)致的報(bào)錯(cuò)。處理辦法是在技能包目錄里放一個(gè)requirements.txt并在SKILL.md里寫明“使用本技能前需要安裝以下依賴”。能提前寫清楚的事情千萬(wàn)不要留給運(yùn)行時(shí)才猜。6. 個(gè)人心得與擴(kuò)展建議6.1 我踩過(guò)的幾個(gè)坑這個(gè)方案我已經(jīng)跑了幾個(gè)月踩過(guò)的坑比想象中多。最值得說(shuō)的是三個(gè)。第一個(gè)是曾經(jīng)把同一個(gè)技能在Claude Code和Codex里各寫了一份兩邊內(nèi)容漸漸不一致后來(lái)排查問(wèn)題時(shí)才發(fā)現(xiàn)某條規(guī)則只在一半的Agent里生效。用統(tǒng)一倉(cāng)庫(kù)加符號(hào)鏈接之后這個(gè)問(wèn)題徹底消失了因?yàn)槲锢砩暇椭挥幸环菸募５诙€(gè)坑是過(guò)度設(shè)計(jì)。一開(kāi)始我把frontmatter塞滿了version、author、allowed-tools等字段還寫了自定義解析邏輯結(jié)果Codex那邊表現(xiàn)很奇怪。后來(lái)老老實(shí)實(shí)只用name和description復(fù)雜邏輯全部寫進(jìn)正文反而兩邊都穩(wěn)定。跨工具場(chǎng)景里克制比炫技重要。第三個(gè)坑是測(cè)試不充分。新增技能后只驗(yàn)證了一個(gè)Agent另一個(gè)沒(méi)測(cè)結(jié)果某次緊急任務(wù)正好走到另一個(gè)Agent上才發(fā)現(xiàn)技能壓根沒(méi)被識(shí)別?，F(xiàn)在我的習(xí)慣是任何技能變更之后兩邊都會(huì)各跑一次最小測(cè)試用例確認(rèn)觸發(fā)、加載、執(zhí)行三個(gè)環(huán)節(jié)都沒(méi)問(wèn)題再提交。6.2 后續(xù)擴(kuò)展團(tuán)隊(duì)共享、模板體系與自動(dòng)化這套方案天然適合往團(tuán)隊(duì)方向擴(kuò)展。你只需要把~/ai-skills換成團(tuán)隊(duì)共用的Git倉(cāng)庫(kù)再約定好命名規(guī)范和提交流程每個(gè)成員本地執(zhí)行一次同步腳本就能獲得完全一致的技能體驗(yàn)。新成員入職時(shí)跑兩條命令就能把整個(gè)技能庫(kù)配好不需要手動(dòng)復(fù)制任何文件。進(jìn)一步的話可以把技能包里的模板做得更豐富比如前端組件技能里放多種組件模板、數(shù)據(jù)庫(kù)技能里放常用的索引設(shè)計(jì)樣例。Skills的價(jià)值會(huì)隨著模板質(zhì)量和覆蓋場(chǎng)景的增加而指數(shù)級(jí)上升。還可以考慮把lint.sh集成到CI里每次合并新技能時(shí)自動(dòng)校驗(yàn)格式。如果你的Agent工具支持MCP也可以把一些外部數(shù)據(jù)源或內(nèi)部接口封裝成MCP服務(wù)把“技能包負(fù)責(zé)流程、MCP負(fù)責(zé)外部連接”結(jié)合起來(lái)?？傊劝选耙惶譙kills多Agent共享”的地基打好后面加什么擴(kuò)展都會(huì)順手很多。我自己在維護(hù)這個(gè)倉(cāng)庫(kù)時(shí)最大的體會(huì)是工具會(huì)變但“單一來(lái)源 自動(dòng)化同步 版本管理”的思路不會(huì)過(guò)時(shí)。哪怕以后我又換了一個(gè)新的Agent工具只需要把它的技能目錄加進(jìn)同步腳本整個(gè)體系就能立刻復(fù)用這才是這套方案真正值錢的地方。