1. 从零写一个 Codex Skill 到底难在哪个人开发者的真实卡点Codex Skill 这个词最近在开发者圈子里出现得越来越频繁但很多人第一次听到时会把它和「插件」「MCP 服务」「自定义指令」混在一起。简单说Codex Skill 是一个把某类任务的步骤、规则、脚本和模板沉淀下来的「专用流程包」它最少只需要一个SKILL.md文件就能让 Codex 在遇到匹配场景时自动按你定义的流程干活。它适合谁适合那些每天重复写同类代码、重复排查同类报错、重复输出同类文档的个人开发者——你不需要写复杂的服务端逻辑只要把「怎么做这件事」写清楚就能复用。但真正动手时卡点往往不在「写」而在「写完之后怎么验证、怎么打包、怎么在另一台机器上装回去」。我见过太多人卡在三个地方第一SKILL.md的 YAML frontmatter 写错导致打包脚本直接报错第二本地调试时不知道该用什么请求去触发这个 Skill只能靠猜第三打包出来的.skill文件在目标机器上解压后不生效因为目录层级放错了。这篇就按「编写 → 本地调试 → 打包 → 分发」的完整链路走一遍并且用 TaoToken 的统一 Key 通道来完成调用验证这样你不需要在多个平台之间来回切换 Key。先说清楚一个前提Skill 本身是本地文件不依赖任何在线服务就能被 Codex 识别。但如果你想让 Skill 里的流程真正调用模型比如让 Codex 按你的规则生成内容就需要一个稳定的 API 通道。TaoToken 在这里扮演的角色是「统一 Key 通道」——你用一个 Key 就能访问多种模型省去为每个模型单独申请和管理的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 后面配置里会反复用到。这一节先把「Skill 是什么、适合谁、卡在哪」讲透下一节再进入 TaoToken 的前置准备。你如果已经写过一两个 Skill可以直接跳到第 3 节看可复制的配置片段。2. TaoToken 前置准备统一 Key 通道与 Codex 接入配置在写 Skill 之前先把调用通道打通这样你在本地调试 Skill 时才能立刻验证「模型是否按我的规则输出」。TaoToken 的核心价值是「一个 Key 走通多个模型」对个人开发者来说最直接的好处是不用维护一堆环境变量和配置文件。2.1 获取 API Key 与确认 Base URL第一步是拿到 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key复制出来先存到安全的地方。注意这个 Key 只在创建时完整显示一次后面配置里要用到。第二步是确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api这个地址在后面的settings.json、auth.json或环境变量里都会出现。注意不要写成带 UTM 参数的地址API 调用只认纯域名路径。2.2 Codex 的配置文件位置Codex 在个人电脑上的配置通常放在用户目录下的.codex文件夹里。Windows 下是C:\Users\你\.codex\macOS / Linux 下是~/.codex/这个目录里会有config.toml、auth.json等文件。Skill 的存放位置是$CODEX_HOME/skills/skill-name/其中$CODEX_HOME默认就是~/.codex。如果你改过环境变量以实际值为准。2.3 三件套Base URL Key Model ID不管你用的是 Codex CLI、Cline 还是其他支持 OpenAI 兼容接口的客户端接入 TaoToken 都离不开三件套配置项值说明Base URLhttps://taotoken.net/api所有请求的前缀API Key你在 api-keys 页面创建的那串放在 Authorization 头里Model ID例如gpt-4o、claude-3-5-sonnet等按你实际要用的模型填如果你用的是 Codex 的auth.json结构大致如下{ OPENAI_API_KEY: sk-你的TaoTokenKey, OPENAI_BASE_URL: https://taotoken.net/api }如果你用的是config.toml可以写成[model] provider openai api_key sk-你的TaoTokenKey base_url https://taotoken.net/api model gpt-4o注意不同版本的 Codex 对配置字段的命名可能略有差异以你本地codex --help或官方文档为准。但 Base URL 和 Key 这两项是固定的。2.4 验证通道是否打通配置完之后先别急着写 Skill用一条最简单的请求确认通道可用。如果你装了curl可以这样测curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 回复两个字通了}] }如果返回的 JSON 里有choices字段并且内容里出现了「通了」说明通道没问题。如果返回 401说明 Key 不对如果返回local proxy failed说明 Base URL 写错了或者网络层有问题。这两个报错后面第 5 节会专门讲。这一节把前置准备做完了下一节进入正题写SKILL.md。3. 可复制配置SKILL.md 模板与目录结构完整示例这一节是全文的核心我会给出一个可以直接复制、改改就能用的SKILL.md模板以及配套的目录结构。你照着做十分钟内就能有一个能跑的最小 Skill。3.1 目录结构最小与完整最小 Skill 只需要一个文件blogger-writer/ └── SKILL.md完整结构可以扩展为blogger-writer/ ├── SKILL.md ├── scripts/ │ └── gen_cover.py ├── references/ │ └── style-guide.md └── assets/ └── logo.svg注意除SKILL.md外其他目录都是可选的。scripts/放可执行脚本references/放参考文档assets/放图片、模板等静态资源。Codex 在触发 Skill 时会按需读取这些内容。3.2 初始化用官方脚本生成模板推荐用官方提供的init_skill.py来生成初始结构它会自动带上正确的 frontmatter 和基本框架。Windows 下脚本路径通常是C:\Users\你\.codex\skills\.system\skill-creator\scripts\init_skill.py初始化命令python C:\Users\你\.codex\skills\.system\skill-creator\scripts\init_skill.py \ blogger-writer \ --path C:\Users\你\.codex\skills执行后会生成C:\Users\你\.codex\skills\blogger-writer\SKILL.md如果你用的是 macOS 或 Linux把路径换成~/.codex/skills/.system/skill-creator/scripts/init_skill.py即可。3.3 SKILL.md 完整模板可直接复制下面这个模板是我实际在用的你可以直接复制把name和description改成你自己的场景。--- name: blogger-writer description: 编写简体中文 IT 技术博客工程实践、故障排查、教程、架构设计等用于撰写或润色技术文章、在项目中创建新的 Markdown 文档并根据文章主题生成配套的 SVG 封面。 --- # 技术博客写作 ## 概述 编写严谨、内容详实的简体中文 IT 技术博客并以 Markdown 形式交付然后设计与主题一致的 SVG 封面。 ## 工作流程 1) 澄清需求 - 确认主题、受众、范围与深度。 - 仅在必要时询问限制条件长度、语气、发布平台。 2) 收集事实与上下文 - 从对话中提取可验证的数据命令、日志、配置。 - 识别缺失信息必要时明确标注假设。 3) 规划结构不固定模板 - 使用清晰的小节与简短段落。 - 故障排查优先「问题→排查→修复」的流程教程采用可复现的步骤流。 4) Markdown 起草 - 使用准确语言、实操细节与可复现步骤。 - 原样呈现命令、日志或代码块。 - 在必要时强调注意事项、验证步骤与回滚说明。 5) 完成定稿 - 确保文章自洽且可操作。 - 需要时加入简洁结论或要点总结。 6) 生成主题封面SVG - 在 Markdown 完成后生成 1600x900 的 SVG。 - 使用清晰排版与与主题匹配的视觉要素。 - 不依赖外部资源保持 SVG 自包含。 - 标题已知时应体现于封面。 ## 写作规范 - 使用简体中文语气严谨。 - 以技术准确性为先避免营销化表述。 - 避免模糊描述使用上下文中的具体证据。 - 步骤描述需确定且可复现。 - 必要假设需明确标注。 ## 输出规则 - 默认在当前项目路径新建 Markdown 文档除非用户指定路径。 - 未明确要求时不得覆盖已有文件。 - Markdown 完成后生成配套 SVG 封面并与文章保存在同一目录。3.4 frontmatter 的两个硬性要求第一name必须与目录名一致。目录叫blogger-writername就必须是blogger-writer否则打包时会报错。第二description必须清楚描述「什么时候触发该 skill」。这句话是给 Codex 看的它决定了 Codex 在什么场景下会加载这个 Skill。建议用中文描述同时保留必要关键词提升触发率。比如上面模板里的description就包含了「技术博客」「Markdown」「SVG 封面」这些关键词。3.5 内容编写原则内容要简洁但具操作性。Codex 已经懂的内容不需要重复比如「什么是 Markdown」这种常识不用写。你要写的是「这个 Skill 特有的规则」流程步骤、输出格式、边界条件、回滚说明。不需要固定模板就不要强加模板。有些 Skill 适合用编号步骤有些适合用检查清单按场景来。3.6 用 TaoToken 验证 Skill 触发写完SKILL.md后重启 Codex然后用一个与description匹配的请求测试。比如帮我写一篇关于 Redis 缓存穿透的技术博客要包含排查步骤和代码示例。如果 Codex 按你定义的流程输出先澄清需求、再规划结构、最后生成 Markdown 和 SVG说明 Skill 已生效。如果没触发检查description是否覆盖了你的请求关键词。如果你在验证时遇到模型调用失败回到第 2 节的配置检查 Base URL 和 Key。TaoToken 的模型对话入口是 https://taotoken.net/models 你可以在那里先手动测一下模型是否可用再回到 Codex 里调试 Skill。这一节把配置和模板给全了下一节讲怎么验证请求和确认成功结果。4. 验证请求与成功结果从触发到打包的完整链路写完 Skill 只是第一步真正要确认的是「它能不能被正确触发、能不能按规则输出、能不能打包成可分发产物」。这一节按顺序走一遍验证链路。4.1 触发验证用匹配请求测试重启 Codex 后打开一个新的会话输入一个与description高度匹配的请求。以blogger-writer为例帮我写一篇关于 Docker 镜像瘦身的技术博客面向有经验的开发者包含具体命令和踩坑记录。观察 Codex 的响应。如果 Skill 生效你应该看到它先确认需求主题、受众、范围然后规划结构最后输出 Markdown。如果它直接开始写没有走流程说明 Skill 没被触发。触发失败最常见的原因是description写得太窄或太宽。太窄Codex 匹配不到太宽Codex 不确定该不该用。建议在description里同时包含「动作」和「对象」比如「编写技术博客」是动作「Markdown 文档」是对象。4.2 输出验证检查是否符合规则Skill 触发后检查输出是否符合你在SKILL.md里定义的规则。比如是否用了简体中文是否包含可复现的命令和代码块是否在最后生成了 SVG 封面是否默认在当前项目路径新建文档而不是覆盖已有文件如果某条规则没被执行回到SKILL.md检查那条规则的表述是否足够明确。Codex 对模糊表述的执行力有限比如「尽量用中文」就不如「必须用简体中文」明确。4.3 打包验证生成 .skill 文件确认 Skill 能正常工作后就可以打包了。打包脚本路径通常是C:\Users\你\.codex\skills\.system\skill-creator\scripts\package_skill.py打包命令推荐指定输出目录python C:\Users\你\.codex\skills\.system\skill-creator\scripts\package_skill.py \ C:\Users\你\.codex\skills\blogger-writer \ C:\Users\你\.codex\skills\dist成功后生成C:\Users\你\.codex\skills\dist\blogger-writer.skill注意打包会校验SKILL.md的 YAML 格式、目录结构、描述完整性。如果 frontmatter 里有拼写错误或者name与目录名不一致打包会直接失败并给出报错信息。4.4 Windows 编码问题与 PYTHONUTF8Windows 默认编码可能导致打包脚本读取SKILL.md失败报错通常是UnicodeDecodeError。解决办法是临时设置环境变量$env:PYTHONUTF81 python C:\Users\你\.codex\skills\.system\skill-creator\scripts\package_skill.py C:\Users\你\.codex\skills\blogger-writer C:\Users\你\.codex\skills\dist设置PYTHONUTF81后Python 会以 UTF-8 读取文件中文 frontmatter 就不会出问题。4.5 分发验证在目标机器上安装.skill文件本质是 zip 包。分发后在目标机器上解压到$CODEX_HOME/skills/skill-name即可。Windows 安装示例$skill C:\path\to\blogger-writer.skill $dest $env:USERPROFILE\.codex\skills\blogger-writer New-Item -ItemType Directory -Force -Path $dest | Out-Null Expand-Archive -Path $skill -DestinationPath $dest -Force完成后重启 Codex用同样的匹配请求测试触发。如果触发成功说明分发链路完整。4.6 用 TaoToken 做端到端验证如果你想确认「Skill 模型调用」整条链路都通可以在 Skill 触发后让 Codex 调用模型生成一段内容。这时 TaoToken 的通道就派上用场了。你可以在 https://taotoken.net/models 先确认模型可用再回到 Codex 里跑完整流程。如果模型调用返回reading choices相关报错通常是响应格式解析问题检查 Base URL 是否写成了https://taotoken.net/api而不是其他路径。这一节把验证链路走完了下一节集中讲常见报错和排查方法。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节把个人开发者在写 Codex Skill 和接入 TaoToken 时最常遇到的四类报错集中讲一遍。每个报错都给出「现象 → 原因 → 解决」的结构你可以对照自己的情况排查。5.1 401 UnauthorizedKey 不对或没带上现象请求返回401 Unauthorized响应体里通常有invalid_api_key或authentication_error。原因有三种第一Key 复制时漏了字符或多了空格第二请求头里没带Authorization: Bearer sk-xxx第三Key 已被删除或过期。解决回到 https://taotoken.net/api-keys 重新创建一个 Key复制时注意不要带前后空格。然后在请求里确认头部格式Authorization: Bearer sk-你的TaoTokenKey如果你用的是auth.json确认字段名是OPENAI_API_KEY值以sk-开头。5.2 local proxy failedBase URL 写错或网络层问题现象请求返回local proxy failed或类似的连接错误。原因Base URL 写错了。常见错误是写成了https://taotoken.net/api/v1或https://taotoken.net正确的应该是https://taotoken.net/api注意末尾没有斜杠也没有/v1。Codex 或客户端会自动在 Base URL 后面拼接/v1/chat/completions等路径。解决检查配置文件里的base_url字段改成https://taotoken.net/api。如果你用的是环境变量确认OPENAI_BASE_URL的值正确。5.3 reading choices响应格式解析失败现象客户端报reading choices或cannot read property choices of undefined。原因模型返回的响应格式与客户端预期不一致。常见于 Base URL 写错导致请求打到了非兼容接口或者模型 ID 写错导致返回了错误信息。解决先用curl直接测一次确认返回的 JSON 里有choices字段curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d {model: gpt-4o, messages: [{role: user, content: hi}]}如果curl能返回正常 JSON但客户端报错说明客户端的配置有问题。检查 Model ID 是否拼写正确以及客户端是否支持 OpenAI 兼容接口。5.4 OAuth 相关报错认证方式不匹配现象报错里出现OAuth、token exchange failed或invalid_grant。原因你用的客户端默认走 OAuth 认证但 TaoToken 用的是 API Key 认证。两者不匹配。解决在客户端设置里切换到「API Key」模式填入 TaoToken 的 Key 和 Base URL。如果你用的是 Codex CLI确认auth.json里用的是OPENAI_API_KEY而不是 OAuth 相关字段。5.5 打包报错frontmatter 格式问题现象package_skill.py报错提示 YAML 解析失败或name与目录名不一致。原因SKILL.md顶部的 frontmatter 格式不对。常见错误包括---没写全、name与目录名不一致、description里有未转义的特殊字符。解决对照第 3 节的模板检查 frontmatter。确保第一行是---name与目录名完全一致description是单行字符串没有换行frontmatter 结束后有---5.6 三件套检查清单如果你在接入 TaoToken 时遇到问题先对照这个清单检查项正确值常见错误Base URLhttps://taotoken.net/api多了/v1或末尾斜杠API Keysk-开头漏字符、多空格、已删除Model ID如gpt-4o拼写错误、大小写不对这三项确认无误后大部分接入问题都能解决。如果还有问题可以到 https://taotoken.net/doc 查接入文档里面有更详细的配置说明。这一节把常见报错讲完了下一节给出 CTA 分流和后续建议。6. 从 Skill 到工作流长期编码与 Agent 场景的落地建议写到这里你已经走完了「编写 → 调试 → 打包 → 分发」的完整链路。最后这一节不讲总结讲几个实际落地时的建议以及不同场景下该用哪个入口。6.1 优先沉淀高频、流程固定的任务不是所有任务都值得做成 Skill。判断标准很简单这个任务你是不是每周至少做一次流程是不是基本固定如果是就值得沉淀。比如「写技术博客」「排查某类报错」「生成某类配置文件」都是典型的高频固定任务。反过来一次性的、流程每次都不一样任务做成 Skill 反而增加维护成本。6.2 逐步沉淀脚本与模板最小 Skill 只需要SKILL.md但当你发现某个步骤反复需要执行同样的脚本时就可以把它放到scripts/目录里。比如生成 SVG 封面的脚本、格式化 Markdown 的脚本、校验配置的脚本。references/适合放风格指南、检查清单、决策约束这类文档。assets/适合放 logo、模板文件、示例图片。6.3 分发检查清单在把.skill文件发给别人之前对照这个清单检查一遍SKILL.md的name与目录名一致description清楚描述了触发场景打包命令执行成功生成了.skill文件在另一台机器上解压后重启 Codex 能触发如果 Skill 依赖模型调用确认目标机器也配置了 TaoToken 的 Base URL 和 Key6.4 不同场景的入口选择如果你只是偶尔验证一下模型输出用模型对话入口就够了https://taotoken.net/models 。如果你在长期做编码任务、需要稳定的 API 通道建议用 Coding Planhttps://taotoken.net/coding-plan 。如果你需要管理多个 Key、查看用量用控制台https://taotoken.net/console 。如果你要创建新的 API Key直接去https://taotoken.net/api-keys 。接入文档在https://taotoken.net/doc 。6.5 一个实际的工作流示例我现在的工作流是这样的平时遇到重复任务先记在备忘录里周末花半小时把它写成SKILL.md用 TaoToken 的通道在本地验证触发和输出确认没问题后用package_skill.py打包把.skill文件存到云盘换机器时直接解压安装。这套流程跑下来一个 Skill 从想法到可用大概只需要一小时。积累十几个 Skill 之后你会发现很多以前要手动做的事现在一句话就能触发。如果你还没开始建议从最简单的「写技术博客」Skill 入手照着第 3 节的模板改一改先跑通一遍完整链路。跑通之后再按自己的需求扩展scripts/和references/。
