一文快速入门 Codex Skill：从 SKILL.md 到 Codex CLI 的配置与验证

1. Codex Skill 到底是什么为什么值得先跑通一个最小示例Codex Skill 是 OpenAI Codex CLI 里用来做「知识复用」的机制核心文件是SKILL.md。你可以把它理解成给 Codex 写的一份「岗位说明书」平时它只记住这份说明书的标题和触发条件不占用上下文当你真的问到相关问题时Codex 才把完整内容加载进来按你写好的步骤干活。这个机制叫渐进式披露好处是哪怕你装了十几个 Skill日常对话也不会被拖慢。它适合谁如果你经常重复问 Codex 同一类问题比如「帮我统计 FASTA 序列数量」「按团队规范生成提交信息」「把这段 SQL 转成 ORM 写法」那 Skill 就是把这些重复经验固化下来的地方。写一次之后用自然语言或$skill-name就能触发不用每次重新解释背景。Codex Skill 和 Claude Code Skill 的术语、文件结构几乎一致都是SKILL.md区别主要在存储位置和触发符号Codex 放在~/.codex/skills/触发用$skill-nameClaude Code 放在~/.claude/skills/触发用/skill-name。学会一个另一个基本能直接迁移。这篇要带你跑通的是一个最小可用 Skill从写SKILL.md到放进~/.codex/skills/再到把 Codex CLI 的 endpoint 和鉴权统一改到 TaoToken 管理最后用一条真实请求验证它确实被加载了。全程可复制不需要你先理解全部原理。先明确一个容易混淆的点Skill 不是插件也不是 MCP 服务。它不执行代码只是把「指令 示例 规则」以 Markdown 形式喂给模型。真正干活的是 Codex 本身Skill 负责告诉它「遇到这类问题该怎么做」。所以调试 Skill 时你排查的是「触发条件写没写对」「指令够不够具体」而不是「服务有没有起来」。我试过把团队里反复出现的代码审查清单写成一个 Skill之后每次让 Codex 审 PR它都会按清单逐条过省掉了每次贴规范的动作。这就是 Skill 最实际的价值把口头约定变成可复用的文件。2. 前置准备把 Codex CLI 的 endpoint 与鉴权改到 TaoToken 统一管理在写 Skill 之前先把 Codex CLI 的接入配置理顺。很多人卡在第一步不是 Skill 写错而是 CLI 根本没连上模型。这里我们把 endpoint 和鉴权统一改到 TaoToken好处是 Key 集中管理换模型或换项目时不用到处改配置。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置里填的就是这个干净地址。Codex CLI 的鉴权信息通常放在~/.codex/auth.json模型和 provider 相关配置放在~/.codex/config.toml。不同版本字段名可能略有差异但核心三件套不变Base URL、API Key、Model ID。下面给出可复制的片段你按自己实际拿到的 Key 替换即可。先看auth.json它负责鉴权{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }再看config.toml它负责模型和 provider 声明model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key OPENAI_API_KEY wire_api responses这里env_key指向环境变量名Codex 会去读对应值。如果你更习惯用环境变量而不是auth.json可以在 shell 里导出export OPENAI_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/api配置完成后先别急着写 Skill跑一条最简请求确认链路通codex exec 用一句话说明什么是渐进式披露如果返回了正常文本说明 endpoint 和鉴权都没问题。如果报 401多半是 Key 没生效或auth.json路径不对如果报连接失败检查base_url是不是写成了带 UTM 的地址——配置里只填https://taotoken.net/api。注意wire_api字段在不同 Codex 版本里取值可能是responses或chat以你本地版本实际支持为准。填错会报协议不匹配而不是鉴权错误排查时要区分开。Key 的获取和轮换在 TaoToken 控制台的 API Keys 页面完成建议给不同项目建不同的 Key方便按项目排查用量。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 字段有疑问时以文档为准。这一步做完你就有了一条稳定的模型通道接下来写 Skill 才有意义——否则 Skill 加载了也调不动模型。3. 可复制配置手写一个 SKILL.md 并放进 ~/.codex/skills/现在进入正题。Codex Skill 的目录结构长这样my-skill/ ├── SKILL.md # 必需指令 元数据 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选文档资料 ├── assets/ # 可选模板、图标 └── agents/ └── openai.yaml # 可选UI 配置和依赖最小可用只需要SKILL.md。我们以「FASTA 文件操作」为例先建目录mkdir -p ~/.codex/skills/fasta-tools然后写SKILL.mdvim ~/.codex/skills/fasta-tools/SKILL.md内容如下可直接复制--- name: fasta-tools description: FASTA 文件操作。当用户提到 fasta、序列、基因、基因组时使用。 --- # FASTA 工具箱 ## 指令 1. 询问具体需求统计、提取、转换、过滤 2. 提供 shell 命令推荐或 Python 代码 3. 解释命令每个参数的含义 ## 示例 - 统计序列数量 → grep -c ^ input.fa - 提取长度1000的序列 → seqtk seq -L 1000 input.fa output.fa ## 补充规则 - 优先给一行命令复杂需求才给脚本 - 提醒用户修改输入/输出文件名这里有几个关键点值得展开。第一description是触发条件的核心Codex 靠它判断「这个问题要不要加载这个 Skill」。所以别写「一个有用的工具」这种模糊描述要写清楚「当用户提到 fasta、序列、基因、基因组时使用」。触发词越具体误触发越少。第二## 指令部分要写成可执行的步骤而不是泛泛而谈。Codex 会按这个顺序组织回答步骤清晰输出就稳定。第三## 示例用「用户问 → 你应该」的对照格式这是给模型最直接的信号。示例里的命令要真实可跑别写伪代码。写完后验证安装ls ~/.codex/skills/应该能看到fasta-tools目录。再确认文件在cat ~/.codex/skills/fasta-tools/SKILL.md如果你不想手写Codex 内置了$skill-creator在 Codex 里直接运行$skill-creator它会引导你提供名称、触发示例和存放位置自动生成 Skill。若此前已有中文对话它会直接输出中文否则先用中文聊几句再运行交互语言会切过来。自动生成适合快速起步但生成后建议打开SKILL.md检查description是否够具体。注意Skill 目录名和name字段建议保持一致虽然不强制但排查问题时能少一层心智负担。4. 验证请求与成功结果确认 Skill 真的被加载和调用配置写完不代表生效必须验证。Codex 里查看可用 Skill 列表有两种方式输入$会弹出候选或者运行/skills后选「List skills」。列表里出现fasta-tools说明文件被识别了。接下来做真实触发测试。用自然语言问怎么统计 fasta 文件有多少条序列如果 Skill 生效Codex 的回答会遵循你在SKILL.md里写的结构先确认需求再给命令并解释参数。预期输出大致是grep -c ^ input.fa并附带说明^匹配以开头的行即序列标题行-c统计匹配行数。如果它只是泛泛回答「可以用 grep」没有按你的指令结构走说明 Skill 没被加载回到上一节检查description触发词。也可以用显式调用验证$fasta-tools显式调用会强制加载该 Skill适合排查「到底是没触发还是没写对」。如果显式调用正常、自然语言不触发问题一定在description的触发词上。再测一个带参数的场景提取长度大于 1000 的序列预期它给出seqtk seq -L 1000 input.fa output.fa并提醒你替换输入输出文件名。这一步能验证## 示例和## 补充规则是否被正确读取。验证通过后你可以用同样的方式接入更多 Skill。社区里有现成资源可以参考OpenAI 官方仓库github.com/openai/skills提供内置示例bioSkills 覆盖 62 个分类、425 个技能SkillMD.ai 是社区市场。改造通用 Skill 的常见做法是先用$skill-creator生成再手动调整description和指令让它贴合你自己的流程。注意验证时如果 Codex 报reading choices相关错误通常是模型返回格式和 CLI 预期不一致检查config.toml里的wire_api取值是否和当前模型匹配。5. 本篇常见错误排查401、local proxy failed、OAuth 与配置不生效跑通过程中容易踩的坑集中在几类逐个对照排查。第一类401 鉴权失败。报错通常长这样401 Unauthorized: invalid api key原因有三种Key 写错、auth.json路径不对、环境变量没导出。先确认 Key 没有多余空格再确认~/.codex/auth.json确实存在且字段名是OPENAI_API_KEY。如果你同时用了环境变量和auth.json以实际读取顺序为准建议只保留一种来源避免互相覆盖。第二类local proxy failed或连接超时。这类报错多半是base_url写错。检查config.toml和auth.json里的地址是不是https://taotoken.net/api不要带 UTM 参数也不要多写斜杠。如果本地有网络策略限制确认能正常访问该地址。第三类OAuth 相关报错。Codex 某些版本会走 OAuth 流程如果你用的是 API Key 模式需要在配置里明确 provider避免它去尝试 OAuth。config.toml里的model_provider taotoken和[model_providers.taotoken]段就是干这个的。报错里出现OAuth字样时先确认 provider 段有没有写全。第四类Skill 不触发。显式$fasta-tools能调用、自然语言不行问题在description。把触发词写得更贴近用户实际说法比如加上「序列统计」「基因组文件」这类同义表达。第五类reading choices报错。这是响应格式解析问题通常是wire_api和模型不匹配。换成另一个取值再试或者确认当前模型是否支持所选协议。第六类配置改了不生效。Codex 可能缓存了旧配置重启 CLI 再试。另外确认你改的是当前用户目录下的~/.codex/而不是项目里的局部配置。排查时有个通用思路先确认模型通道通跑一条codex exec最简请求再确认 Skill 被识别/skills列表最后确认触发逻辑显式调用 vs 自然语言。三层分开验证比一上来就怀疑 Skill 写错高效得多。6. 把 Skill 用起来从最小示例到团队复用最小示例跑通后下一步是把它变成真正省时间的工具。几个实用方向把团队代码规范写成 Skill让 Codex 审代码时自动按规范走把常用数据处理流程封装成 Skill新人不用问就知道怎么做把项目特有的目录结构和命名约定写进去减少来回解释。长期做编码和 Agent 任务的话可以考虑用 Coding Plan 统一管理额度入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要单独验证某个模型表现时用模型对话页面快速试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。Key 管理仍在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Skill 的本质是知识复用写一次之后每次触发都在替你省解释成本。先把fasta-tools这类小 Skill 跑顺再逐步把团队流程搬进去比一上来写大而全的 Skill 更容易成功。