1. 为什么你的 Codex CLI 需要一棵「技能树」很多人第一次用 Codex CLI 的时候都会经历一个相似的阶段把项目背景、代码规范、提交约定一股脑塞进AGENTS.md然后发现模型确实「知道」了但每次对话都要重新读一遍那几百行说明Token 消耗肉眼可见地涨而且它经常漏看关键条款。我试过在一个前端项目里写了 180 行的规范文档结果模型改一个按钮样式时还是把 BEM 命名写成了btn-red。问题的根源不在于模型不够聪明而在于我们把「知识」和「指令」混在了一起。Codex CLI 从 0.65 版本开始引入的 Skills 机制本质上就是给 AI 助手装上一棵可插拔的「技能树」——每个技能是一个独立的知识包平时只加载名字和描述真正用到时才把全文注入上下文。这种「渐进式披露」的设计让 AI 从「什么都会一点」的通才变成「手持技能手册」的领域专家。Skills 是什么你可以把它理解成 AI 的「知识插件」。它不是一个 Prompt 模板而是一个带元数据的 Markdown 文件放在约定目录里Codex CLI 启动时扫描、按需加载。适合谁适合那些有稳定工作流、希望把个人经验沉淀成可复用资产的开发者尤其是小团队里需要统一代码风格、统一文档格式、统一审查标准的场景。能做什么举几个我实际封装过的例子PDF 文本清洗、ESLint 规则自动修复、根据 Git commit 生成 CHANGELOG、SQL 慢查询审查、BEM 命名强制校验。这些任务的共同点是——步骤固定、规则明确、重复率高。把它们写成 Skill比每次在对话里重新描述一遍要省心得多。这一篇我会带你从零走完 Codex CLI Skills 的落地路径先讲清楚它和传统AGENTS.md的区别再给出可复制的config.toml配置片段和SKILL.md目录结构模板最后用一条完整的验证命令序列确认技能是否真的生效。全程结合 TaoToken 的统一 Key 和 API 通道完成接入你不需要在多个平台之间来回切换。2. TaoToken 前置统一 Key 与 API 通道怎么准备在配置 Skills 之前得先把 Codex CLI 的模型通道打通。Codex CLI 本身是一个客户端它需要指向一个兼容 OpenAI 接口规范的 Base URL并携带有效的 API Key。TaoToken 在这里扮演的角色就是提供统一的 Key 管理和 API 通道让你不用为每个模型单独申请凭证。你需要准备三样东西Base URL、API Key、Model ID。这三件套是后面所有配置的基础缺一不可。Base URL 填https://taotoken.net/api注意这个地址不带任何查询参数。API Key 在控制台的 API Keys 页面生成建议按项目或按用途分开建 Key方便后续排查问题时定位来源。Model ID 则根据你实际要调用的模型填写比如gpt-4o、claude-3-5-sonnet这类标识。为什么强调「统一」因为 Codex CLI 的 Skills 机制本身不关心你用的是哪家模型它只负责在合适的时机把技能内容注入上下文。真正决定请求发往哪里的是config.toml里的 provider 配置。把 Key 和 Base URL 集中管理意味着你换模型时只需要改一个 Model ID不用动 Skills 目录里的任何文件。这里有个容易踩的坑很多人把 API Key 直接写进项目里的.codex/config.toml然后不小心提交到了 Git。正确做法是把 Key 放在环境变量里配置文件里用env_key引用。Codex CLI 支持从环境变量读取这样既安全又方便在不同机器之间迁移。具体操作上你可以先在终端里导出环境变量export TAOTOKEN_API_KEYsk-你的实际KeyWindows 用户用 PowerShell 的话是$env:TAOTOKEN_API_KEYsk-...。导出之后用一条简单的 curl 确认通道是通的curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY如果返回一个包含模型列表的 JSON说明 Key 和通道都没问题。这一步看起来简单但能帮你排除掉后面 80% 的「技能不生效」误判——因为很多时候问题根本不在 Skills而在通道本身没通。另外提醒一句TaoToken 的接入文档里有针对不同客户端的详细配置说明Codex CLI 的字段名和通用 OpenAI 客户端略有差异建议对照文档确认wire_api这类参数。准备阶段多花五分钟后面调试能省半小时。3. 可复制配置config.toml 与 SKILL.md 骨架这一节是整篇的核心我会给出可以直接复制粘贴的配置片段。先看~/.codex/config.toml这是 Codex CLI 的全局配置文件Skills 功能默认是实验性的必须显式开启# ~/.codex/config.toml [features] skills true # 关键开关不开这个技能目录会被完全忽略 [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat [profiles.default] model_provider taotoken model gpt-4o这里有几个细节值得展开。[features]段里的skills true是总开关没有它后面建再多目录也没用。[model_providers.taotoken]段定义了 providerbase_url填 TaoToken 的 API 地址env_key指向你刚才导出的环境变量名wire_api用chat表示走 Chat Completions 协议。[profiles.default]则把默认 profile 绑定到这个 provider 和具体模型上。接下来是技能目录结构。Codex CLI 支持两级技能库全局技能放在~/.codex/skills/所有项目共享项目级技能放在项目根目录的.codex/skills/只对当前项目可见。目录名就是技能 ID里面必须有一个SKILL.md。以「PDF 文本清洗专家」为例全局技能的创建命令是mkdir -p ~/.codex/skills/pdf-cleaner cd ~/.codex/skills/pdf-cleaner touch SKILL.mdSKILL.md的骨架分两部分YAML 头front matter和正文。YAML 头里的name和description是启动时加载的轻量信息正文才是按需注入的完整知识。模板如下--- name: PDF 文本清洗专家 description: 从扫描 PDF 提取结构化文本自动过滤页眉页脚并合并段落 version: 1.0 tags: [pdf, ocr, text-processing] --- 你是一名资深文档工程师请严格按以下流程处理 PDF ### 文本提取 - 优先使用 pdfplumber 或 PyMuPDF - 输出原始文本后进入清洗阶段 ### 清洗规则 1. 页眉页脚识别若连续 3 页首行或末行文本重复判定为页眉页脚并删除 2. 段落合并非句号结尾且下一行缩进不超过 2 空格时合并避免误拼列表项 3. 噪声过滤删除单独成行的纯数字页码删除 □、■、连续 ---- 等扫描残留 ### 输出格式 必须返回 JSON Lines {page: 1, text: 清洗后段落1} {page: 1, text: 清洗后段落2} 禁止直接返回 OCR 原始结果必须执行清洗。项目级技能的路径是.codex/skills/注意是点开头。启动 Codex CLI 时必须在项目目录内它会自动合并全局和本地技能。如果同名项目级优先。这里要强调三件套的完整性Base URL、Key、Model ID 在config.toml里必须全部到位。我见过有人只填了base_url忘了env_key结果请求直接 401也有人model写了个不存在的 ID报错信息却是「技能未加载」白白排查半天。4. 验证请求从零到可用的命令序列配置写完之后怎么确认 Skills 真的生效了这一节给出一条完整的验证命令序列你照着敲一遍就能看到结果。第一步确认配置文件语法正确。Codex CLI 在启动时会解析config.toml如果 TOML 格式有误会直接报错。可以先跑一个 dry-runcodex --version codex config validate如果config validate这个子命令在你的版本里不存在直接启动一次交互模式也能触发解析。看到版本号正常输出、没有 TOML 解析错误说明配置结构没问题。第二步确认技能被扫描到。Codex CLI 启动时会打印技能加载日志你可以用一条显式指定技能的命令来触发codex run --skill pdf-cleaner --file ./docs/report.pdf观察终端输出正常的话会看到类似这样的日志[Skills] Loading skill: pdf-cleaner (v1.0) [Context] Added 328 tokens from skill PDF 文本清洗专家 → Total context: 1,842 / 2048 tokens看到Loading skill加上 token 增量就说明技能已经注入上下文了。如果只有Loading skill没有 token 增量可能是SKILL.md正文为空或者 YAML 头解析失败。第三步用自然语言触发验证「渐进式披露」是否按预期工作。在交互模式里输入请使用「PDF 文本清洗专家」技能处理 ./docs/report.pdfCodex 会自动匹配技能名、加载全文、结合当前上下文执行任务。这一步的意义在于确认技能不是靠--skill参数硬指定的而是能被语义匹配到。第四步检查 Token 消耗是否符合预期。Skills 的核心价值就是省 Token你可以在一次不涉及 PDF 的对话里观察上下文大小应该明显小于加载了技能的那次。如果每次对话的 Token 都居高不下说明技能被全量加载了需要检查skills true是否真的生效。实测下来一个 300 字左右的技能正文注入后大约增加 300 到 400 token而如果把它写进AGENTS.md全量加载每次对话都要多付这部分成本。对话轮次越多差距越明显。5. 本篇常见错排查401、技能未加载与 YAML 解析失败配置过程中最容易撞上的几类报错我按实际遇到的频率排个序逐个给排查路径。401 Unauthorized。这个报错几乎总是 Key 的问题。先确认环境变量真的导出了echo $TAOTOKEN_API_KEY如果输出为空说明当前 shell 会话没读到。注意config.toml里的env_key填的是变量名不是 Key 本身写成env_key sk-xxx是错的。还有一种情况是 Key 复制时带了首尾空格用echo检查一下长度。local proxy failed / connection refused。这类报错说明请求根本没发出去通常是base_url写错了。确认填的是https://taotoken.net/api不要多加/v1或者结尾斜杠。有些客户端会自动拼接路径多写一层就变成/api/v1/v1/chat/completions直接 404。技能未加载日志里没有 Loading skill。按这个顺序查第一config.toml里[features]段的skills true有没有写第二技能目录名和--skill参数是否一致大小写敏感第三项目级技能是否在项目根目录的.codex/skills/下而不是codex/skills/第四SKILL.md文件名是否全大写有些系统对大小写敏感。YAML 头解析失败 / reading choices 报错。SKILL.md的 front matter 必须用---包裹前后不能有空格。键名建议统一用双引号比如name而不是name。如果正文里出现了单独的---行解析器可能误判为 front matter 结束导致后面的内容被截断。解决办法是在正文里用***或者空行代替分隔线。OAuth 相关报错。如果你之前配置过其他 provider 的 OAuth 流程可能会和当前的env_key方式冲突。检查config.toml里有没有残留的[auth]段有的话先注释掉。Codex CLI 的认证优先级是 OAuth 高于 env_key残留配置会覆盖你的 Key。技能和 AGENTS.md 冲突。同名指令以 Skill 为准这是设计上的优先级。但如果你发现 Skill 没生效、AGENTS.md 反而生效了说明 Skill 根本没加载成功回到上一条排查。把这几类报错对照着过一遍基本能覆盖 90% 的配置问题。剩下的 10% 通常是版本差异建议用codex --version确认在 0.65 以上。6. 把经验封装成资产从 Skills 到工作流走到这里你已经有了一个能跑通的 Skills 配置。但真正的价值不在于配好一个技能而在于把「配技能」这件事变成习惯。我自己的做法是每当发现自己在对话里重复描述同一套规则超过三次就把它抽成一个 Skill。比如团队里对 commit message 的格式要求、对 API 错误码的返回约定、对数据库查询的审查清单这些都是天然的技能候选。封装一次后面所有项目都能复用。几个值得封装的技能方向eslint-fixer自动修复并解释规则对新人友好api-contract-gen根据注释生成 OpenAPI YAML减少前后端扯皮changelog-writer从 Git commit 生成语义化 CHANGELOGsql-reviewer检查 N1 查询和缺失索引bem-namer强制 CSS 命名规范。这些任务的共同点是规则明确、步骤固定、重复率高正好是 Skills 的用武之地。如果你需要长期跑编码任务或者搭 Agent 工作流Coding Plan 会比按量调用更划算适合把 Skills 沉淀成稳定的生产力工具。想先验证模型对话效果的话可以从模型对话页面开始试。API Key 的生成和管理在 API Keys 页面接入细节对照接入文档。最后说一句实在的Skills 不是让你少写 Prompt而是让你把 Prompt 从「一次性消耗品」变成「可版本管理的资产」。你今天封装的一个小技能可能就是明天团队里被复用几十次的标准件。这件事的复利比任何单次调优都大。