1. 为什么我要折腾 Codex Agent Skills如果你已经在用 Codex CLI 或 IDE 扩展写代码大概率遇到过这种场景每次让它做代码审查都要重复粘贴同一套规范每次让它生成数据库迁移脚本都要重新解释命名约定和回滚策略。提示词越写越长上下文窗口被这些重复内容吃掉一大半真正留给代码本身的空间反而越来越少。Codex Agent Skills 就是来解决这个问题的。它把「可复用的工作流」从聊天记录里抽出来固化成一个带SKILL.md的目录Codex 在需要的时候按需加载不需要的时候只保留一行描述。你可以把它理解成给 Codex 写的「标准操作流程手册」做什么、什么时候做、怎么做全部写清楚之后无论是显式调用还是隐式匹配它都能自动激活。这套机制适合三类人一是团队里想把代码规范沉淀下来的工程师二是经常写重复脚本、想让 Agent 自动接管的自动化玩家三是想把内部工具封装成技能分发给同事的团队负责人。我实测下来一个写得好的 Skill 能把重复提示词减少七成以上而且触发稳定性比纯靠聊天上下文高得多。下面我会从目录骨架、SKILL.md结构、skill-creator生成流程、Plugins 挂载一直到settings.json/config.toml片段和一次完整的加载验证全部走一遍。你跟着做就能在本地跑通自己的第一个自定义技能。2. TaoToken 前置准备把模型通道先打通在写 Skill 之前得先保证 Codex 能正常调用模型。我这边习惯用 TaoToken 作为统一入口它的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的请求格式Codex 配置起来比较省事。第一步是拿 Key。打开控制台页面https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite登录后在 API Keys 区域创建一个新 Key。建议按用途分开建比如codex-dev、codex-agent方便后面排查是哪个环境出的问题。创建完记得立刻复制页面刷新后就看不到完整 Key 了。拿到 Key 之后在终端里设置环境变量。macOS / Linux 用export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的实际Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你想让 Codex 的配置文件直接引用这个 Key可以在~/.codex/config.toml里写model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat这样 Codex 启动时会自动读取环境变量里的 Key不用把明文写进配置文件。配置完先跑一次最简单的对话验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里能看到choices字段就说明通道没问题。这一步别跳过后面 Skill 加载失败很多时候其实是模型通道本身没通排查起来会绕远路。3. 可复制配置SKILL.md 结构与目录骨架Skill 的本质就是一个目录里面必须有一个SKILL.md。这个文件分两部分顶部的 YAML front matter 写元数据下面的正文写执行指令。先看最小可用的目录骨架my-skill/ ├── SKILL.md # 必备元数据 执行指引 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 ├── assets/ # 可选模板、静态资源 └── agents/ └── openai.yaml # 可选UI 元数据与调用策略SKILL.md的 front matter 至少要有name和description两个字段。description是隐式匹配的核心写得越精准Codex 越容易在合适的时机自动激活它。我一般把核心触发词放在最前面因为初始技能列表有字符预算限制描述可能被截断。--- name: sql-migration-review description: 审查数据库迁移脚本检查命名规范、回滚策略和索引合理性。当用户提到 migration、DDL、ALTER TABLE、数据库变更时触发。 --- # SQL 迁移审查技能 ## 执行步骤 1. 读取用户提供的迁移文件确认目标数据库类型PostgreSQL / MySQL。 2. 检查表名和列名是否使用 snake_case。 3. 确认每个 ALTER TABLE 都有对应的回滚语句。 4. 检查新增索引是否覆盖了 WHERE 和 JOIN 中的高频字段。 5. 输出审查报告按「阻断项 / 建议项 / 通过项」三档分类。 ## 输出格式 用 Markdown 表格列出问题每行包含文件位置、问题类型、修改建议。这里有几个我踩过的坑。第一description不要写成「这是一个很好的技能」这种空话要写清楚「什么时候触发、什么时候不触发」。第二正文指令用祈使句明确每一步的输入和输出Codex 执行起来更稳定。第三如果技能需要调用外部工具在agents/openai.yaml里声明依赖别在正文里硬编码。agents/openai.yaml的可选配置长这样interface: display_name: SQL 迁移审查 short_description: 检查迁移脚本的规范与回滚 brand_color: #3B82F6 policy: allow_implicit_invocation: true dependencies: tools: - type: mcp value: postgres-inspector description: 用于读取表结构的 MCP 服务 transport: streamable_http url: https://your-mcp-host/mcpallow_implicit_invocation默认是true设成false后只能通过$skill-name显式调用适合那些不想被误触发的危险操作技能。4. 用 skill-creator 生成与 Plugins 挂载手动写SKILL.md适合结构简单的技能但如果你要生成一个带脚本、带参考文档的完整骨架用内置的skill-creator更快。在 Codex 里输入$skill-creator它会依次问你三个问题这个技能做什么、什么时候触发、纯指令还是包含脚本。回答完之后它会在当前目录下生成一个完整的技能目录包括SKILL.md、scripts/和agents/openai.yaml的模板。我一般会在这个基础上改比从零写省事。生成完之后把技能放到 Codex 能扫描到的位置。Codex 会从四个范围读取技能仓库级、用户级、管理员级、系统级。最常用的是仓库级和用户级# 仓库级当前工作目录向上扫描到仓库根 $CWD/.agents/skills/ $REPO_ROOT/.agents/skills/ # 用户级当前用户所有仓库通用 $HOME/.agents/skills/比如你把技能放在~/.agents/skills/sql-migration-review/那所有仓库都能用。如果只想给某个项目用就放在项目根目录的.agents/skills/下。如果你要把技能分发给团队或者打包多个技能一起发布就需要用 Plugins 机制。Plugins 是分发格式Skills 是编写格式两者关系类似「源码」和「安装包」。一个 Plugin 可以包含多个 Skill还能带上 MCP 服务器配置和展示资源。挂载 Plugin 后里面的技能会自动出现在技能选择器里。安装精选技能可以用$skill-installer$skill-installer linear它会从官方仓库拉取技能到本地。安装完如果没立刻出现重启 Codex 即可它会自动检测新文件。5. 验证请求一次完整的技能加载动作配置写完得验证技能真的能被加载和触发。我一般分两步先确认技能出现在初始列表里再测试显式调用和隐式匹配。第一步启动 Codex 后输入/skills命令看列表里有没有你刚创建的技能。如果没出现先检查目录路径对不对再检查SKILL.md的 front matter 格式有没有写错。YAML 对缩进敏感name和description前面不能有多余空格。第二步显式调用测试。在提示词里输入$sql-migration-review 帮我看看这个迁移脚本有没有问题如果技能正常加载Codex 会读取完整的SKILL.md并按步骤执行。你会看到它输出审查报告而不是泛泛地聊两句。第三步隐式匹配测试。直接输入这个 ALTER TABLE 语句加索引合理吗如果description写得够精准Codex 应该自动激活sql-migration-review技能。如果没触发说明描述里的触发词不够靠前或者被初始列表的字符预算截断了。我实测下来初始技能列表的字符数被限制在模型上下文窗口的约 2%或者上下文窗口未知时的 8000 字符。技能装多了之后Codex 会先缩短描述再不够就部分技能不显示。所以description一定要精简核心触发词放最前面。验证通过后你可以用config.toml管理技能的启用和禁用# 文件路径~/.codex/config.toml [[skills.config]] path /home/user/.agents/skills/sql-migration-review/SKILL.md enabled true [[skills.config]] path /home/user/.agents/skills/legacy-skill/SKILL.md enabled false改完配置需要重启 Codex 才生效。这个机制适合临时关掉不常用的技能避免它们挤占初始列表的字符预算。6. 本篇常见错排查技能更新后没生效是最常见的问题。Codex 会自动检测文件变更但有时候缓存没刷新重启一次基本能解决。如果重启还不行检查SKILL.md的 front matter 是不是有语法错误YAML 解析失败会导致整个技能被跳过。两个技能重名的情况也要注意。Codex 不会合并同名技能两者都会出现在选择器里容易混淆。建议在不同作用范围里避免用相同的name比如仓库级用proj-sql-review用户级用user-sql-review。隐式匹配不准确八成是description的问题。先检查描述里有没有明确写出使用场景和边界再把核心触发词前置。如果某个技能你根本不想让它被隐式调用直接在agents/openai.yaml里把allow_implicit_invocation设成false这样只有$skill-name显式调用才生效。初始技能列表被截断说明装的技能太多了。精简每个技能的description确保最核心的触发词在最前面。对于当前任务用不到的技能用config.toml暂时禁用等需要的时候再打开。还有一个容易忽略的点技能目录的符号链接。Codex 扫描时会跟随符号链接目标如果你用软链接把技能挂到.agents/skills/下确保链接目标路径是真实存在的否则技能不会被加载。如果你在接入过程中遇到模型通道报错比如 401 或 403先去https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite确认 Key 是否有效、额度是否充足。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里面有完整的参数说明和错误码对照。想先验证模型对话是否正常可以用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite快速测一轮。如果你打算长期跑编码任务或 Agent 工作流Coding Plan 页面https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里有针对性的套餐说明按自己的调用量选就行。技能骨架搭好之后建议先从一个最简单的纯指令技能开始跑通确认加载、触发、执行三个环节都没问题再往上加脚本和 MCP 依赖。这样出问题的时候排查范围小定位快。
