1. codex 的 skills 到底是什么为什么值得折腾如果你刚开始用 codex 写代码大概率会遇到一个尴尬模型能力很强但每次都要把同一套背景、同一套规范、同一套流程重新讲一遍。比如你想让它按公司模板生成 PPT 大纲、按固定格式写周报、按团队约定生成接口文档每次都得复制粘贴一大段提示词。skills 就是来解决这个问题的。你可以把 skill 理解成「给 codex 装的一个小插件包」。它本质上是一个目录里面放一份SKILL.md说明文件可能还有脚本、模板、示例。codex 在对话时如果判断当前任务匹配某个 skill 的描述就会自动加载它或者你手动用/技能名直接调用。装一次之后这个项目甚至整台电脑都能反复用。它适合谁三类人最明显一是天天写重复性文档、报告、模板的开发者二是团队里想把编码规范、提交规范固化下来的 Tech Lead三是刚接触 codex、想让 AI 输出更稳定、更少「自由发挥」的新手。这篇就按「从零配置到实战验证」的路线走一遍交付可复制的config.toml骨架、skills 目录结构以及装完之后怎么确认它真的生效。需要先说明一点codex 的 skills 分两个层级项目级和电脑级。项目级只在你当前仓库里生效适合团队共享电脑级在你整台机器的任何目录都能用适合个人常用工具。搞混这两个路径是新手最常见的翻车点后面会专门讲。2. 前置准备TaoToken 接入与 codex 环境确认在装 skill 之前得先保证 codex 本身能正常跑起来、能正常调用模型。这一步没通后面装再多 skill 也是白搭。我这边用的是 TaoToken 提供的接入方式官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 入口是 https://taotoken.net/api 。它的作用是给你一个统一的模型调用入口codex 通过它去请求模型。你需要在控制台里创建一个 API Key然后把它填进 codex 的配置里。先确认你的 codex 版本和配置目录。不同系统路径不一样系统codex 配置目录Linux / macOS~/.codex/WindowsC:\Users\你的用户名\.codex\进去之后应该能看到config.toml如果没有就手动建一个。这个文件是 codex 的核心配置模型、API 地址、skills 开关都在这里。注意skills 目录和config.toml是同级关系都在.codex下面。很多人把 skills 放错位置导致 codex 根本扫不到这是排查时第一个要看的点。创建 API Key 的入口在控制台的 API Keys 页面拿到 key 之后先别急着写进配置建议先用一条 curl 验证 key 本身是通的避免后面把「key 无效」误判成「skill 没生效」。curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer 你的API_KEY返回一个模型列表的 JSON就说明 key 和网络都没问题。这一步过了再往下走。3. 可复制的 config.toml 骨架与 skills 目录结构这一节是全文的核心直接给你能抄的配置。先看config.toml骨架。下面这份是精简可用版字段按需增减# ~/.codex/config.toml # 模型接入配置 model gpt-4o model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY # skills 相关 [skills] enabled true # 电脑级 skills 目录默认就是这个可显式写出 user_dir ~/.codex/skills # 项目级 skills 目录相对项目根目录 project_dir .codex/skillsAPI Key 不建议直接写进 toml用环境变量更安全# Linux / macOS写进 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEY你的API_KEY # Windows PowerShell setx TAOTOKEN_API_KEY 你的API_KEY然后是 skills 目录结构。一个标准 skill 长这样.codex/skills/ └── ppt-generator/ ├── SKILL.md # 必须描述技能用途和触发条件 ├── templates/ │ └── outline.md # 可选模板文件 └── scripts/ └── build.py # 可选辅助脚本SKILL.md是灵魂codex 靠它判断「这个 skill 是干嘛的、什么时候用」。一个最小可用的SKILL.md大概长这样--- name: ppt-generator description: 根据主题生成结构化的 PPT 大纲包含封面、目录、章节页和总结页 --- # PPT 大纲生成器 当用户要求生成 PPT 大纲、演示文稿结构时使用本技能。 ## 输出格式 1. 封面页标题 副标题 2. 目录页列出 3-5 个章节 3. 每个章节标题 3 条要点 4. 总结页核心结论description写得越具体codex 自动匹配越准。如果你希望它只在手动调用时触发可以把描述写得窄一点靠/ppt-generator手动唤起。项目级和电脑级的区别用一张表说清楚层级路径生效范围适用场景电脑级~/.codex/skills/整台机器所有项目个人常用工具项目级项目根目录/.codex/skills/仅当前项目团队共享、项目专属规范提示项目级 skills 建议提交到 git这样团队成员拉下来就自动有了不用每个人手动装。4. 安装 skill 的两种方式让 codex 代劳 vs 手动放置装 skill 有两条路一条是懒人路线一条是手动路线。我建议新手先走懒人路线跑通之后再理解手动路径。方式一让 codex 自己装。你直接把 skill 的仓库地址或者说明页丢给它然后给一句明确的提示词比如「把这个 skill 安装到当前项目级别」。codex 会自己去读页面、下载、放到正确路径。这种方式对不懂目录结构的人最友好缺点是你要信任它放对了位置装完还是得验证。方式二手动放置。从 skill 市场或者 GitHub 仓库下载 zip解压后把整个文件夹挪到对应路径。这里的关键是「文件夹名就是技能名」别改乱。# 电脑级安装Linux / macOS mkdir -p ~/.codex/skills cp -r ~/Downloads/ppt-generator ~/.codex/skills/ # 项目级安装 mkdir -p 你的项目/.codex/skills cp -r ~/Downloads/ppt-generator 你的项目/.codex/skills/Windows 下手动放置# 电脑级 New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codex\skills Copy-Item -Recurse $env:USERPROFILE\Downloads\ppt-generator $env:USERPROFILE\.codex\skills\ # 项目级 Copy-Item -Recurse $env:USERPROFILE\Downloads\ppt-generator .\你的项目\.codex\skills\放完之后目录应该是这样的注意SKILL.md必须直接躺在技能文件夹里不能多套一层~/.codex/skills/ppt-generator/SKILL.md 正确 ~/.codex/skills/ppt-generator/ppt-generator/SKILL.md 多套了一层多套一层是手动安装最高频的错误codex 扫不到表现就是「skill 明明放了却用不了」。5. 验证 skill 是否生效具体命令与成功结果装完不验证等于没装。这一节给你可执行的验证步骤。第一步重启 codex。skills 是在启动时扫描的热加载不一定生效先退出再进。第二步查看已加载的 skills 列表。codex 一般有类似/skills或者/help的命令输入后应该能看到你刚装的技能名出现在列表里。如果列表里没有直接跳到下一节排查。第三步手动调用测试。在对话里输入/ppt-generator注意输入/之后通常会有自动补全按 Tab 能补全出技能名说明它被识别了。 /ppt-generator 帮我生成一个「AI 技术分享」的 PPT 大纲如果 skill 生效codex 会按照SKILL.md里定义的格式输出而不是自由发挥。你可以对比一下没装 skill 时它可能给你一段散文式描述装了之后应该严格出现封面、目录、章节、总结这种结构化输出。第四步验证自动触发。不手动打/直接说「帮我做个关于 XX 的 PPT 大纲」看它会不会自动匹配到 skill。这一步验证的是description写得够不够准。成功的结果长这样输出结构和你SKILL.md里定义的完全一致章节数量、要点条数都对得上。如果格式对不上说明 skill 没被加载codex 在用默认行为回答。6. 本篇常见错误排查清单把踩过的坑集中列一下按出现频率排序。错误一skill 放了但列表里没有。九成是路径问题。检查SKILL.md是不是直接躺在技能文件夹根目录检查是不是放到了.codex/skills外面检查项目级是不是放到了项目根目录而不是子目录。错误二/技能名补全不出来。技能名默认取文件夹名如果你文件夹叫ppt_generator但你以为叫ppt-generator补全就对不上。统一用文件夹名调用。错误三skill 加载了但输出格式不对。问题在SKILL.md的description或正文描述太模糊。codex 不知道什么时候该用它或者用了但没理解输出要求。把输出格式写得更死板一点用编号列表明确每一页要什么。错误四项目级 skill 在别的目录用不了。这是正常的项目级只在当前项目生效。想全局用就装到电脑级路径。错误五改了SKILL.md但没变化。改完要重启 codex它不会实时监听文件变化。错误六API 报错被误判成 skill 问题。如果 codex 连模型都调不通skill 自然也不会工作。先用第 2 节的 curl 确认 API 通不通再排查 skill。注意排查顺序永远是「先确认 API 通 → 再确认 skill 被扫描到 → 最后确认输出格式」。顺序反了会浪费大量时间。7. 下一步把 skill 用进真实工作流跑通第一个 skill 之后你可以开始把它接进日常。比如把团队的代码规范写成一个 skill每次让 codex 生成代码时自动套用把周报模板做成 skill周五直接/weekly-report一键生成。如果你打算长期用 codex 做编码和 Agent 类任务可以了解一下 Coding Plan 这类长期方案入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 适合需要稳定调用、频繁跑 skill 的场景。想先验证模型对话效果可以直接用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试几条 prompt。接入过程中如果遇到配置问题接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后一个实用建议skill 不要贪多。先装一两个真正高频的用顺了再扩。装一堆用不上的 skill反而会让 codex 的自动匹配变乱输出稳定性下降。 codex安装和使用skills：从零配置到实战验证的完整指南
1. codex 的 skills 到底是什么为什么值得折腾如果你刚开始用 codex 写代码大概率会遇到一个尴尬模型能力很强但每次都要把同一套背景、同一套规范、同一套流程重新讲一遍。比如你想让它按公司模板生成 PPT 大纲、按固定格式写周报、按团队约定生成接口文档每次都得复制粘贴一大段提示词。skills 就是来解决这个问题的。你可以把 skill 理解成「给 codex 装的一个小插件包」。它本质上是一个目录里面放一份SKILL.md说明文件可能还有脚本、模板、示例。codex 在对话时如果判断当前任务匹配某个 skill 的描述就会自动加载它或者你手动用/技能名直接调用。装一次之后这个项目甚至整台电脑都能反复用。它适合谁三类人最明显一是天天写重复性文档、报告、模板的开发者二是团队里想把编码规范、提交规范固化下来的 Tech Lead三是刚接触 codex、想让 AI 输出更稳定、更少「自由发挥」的新手。这篇就按「从零配置到实战验证」的路线走一遍交付可复制的config.toml骨架、skills 目录结构以及装完之后怎么确认它真的生效。需要先说明一点codex 的 skills 分两个层级项目级和电脑级。项目级只在你当前仓库里生效适合团队共享电脑级在你整台机器的任何目录都能用适合个人常用工具。搞混这两个路径是新手最常见的翻车点后面会专门讲。2. 前置准备TaoToken 接入与 codex 环境确认在装 skill 之前得先保证 codex 本身能正常跑起来、能正常调用模型。这一步没通后面装再多 skill 也是白搭。我这边用的是 TaoToken 提供的接入方式官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 入口是 https://taotoken.net/api 。它的作用是给你一个统一的模型调用入口codex 通过它去请求模型。你需要在控制台里创建一个 API Key然后把它填进 codex 的配置里。先确认你的 codex 版本和配置目录。不同系统路径不一样系统codex 配置目录Linux / macOS~/.codex/WindowsC:\Users\你的用户名\.codex\进去之后应该能看到config.toml如果没有就手动建一个。这个文件是 codex 的核心配置模型、API 地址、skills 开关都在这里。注意skills 目录和config.toml是同级关系都在.codex下面。很多人把 skills 放错位置导致 codex 根本扫不到这是排查时第一个要看的点。创建 API Key 的入口在控制台的 API Keys 页面拿到 key 之后先别急着写进配置建议先用一条 curl 验证 key 本身是通的避免后面把「key 无效」误判成「skill 没生效」。curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer 你的API_KEY返回一个模型列表的 JSON就说明 key 和网络都没问题。这一步过了再往下走。3. 可复制的 config.toml 骨架与 skills 目录结构这一节是全文的核心直接给你能抄的配置。先看config.toml骨架。下面这份是精简可用版字段按需增减# ~/.codex/config.toml # 模型接入配置 model gpt-4o model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY # skills 相关 [skills] enabled true # 电脑级 skills 目录默认就是这个可显式写出 user_dir ~/.codex/skills # 项目级 skills 目录相对项目根目录 project_dir .codex/skillsAPI Key 不建议直接写进 toml用环境变量更安全# Linux / macOS写进 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEY你的API_KEY # Windows PowerShell setx TAOTOKEN_API_KEY 你的API_KEY然后是 skills 目录结构。一个标准 skill 长这样.codex/skills/ └── ppt-generator/ ├── SKILL.md # 必须描述技能用途和触发条件 ├── templates/ │ └── outline.md # 可选模板文件 └── scripts/ └── build.py # 可选辅助脚本SKILL.md是灵魂codex 靠它判断「这个 skill 是干嘛的、什么时候用」。一个最小可用的SKILL.md大概长这样--- name: ppt-generator description: 根据主题生成结构化的 PPT 大纲包含封面、目录、章节页和总结页 --- # PPT 大纲生成器 当用户要求生成 PPT 大纲、演示文稿结构时使用本技能。 ## 输出格式 1. 封面页标题 副标题 2. 目录页列出 3-5 个章节 3. 每个章节标题 3 条要点 4. 总结页核心结论description写得越具体codex 自动匹配越准。如果你希望它只在手动调用时触发可以把描述写得窄一点靠/ppt-generator手动唤起。项目级和电脑级的区别用一张表说清楚层级路径生效范围适用场景电脑级~/.codex/skills/整台机器所有项目个人常用工具项目级项目根目录/.codex/skills/仅当前项目团队共享、项目专属规范提示项目级 skills 建议提交到 git这样团队成员拉下来就自动有了不用每个人手动装。4. 安装 skill 的两种方式让 codex 代劳 vs 手动放置装 skill 有两条路一条是懒人路线一条是手动路线。我建议新手先走懒人路线跑通之后再理解手动路径。方式一让 codex 自己装。你直接把 skill 的仓库地址或者说明页丢给它然后给一句明确的提示词比如「把这个 skill 安装到当前项目级别」。codex 会自己去读页面、下载、放到正确路径。这种方式对不懂目录结构的人最友好缺点是你要信任它放对了位置装完还是得验证。方式二手动放置。从 skill 市场或者 GitHub 仓库下载 zip解压后把整个文件夹挪到对应路径。这里的关键是「文件夹名就是技能名」别改乱。# 电脑级安装Linux / macOS mkdir -p ~/.codex/skills cp -r ~/Downloads/ppt-generator ~/.codex/skills/ # 项目级安装 mkdir -p 你的项目/.codex/skills cp -r ~/Downloads/ppt-generator 你的项目/.codex/skills/Windows 下手动放置# 电脑级 New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codex\skills Copy-Item -Recurse $env:USERPROFILE\Downloads\ppt-generator $env:USERPROFILE\.codex\skills\ # 项目级 Copy-Item -Recurse $env:USERPROFILE\Downloads\ppt-generator .\你的项目\.codex\skills\放完之后目录应该是这样的注意SKILL.md必须直接躺在技能文件夹里不能多套一层~/.codex/skills/ppt-generator/SKILL.md 正确 ~/.codex/skills/ppt-generator/ppt-generator/SKILL.md 多套了一层多套一层是手动安装最高频的错误codex 扫不到表现就是「skill 明明放了却用不了」。5. 验证 skill 是否生效具体命令与成功结果装完不验证等于没装。这一节给你可执行的验证步骤。第一步重启 codex。skills 是在启动时扫描的热加载不一定生效先退出再进。第二步查看已加载的 skills 列表。codex 一般有类似/skills或者/help的命令输入后应该能看到你刚装的技能名出现在列表里。如果列表里没有直接跳到下一节排查。第三步手动调用测试。在对话里输入/ppt-generator注意输入/之后通常会有自动补全按 Tab 能补全出技能名说明它被识别了。 /ppt-generator 帮我生成一个「AI 技术分享」的 PPT 大纲如果 skill 生效codex 会按照SKILL.md里定义的格式输出而不是自由发挥。你可以对比一下没装 skill 时它可能给你一段散文式描述装了之后应该严格出现封面、目录、章节、总结这种结构化输出。第四步验证自动触发。不手动打/直接说「帮我做个关于 XX 的 PPT 大纲」看它会不会自动匹配到 skill。这一步验证的是description写得够不够准。成功的结果长这样输出结构和你SKILL.md里定义的完全一致章节数量、要点条数都对得上。如果格式对不上说明 skill 没被加载codex 在用默认行为回答。6. 本篇常见错误排查清单把踩过的坑集中列一下按出现频率排序。错误一skill 放了但列表里没有。九成是路径问题。检查SKILL.md是不是直接躺在技能文件夹根目录检查是不是放到了.codex/skills外面检查项目级是不是放到了项目根目录而不是子目录。错误二/技能名补全不出来。技能名默认取文件夹名如果你文件夹叫ppt_generator但你以为叫ppt-generator补全就对不上。统一用文件夹名调用。错误三skill 加载了但输出格式不对。问题在SKILL.md的description或正文描述太模糊。codex 不知道什么时候该用它或者用了但没理解输出要求。把输出格式写得更死板一点用编号列表明确每一页要什么。错误四项目级 skill 在别的目录用不了。这是正常的项目级只在当前项目生效。想全局用就装到电脑级路径。错误五改了SKILL.md但没变化。改完要重启 codex它不会实时监听文件变化。错误六API 报错被误判成 skill 问题。如果 codex 连模型都调不通skill 自然也不会工作。先用第 2 节的 curl 确认 API 通不通再排查 skill。注意排查顺序永远是「先确认 API 通 → 再确认 skill 被扫描到 → 最后确认输出格式」。顺序反了会浪费大量时间。7. 下一步把 skill 用进真实工作流跑通第一个 skill 之后你可以开始把它接进日常。比如把团队的代码规范写成一个 skill每次让 codex 生成代码时自动套用把周报模板做成 skill周五直接/weekly-report一键生成。如果你打算长期用 codex 做编码和 Agent 类任务可以了解一下 Coding Plan 这类长期方案入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 适合需要稳定调用、频繁跑 skill 的场景。想先验证模型对话效果可以直接用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试几条 prompt。接入过程中如果遇到配置问题接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后一个实用建议skill 不要贪多。先装一两个真正高频的用顺了再扩。装一堆用不上的 skill反而会让 codex 的自动匹配变乱输出稳定性下降。