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