如何“训练” Codex 的 Skill：从 SKILL.md 到 config.toml 的实战配置

1. 为什么你的 Codex 总是“记不住”流程先说清楚一件事这里讲的“训练” Codex Skill不是去微调模型参数也不需要准备数据集和 GPU。它更像是给 Codex 写一份“专业上岗手册”——把重复的流程、固定的规范、容易漏掉的步骤沉淀成一个独立目录。之后只要任务命中这个 SkillCodex 就会自动加载对应说明按你设定的流程干活。我见过太多人每次对话都要重新交代一遍先读哪个文件、命令怎么跑、输出格式长什么样、哪些坑不能踩。这种重复劳动做多了效率反而比手动还低。Skill 要解决的就是这个问题可复用提示词 操作流程 脚本工具 参考资料 模板资源打包成一个目录。适合写成 Skill 的任务通常有几个特征经常重复做、流程比较固定、有明确输入输出、需要特定领域知识、普通提示词容易漏步骤。比如自动生成 CSDN 技术文章、按团队规范写接口文档、处理固定格式的报表、按模板排版 LaTeX、生成固定风格的 PPT、做代码 Review。反过来一次性临时需求、没有稳定流程的开放闲聊、一句提示词就能搞定的小任务都不值得写成 Skill。这篇会从 SKILL.md 骨架讲到 config.toml 配置再演示通过 TaoToken 统一 Key/API 通道接入后的验证动作确认技能被正确加载与调用。全程可跟做代码和配置都能直接复制。2. TaoToken 前置统一 Key 与 API 通道在写 Skill 之前先把接入层搞定。Codex 这类工具在调用模型时需要稳定的 API 通道和统一的 Key 管理。TaoToken 在这里扮演的角色就是统一入口一个 Key 走通模型对话、编码计划、控制台管理不用在多个平台之间来回切换配置。你需要先拿到 API Key。访问控制台创建控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keysAPI 基础地址是https://taotoken.net/api注意这个地址不带 UTM 参数直接用于代码里的 base_url 配置。提示Key 只创建一次就够后续所有 Skill 和工具共用同一个 Key。不要把 Key 写进 SKILL.md 或提交到 Git 仓库用环境变量管理。如果你还没决定用哪个模型可以先在模型对话里试一下效果模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat长期做编码和 Agent 任务的建议直接看 Coding Plan额度更划算Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan接入文档在这里配置细节以文档为准接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc3. SKILL.md 骨架从 frontmatter 到正文一个标准 Skill 目录长这样只有 SKILL.md 是必须的其他按需添加my-skill/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── scripts/ │ └── helper.py ├── references/ │ └── guide.md └── assets/ └── template.mdSKILL.md 分两部分YAML frontmatter 和 Markdown 正文。frontmatter 里最关键的是name和description。name用短横线小写命名一个 Skill 只做一类事description决定 Codex 什么时候触发这个 Skill必须同时写清楚“能做什么”和“用户说什么时触发”。--- name: csdn-writer description: Create, polish, and format Simplified Chinese CSDN-ready Markdown technical articles for software installation, debugging, programming tutorials, AI tools, and engineering notes. Use when the user asks to write a CSDN article, generate a Markdown blog post, convert notes into a publishable tutorial, or polish technical content for CSDN. --- # CSDN Writer ## Workflow 1. Identify the topic, target reader, and source material. 2. Extract concrete facts from provided files, logs, or notes. 3. Build a practical article outline before drafting. 4. Write a complete Markdown article with clear headings. 5. Add code blocks, commands, and checklists when useful. 6. Save the final article as a .md file when working locally. ## Style - Write in Simplified Chinese by default. - Use a practical tutorial tone. - Do not invent facts, versions, commands, links, or citations. ## Resources - Use references/csdn-style.md when polishing article style. - Use assets/article-template.md when the user asks for a standard template. - Use scripts/check_markdown.py before final delivery if it exists.正文不要写成教材。Codex 本身知道通用知识你只需要补充它不知道的流程、约束、资源和项目规范。常见错误是把触发条件写在正文里——正文只有在 Skill 已经触发后才会加载所以“什么时候用”必须写进 description。4. config.toml 可复制片段与目录初始化Skill 写好后需要让 Codex 能发现它。默认路径是${CODEX_HOME:-$HOME/.codex}/skills。手动创建目录也行但至少要有 SKILL.mdmkdir -p ${CODEX_HOME:-$HOME/.codex}/skills/csdn-writer cd ${CODEX_HOME:-$HOME/.codex}/skills/csdn-writer touch SKILL.mdWindows PowerShell 对应写法New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codex\skills\csdn-writer Set-Location $env:USERPROFILE\.codex\skills\csdn-writer New-Item -ItemType File -Force -Path SKILL.md接下来是 config.toml。Codex 的配置文件通常放在~/.codex/config.toml把模型通道指向 TaoToken 的 API 地址Key 从环境变量读取# ~/.codex/config.toml model gpt-4o model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [skills] # Skill 根目录Codex 会扫描该目录下的子目录 path ~/.codex/skills环境变量在 shell 里设置不要写进配置文件export TAOTOKEN_API_KEYsk-你的KeyWindows PowerShell$env:TAOTOKEN_API_KEY sk-你的Key注意base_url用https://taotoken.net/api不要加多余路径。env_key指向的环境变量名要和实际设置的一致否则会报鉴权失败。5. 验证请求确认 Skill 被正确加载配置完成后先做一次最小验证确认 API 通道通、Skill 能被发现。第一步验证通道curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 300返回模型列表说明 Key 和通道正常。第二步验证 Skill 目录结构find ${CODEX_HOME:-$HOME/.codex}/skills -maxdepth 2 -name SKILL.md应该能看到csdn-writer/SKILL.md。第三步用真实任务触发 Skill在 Codex 里输入使用 csdn-writer帮我把这段 Docker 安装说明写成 CSDN Markdown。观察几个关键点Skill 是否被正确触发、是否按 Workflow 顺序执行、是否读取了正确的 reference、输出格式是否符合预期、有没有漏掉保存.md文件这一步。如果触发失败优先检查 description 是否包含用户可能使用的关键词。一个可复用的 Markdown 校验脚本放在scripts/check_markdown.pyimport sys, re def check(path): text open(path, encodingutf-8).read() issues [] if not re.search(r^#\s, text, re.M): issues.append(缺少一级标题) if text.count() % 2 ! 0: issues.append(代码块未闭合) if re.search(r\]\(\s*\), text): issues.append(存在空链接) return issues if __name__ __main__: for p in sys.argv[1:]: errs check(p) print(f{p}: {OK if not errs else errs})运行python scripts/check_markdown.py article.md输出 OK 就说明格式没问题。6. 本篇常见错排查Skill 没触发九成是 description 太短或没写触发场景。只写Write articles.这种Codex 判断不了何时使用。把用户可能说的关键词都列进去比如“CSDN 文章”“Markdown 博客”“润色技术文”。鉴权失败 401检查TAOTOKEN_API_KEY是否在当前 shell 生效env_key名字是否和实际环境变量一致。用echo $TAOTOKEN_API_KEY确认。base_url 配错必须是https://taotoken.net/api多写或少写路径都会导致请求 404。Skill 目录没被扫描确认 config.toml 里[skills]的path指向正确且每个 Skill 是独立子目录SKILL.md 在子目录根下。Codex 编造链接或版本号在 SKILL.md 的 Style 里加一条Do not invent facts, versions, commands, links, or citations实测能明显减少胡编。SKILL.md 越写越长说明它承担了太多内容。把详细资料拆到references/SKILL.md 只保留导航比如Read references/troubleshooting.md when debugging article quality.。脚本反复被重写把稳定逻辑固化到scripts/比如格式转换、Markdown 校验、批量处理。脚本可执行、可测试、结果稳定还能减少上下文占用。7. 迭代与接入入口Skill 不是一次写完就完事。最有效的迭代方式是从真实失败案例改起记录 Codex 每次都忘记保存文件就在 Workflow 最后加一条保存步骤发现它编造参考链接就在 Style 里加禁止编造。不要凭空优化用真实任务测试后再改。一个 Skill 不要试图覆盖所有任务。super-assistant这种万能 Skill 触发不准、执行不稳。拆成csdn-writer、api-doc-writer、frontend-builder这种聚焦的触发更准、执行更稳。接入层统一用 TaoToken一个 Key 走通所有 Skill 和工具。需要新建 Key 或管理额度走控制台和 API Keys 页面控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc长期跑编码和 Agent 任务Coding Plan 的额度更合适Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan想先验证模型效果再决定直接在模型对话里试模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后留一个实用技巧每次改完 SKILL.md用真实任务跑一遍重点看它有没有漏掉 Workflow 里的步骤。漏了就在对应步骤后面加一句明确的约束比在开头写一堆背景说明管用得多。