當 Codex 中的 Skill 從兩三個增長到二三十個時把它們一股腦塞進 preferences 或 AGENTS.md 的做法就會明顯失效。Skill 文件散落在不同目錄、命名混亂、啟停要靠手改配置、內(nèi)容改完不知道是否被加載……這些問題的本質(zhì)是Codex 負責執(zhí)行 Skill但沒有一個專門的工作臺來管理 Skill。SkillDeck 正是為了解決這個問題而出現(xiàn)的一個本地管理工具它圍繞 Codex 的 Skill 目錄結(jié)構(gòu)提供創(chuàng)建、校驗、索引、啟停、打包和集成能力。下面的內(nèi)容會以 SkillDeck 為例把 Codex Skill 的組織方式、工作臺的核心命令、與 Codex 的同步方式、運行驗證、常見排錯路徑和工程化建議完整講一遍。你可以把它當作一套本地 Skills 管理方案來落地也可以借其中的索引、校驗和同步思路改造自己已有的腳本或插件。1. 先理解 Codex Skill 的目錄結(jié)構(gòu)和加載方式1.1 Skill 是什么為什么不能當成普通提示詞Codex 中的 Skill 可以理解為一組可復用的“操作說明書”。它比一句提示詞更結(jié)構(gòu)化的地方在于Skill 通常包含入口說明文件、示例、參考文檔和執(zhí)行腳本。Codex 在對話中讀到 Skill 后會按里面的步驟、參考材料和腳本去完成一類固定任務(wù)例如代碼審查、SQL 優(yōu)化、日志排查、前端重構(gòu)。如果只把 Skill 當成普通提示詞來寫內(nèi)容很容易堆在單個文件里。短的時候還能看懂一旦涉及多個步驟、多份參考資料、多個腳本Codex 就很難準確執(zhí)行。Skill 是用來組織這些內(nèi)容的容器它的問題不是“讓模型記住這句話”而是“讓模型在合適的時候找到這組指令并按順序執(zhí)行”。1.2 一個最小 Skill 的目錄結(jié)構(gòu)一個便于管理和校驗的 Skill 目錄應(yīng)該把“說明、參考、腳本、示例”分開。下面的結(jié)構(gòu)是常見做法不同團隊可以按需裁剪~/.codex/skills/ ├── code-review/ │ ├── SKILL.md │ ├── review-checklist.md │ └── scripts/ │ └── collect_changes.sh ├── sql-optimize/ │ ├── SKILL.md │ └── references/ │ └── index-usage.md └── log-debug/ ├── SKILL.md ├── examples/ │ └── timeout-error.md └── scripts/ └── trace_error.pySKILL.md是入口文件負責描述這個 Skill 的名稱、用途、觸發(fā)條件和執(zhí)行步驟。references放長文檔scripts放可執(zhí)行腳本examples放輸入輸出示例。這樣設(shè)計的好處是SKILL.md保持短小Codex 能快速理解 skill 的用途等它決定啟用 Skill 后再按路徑去讀補充材料。1.3 Codex 加載 Skill 的常見方式Codex 讀取 Skill 的機制在不同版本中會有差異但整體思路是通過配置文件或指令文件把SKILL.md的路徑暴露給 Codex。常見做法是在AGENTS.md中寫入引用路徑例如# Codex Agent Instructions ## Skills - skills/code-review/SKILL.md - skills/sql-optimize/SKILL.md這個文件通常放在項目根目錄也可以放在用戶級目錄中。當 Codex 啟動會話時它會掃描這些引用把 Skill 內(nèi)容作為上下文的一部分加載。也就是說Skill 文件寫好了還不夠必須確保 Codex 能通過配置文件找到它。也有團隊會把 Skill 名稱維護在全局設(shè)置中但這種方式不利于按項目切換。相對推薦的做法是Skill 文件放在統(tǒng)一目錄項目通過AGENTS.md按需引用。SkillDeck 的同步能力就是圍繞這個場景設(shè)計的。1.4 多個 Skill 后暴露的管理問題只管理三五個 Skill 時手寫引用問題不大。但 Skill 一旦多起來會出現(xiàn)幾類明顯問題目錄命名不統(tǒng)一例如code-review、CodeReview、code-review-v2混在一起。啟停 Skill 需要人肉修改AGENTS.md容易漏改或改錯。SKILL.md的字段不完整Codex 無法判斷何時使用這個 Skill。內(nèi)容更新后不知道 Codex 是否已經(jīng)加載只能重啟會話再觀察。沒有索引文件無法快速回答“當前一共啟用了哪些 Skill、版本是什么”。SkillDeck 的核心價值就是把上面這些散落的手工操作收斂成一套命令行工作流。2. SkillDeck 的工作臺模型與核心能力2.1 SkillDeck 的定位SkillDeck 不是一個讓 Codex 變聰明的模型工具而是一個“管理工作臺”。它解決的是 Codex 中 Skill 的生命周期問題創(chuàng)建、命名、填寫元信息、啟用、停用、校驗、生成索引、打包、同步到 Codex 配置。它管理的核心對象是 Skill 目錄和SKILL.md元信息。通過固定的命令入口把原本需要手動操作文件和拼寫路徑的過程變成可重復、可檢查、可回滾的流程。2.2 核心命令和入口SkillDeck 的常用入口分為 CLI 和 Web 工作臺兩部分。CLI 適合在日常編輯和 CI 中使用Web 工作臺適合可視化查看狀態(tài)。下面是一組核心命令示例skilldeck init --skill-root ~/.codex/skills skilldeck new code-review --template review skilldeck list --enabled-only --json skilldeck enable sql-optimize skilldeck disable log-debug skilldeck validate --strict skilldeck index skilldeck sync --target ~/.codex/AGENTS.md skilldeck pack code-review --output dist/這些命令對應(yīng)一條完整的管理鏈路初始化、創(chuàng)建、查看狀態(tài)、啟停、校驗、生成索引、同步給 Codex、打包分發(fā)給團隊。2.3 索引、啟停和打包如何協(xié)同SkillDeck 把管理狀態(tài)和 Codex 可能關(guān)心的元信息集中到一個索引文件中。索引內(nèi)容由skilldeck index生成示例如下{ version: 1, generatedAt: 2025-06-18T10:00:00Z, skills: [ { name: code-review, path: skills/code-review, version: 1.2.0, enabled: true, entry: SKILL.md, tags: [review, code, pr] } ] }索引是一個中間產(chǎn)物。它不是給 Codex 讀的核心文件而是給開發(fā)者和 CI 用的狀態(tài)快照。sync命令會把“啟用的 Skill 列表”寫到AGENTS.mdpack命令則把單個 Skill 打包成 tar.gz便于跨機器分發(fā)。三者結(jié)合在一起才能做到“本地查看狀態(tài)、一鍵同步給 Codex、打包給隊友”。2.4 技術(shù)實現(xiàn)上的取舍實現(xiàn) SkillDeck 時可以把核心邏輯放在一個 CLI 中而不必強依賴 Web 服務(wù)。這樣做的好處是不占用固定端口不會干擾開發(fā)環(huán)境。更符合本地文件管理場景命令執(zhí)行完即退出。方便接入 CI提交前自動執(zhí)行validate。避免為了讓 Codex 使用 Skill 而額外啟動一個常駐進程。Web 工作臺可以作為可選模塊。它只負責讀取索引文件和調(diào)用同一套 CLI 邏輯而不是繞過 CLI 直接改文件。這樣即使 Web 服務(wù)崩潰也不會影響已有 Skill 的加載。3. 環(huán)境準備與初始化3.1 環(huán)境要求SkillDeck 作為一個本地命令行工具依賴一套穩(wěn)定的運行時。下面以 Node.js 生態(tài)為例環(huán)境要求說明Node.js18 或更高版本CLI 依賴較新的文件系統(tǒng) API 和全局 fetch 行為npm9 或更高版本用于安裝全局 CLIGit有則更好便于對 Skills 目錄做版本管理Codex CLI按官方要求安裝用于驗證 Skill 是否被加載如果原始項目沒有明確最低版本落地前要先確認自己環(huán)境中的 Node 版本。不要直接npm install后貿(mào)然使用低版本 Node 可能導致命令輸出異常或文件寫入失敗。3.2 安裝 SkillDeck如果 SkillDeck 已經(jīng)發(fā)布到 npm可以通過全局命令安裝npm install -g skilldeck/cli skilldeck --version如果還沒有發(fā)布到 npm或者你想在本地調(diào)試可以使用源碼方式運行g(shù)it clone 倉庫地址 skilldeck cd skilldeck npm install npm link skilldeck --version安裝完成后需要確認命令能被找到。如果提示command not found檢查 npm 的全局 bin 目錄是否在PATH中。3.3 初始化工作區(qū)安裝完成后先初始化 Skill 根目錄skilldeck init --skill-root ~/.codex/skills執(zhí)行后SkillDeck 會創(chuàng)建基礎(chǔ)目錄結(jié)構(gòu)和配置文件。目錄層級類似這樣~/.codex/skills/ ├── .skilldeck/ │ ├── config.yaml │ └── index.json └── README.md初始化過程不會修改 Codex 的配置它只創(chuàng)建 SkillDeck 自己需要的目錄。把這一步和后面的sync分開是為了避免“剛剛初始化就意外覆蓋了 Codex 配置文件”。3.4 配置項說明config.yaml是 SkillDeck 的主要配置文件。常見配置如下skillRoot: ~/.codex/skills indexFile: ~/.codex/skills/.skilldeck/index.json codexConfig: ~/.codex/AGENTS.md enabledOnlyByDefault: true packDir: ~/.codex/skills/.skilldeck/dist defaultTemplate: basic配置項作用默認值建議skillRootSkill 所在根目錄~/.codex/skills使用默認值便于統(tǒng)一管理indexFile索引 JSON 輸出路徑.skilldeck/index.json放在 skillRoot 下codexConfig需要同步的 Codex 配置文件~/.codex/AGENTS.md改為實際路徑enabledOnlyByDefault新建 Skill 是否默認啟用true按團隊習慣設(shè)置packDir打包產(chǎn)物目錄.skilldeck/dist加入.gitignoredefaultTemplate新建 Skill 使用的模板basic可選review、python等配置項的調(diào)大或調(diào)小影響比較直接skillRoot改動后所有 skill 的路徑都會變化建議在初始化階段確定不要頻繁切換。enabledOnlyByDefault設(shè)置為false時新 Skill 默認不進入同步列表適合先編寫后評審的團隊流程。4. 創(chuàng)建 Skill 并填充內(nèi)容4.1 用模板創(chuàng)建 Skill在初始化好的工作區(qū)中創(chuàng)建 Skillskilldeck new code-review --template review該命令會在~/.codex/skills/code-review目錄下生成入口文件、參考文件和腳本目錄。使用模板的好處是避免每次手寫相同結(jié)構(gòu)。如果模板不滿足需求也可以先創(chuàng)建一個空 Skillskilldeck new sql-optimize然后手動補全內(nèi)容。無論哪種方式最終生成的 Skill 都應(yīng)當能被validate命令通過否則即使復制到 Codex 目錄也不會被正常識別。4.2 編輯 SKILL.md 的 frontmatterSKILL.md的 frontmatter 是 SkillDeck 校驗和索引的核心依據(jù)。一個最小示例--- name: code-review description: 對指定代碼變更執(zhí)行結(jié)構(gòu)化審查輸出問題清單和修改建議。 version: 1.0.0 author: coding-team tags: [review, code-quality, pr] enabled: true --- # Code Review 當用戶要求審查代碼變更或 PR 時執(zhí)行以下步驟 1. 收集變更文件和 diff。 2. 按可讀性、安全性、性能和測試覆蓋四類檢查。 3. 輸出問題清單、影響范圍和修復建議。name必須與目錄名保持一致并且使用小寫加短橫線。description要寫清楚“什么時候用”和“能輸出什么”這一行決定了 Codex 在對話中是否把任務(wù)匹配到這個 Skill。不要寫成“這是一個代碼審查技能”這樣的空描述而要寫“審查代碼變更并輸出問題清單和修改建議”。version是必填字段建議與 Git tag 同步。enabled表示當前是否啟用但在索引生成時會以實際運行狀態(tài)為準。4.3 把長流程寫入 references 和 scriptsSKILL.md不要寫成長篇大論。代碼審查規(guī)則、SQL 優(yōu)化排查步驟、日志分析流程等內(nèi)容可以拆分到references或scripts中。例如在SKILL.md中使用相對路徑引用## 執(zhí)行步驟 1. 先運行 scripts/collect_changes.sh main 獲取變更文件列表。 2. 閱讀 references/review-checklist.md 中的檢查點。 3. 對照變更列表逐項輸出結(jié)果。collect_changes.sh的示例#!/usr/bin/env bash # 根據(jù)基礎(chǔ)分支獲取變更文件列表 set -euo pipefail BASE_BRANCH${1:-main} git diff --name-only --diff-filterACM $BASE_BRANCH腳本要處理失敗情況不能假設(shè)命令一定成功。set -euo pipefail可以在變量為空、管道失敗時提前退出方便 Codex 發(fā)現(xiàn)問題。4.4 啟用、禁用和查看列表Skill 創(chuàng)建后可以查看當前狀態(tài)skilldeck list輸出示例code-review v1.0.0 enabled sql-optimize v1.0.0 enabled log-debug v1.0.0 disabled啟用或禁用某個 Skillskilldeck enable sql-optimize skilldeck disable log-debug這兩個命令會更新本地狀態(tài)并在下次index或sync時反映到索引和 Codex 配置中。如果你只想查看啟用的 Skill 列表方便確認同步內(nèi)容可以執(zhí)行skilldeck list --enabled-only --json輸出是 JSON便于在 CI 或腳本中進一步處理。5. 校驗、索引與 Codex 集成5.1 執(zhí)行 validate 和 index當 Skill 內(nèi)容修改完成先執(zhí)行校驗skilldeck validate --strict--strict模式會檢查必填字段、路徑引用和腳本是否存在。寬松模式只檢查 frontmatter 是否可解析。建議在提交代碼前使用--strict避免壞結(jié)構(gòu)進入共享倉庫。校驗通過后生成索引skilldeck index索引文件不是擺設(shè)。它記錄了 Skill 名稱、描述、版本、啟用狀態(tài)和路徑。后續(xù)sync、Web 工作臺和 CI 都會讀這份文件而不是重新掃描所有目錄。5.2 生成 skill-index.json索引文件樣例{ version: 1, generatedAt: 2025-06-18T10:00:00Z, skills: [ { name: code-review, description: 對指定代碼變更執(zhí)行結(jié)構(gòu)化審查輸出問題清單和修改建議。, path: skills/code-review, version: 1.0.0, enabled: true, entry: SKILL.md, tags: [review, code-quality, pr] } ] }這個文件建議提交到 Git但要視團隊情況而定。如果每個成員都使用同一套 Skill 目錄提交索引能保證所有人看到相同狀態(tài)如果各項目差異很大則可以把索引放在.gitignore中只在 CI 或本地生成。5.3 把啟用列表同步到 AGENTS.md索引生成后還需要把狀態(tài)同步給 Codex。執(zhí)行skilldeck sync --target ~/.codex/AGENTS.mdsync不會覆蓋整個文件。它會在AGENTS.md中維護一個## Skills段把啟用的 Skill 引用寫入其中其余人工維護內(nèi)容保持不變。同步后文件看起來類似# Codex Agent Instructions ## 項目自定義規(guī)則 - 提交代碼前必須運行測試。 ## Skills - skills/code-review/SKILL.md - skills/sql-optimize/SKILL.md注意sync會改寫目標文件。如果AGENTS.md中有團隊自定義內(nèi)容先確認 SkillDeck 的同步策略只操作## Skills段否則會覆蓋人工維護的指令。5.4 驗證 Codex 是否真正讀到 Skill同步完不等于加載成功。建議做一次顯式驗證確認skilldeck list --enabled-only中啟用了目標 Skill。確認AGENTS.md中出現(xiàn)對應(yīng)引用。重啟 Codex 會話輸入一個能觸發(fā) Skill 的請求。觀察輸出是否包含SKILL.md中的步驟或腳本行為。不要只驗證“命令能執(zhí)行”要驗證“Codex 行為發(fā)生了變化”。例如 code-review Skill 生效后Chat 輸出里應(yīng)該出現(xiàn)“收集變更文件、按檢查清單逐項審查”這些結(jié)構(gòu)而不是泛泛給出建議。6. 運行驗證和預期輸出6.1 完整命令序列一次完整的更新流程可以像下面這樣執(zhí)行skilldeck new log-debug # 編輯 SKILL.md 和 scripts/trace_error.py skilldeck validate --strict skilldeck enable log-debug skilldeck index skilldeck sync這些命令的順序不能亂。先創(chuàng)建和填寫內(nèi)容再校驗校驗通過后啟用啟用后生成索引索引更新后再同步給 Codex。如果先sync再validate壞結(jié)構(gòu)會被直接寫進 Codex 配置。6.2 預期輸出與索引內(nèi)容執(zhí)行validate時可能出現(xiàn)三種結(jié)果[OK] code-review 通過校驗字段完整 [OK] sql-optimize 通過校驗字段完整 [OK] log-debug 通過校驗字段完整如果某個 Skill 缺少version輸出會提示[ERROR] log-debug frontmatter 缺少 version 字段執(zhí)行index后可以讀取索引文件確認狀態(tài)cat ~/.codex/skills/.skilldeck/index.json只要enabled為true且path指向真實目錄就說明索引層已經(jīng)準備完畢。6.3 在 Codex 會話中觀察加載效果實際驗證時用一個具體請求來觸發(fā) Skill。例如測試 code-review Skill請審查當前分支相對 main 的代碼改動。如果 Skill 被正確加載Codex 輸出中應(yīng)當體現(xiàn)SKILL.md中定義的步驟例如“先讀取變更文件列表”并且最終給出問題清單。如果它只是簡單回答“我沒有看到改動”說明 Skill 沒有進入上下文。另一種驗證方式是在SKILL.md中寫一個固定輸出詞例如“開始執(zhí)行 Code Review Skill”然后請求觸發(fā)。如果輸出不含該詞說明引用沒有生效或 Skill 描述沒有被識別。7. 常見問題與排查路徑7.1 索引生成了但 Codex 沒變化現(xiàn)象skilldeck index成功生成索引也執(zhí)行了sync但 Codex 的響應(yīng)沒有按新 Skill 執(zhí)行?？赡茉駻GENTS.md路徑和 Codex 實際讀取路徑不一致。Codex 會話沒有重啟仍然使用舊上下文。啟用的 Skill 列表沒有真正寫入AGENTS.md。SKILL.md的description與請求意圖不匹配Codex 沒有識別為可觸發(fā)技能。檢查方式skilldeck list --enabled-only --json cat ~/.codex/AGENTS.md處理建議確認config.yaml中codexConfig指向正確文件重啟 Codex 會話如果 description 與用戶請求語義相差太遠重寫描述。7.2 frontmatter 校驗失敗現(xiàn)象skilldeck validate報錯提示無法解析 frontmatter或缺少必填字段?？赡茉?--開閉標記不完整。description留空或不是字符串。name與目錄名不一致。YAML 縮進錯誤導致字段解析異常。檢查方式用編輯器打開SKILL.md確認 frontmatter 位于文件最頂部并且開閉標記一致。處理建議按模板修正字段重新執(zhí)行校驗。建議把name固定為目錄名避免以后移動目錄時索引錯亂。7.3 Codex 請求 /responses 報錯現(xiàn)象Codex 會話開始后請求/responses接口失敗經(jīng)常伴隨網(wǎng)絡(luò)錯誤或模型配置錯誤?？赡茉蚓W(wǎng)絡(luò)不穩(wěn)定無法連接到 Codex 底層服務(wù)。當前賬號或密鑰沒有訪問所選模型的權(quán)限。Codex 版本與模型版本不匹配。請求參數(shù)中包含不被當前版本支持的字段。檢查方式查看 Codex 的日志輸出確認失敗的請求參數(shù)和響應(yīng)狀態(tài)。檢查配置文件中模型名是否在當前版本支持范圍內(nèi)。處理建議先確認網(wǎng)絡(luò)可達再檢查模型名。如果代碼中硬編碼了模型標識改成當前環(huán)境支持的模型名。不要直接忽略這類報錯因為它會導致 Skill 文件根本沒機會被讀取。7.4 模型不受支持報錯現(xiàn)象啟動或請求時報錯類似于the xxx model is not supported?？赡茉蛩x模型在當前 Codex 版本中不存在或模型標識拼寫錯誤。檢查方式查看 Codex 支持的模型列表比較配置中的模型名。處理建議切換到支持的模型或升級 Codex 版本。升級前先備份AGENTS.md和.codex目錄中的配置文件避免版本升級改變配置結(jié)構(gòu)。7.5 排錯順序建議遇到問題時不要一開始就懷疑 Skill 文件內(nèi)容。推薦按順序排查skilldeck validate是否能通過。skilldeck list中的enabled是否正確。AGENTS.md中是否存在啟用 Skill 的引用。Codex 會話是否重啟是否真的讀取了新的AGENTS.md。Codex 日志和網(wǎng)絡(luò)響應(yīng)是否正常。模型名和版本是否匹配。先確認文件層狀態(tài)再看同步層最后看 Codex 運行層。這樣能避免把簡單問題復雜化。8. 最佳實踐與擴展方向8.1 把 Skill 當作代碼管理Skill 不是一次性提示詞而是長期維護的工程資產(chǎn)。建議像管理代碼一樣管理它使用 Git 版本控制。每次修改都更新version。提交前執(zhí)行skilldeck validate --strict。讓每個 Skill 都有 owner。在 PR 描述中說明 Skill 行為變化。這些規(guī)則不是限制而是為了在多人協(xié)作時減少混亂。SkillDeck 的命令本身不強制這些流程但通過validate和index提前暴露問題。8.2 生產(chǎn)環(huán)境落地清單在正式團隊環(huán)境中落地 SkillDeck 前可以檢查以下項目檢查項建議Skill 目錄是否納入版本控制是放入團隊倉庫SKILL.md是否都有version是與 Git tag 同步CI 是否執(zhí)行validate --strict是阻塞合并AGENTS.md是否由sync生成是避免手工修改索引文件是否有備份是納入倉庫或備份到制品庫是否有 Codex 日志監(jiān)控是關(guān)注/responses報錯和模型不支持類問題是否定期檢查 Skill 觸發(fā)效果是維護 Skill 使用示例和回歸用例8.3 適合繼續(xù)學習的擴展方向SkillDeck 當前可以解決本地管理問題后續(xù)還可以擴展出更多能力支持遠程 Skill 倉庫從團隊倉庫自動拉取和更新。支持 Skill 市場按標簽搜索和安裝。支持多 Agent 互轉(zhuǎn)將同一份 Skill 轉(zhuǎn)換成 Claude Code、Cursor 等工具支持的格式。支持組合編排讓一個 Skill 調(diào)用另一個 Skill。支持統(tǒng)計分析根據(jù) Codex 日志判斷哪些 Skill 使用頻繁、哪些從未觸發(fā)。如果只是剛接觸 Skill不建議一開始就追求復雜擴展。先把validate、index、sync這三條命令跑進日常流程再逐步引入版本管理和 CI 校驗比一次搭建一個龐大平臺更穩(wěn)妥。SkillDeck 的價值不在于把文件變多而在于把散落的 Skill 變成可以被檢查、被同步、被回滾的工程資產(chǎn)。當 Codex 會話里的行為穩(wěn)定下來你真正依賴的已經(jīng)不是某一個命令而是“目錄、索引、校驗、同步”這套組合流程。