先问大家一个问题你拿到 Codex 之后是不是先往 Skill 目录里塞了十几个别人分享的技能包什么前端生成、PPT 排版、视频脚本、数据分析、数学建模看到名字觉得有用就全装进去。结果真正用的时候要么 Agent 半天不调用 Skill要么调用了却给你一顿组合拳式的乱输出最后还得自己一行一行改。这不是某个人的问题而是最近 Codex 和 Skill 生态火起来之后非常普遍的现象。很多人以为“Skill 装得多Codex 就能干更多的活”但实际用下来会发现装得多≠装得对甚至装得多反而更慢、更乱、更费 token。这篇文章我不会劝你“千万别用 Skill”而是想把 Codex 和 Skill 的真实关系讲清楚Skill 到底是什么、为什么不能全装、如何按需选择以及如何自己写一个真正能用的 Skill。全文会用“用 Codex 辅助做视频”这个场景贯穿从零演示一个“视频脚本生成”Skill 的创建和调用流程最后附上我整理的一批排错清单和最佳实践。新手可以照着配置有基础的可以直接跳到第 4 节看实战。1. 背景与核心概念1.1 Codex 是什么Codex 是 OpenAI 推出的编程智能体工具常见形态包括 CLI、桌面客户端和 IDE 插件。它和普通代码补全工具最大的区别是Codex 不只是“接着你写的代码继续写”而是能理解你的完整任务读取项目结构修改多个文件运行命令然后根据执行结果继续调整。简单说你给它一个目标它能像一名初级工程师一样去拆解任务、改代码、跑测试、修报错。在开发圈里Codex 经常被拿来和 Claude Code、Cursor 等工具对比。它们底层思路类似都是“大模型 工具调用 项目上下文”。其中 Skill 机制是最近热度很高的扩展方式。1.2 Skill 到底是什么Skill 可以理解为一个“技能包”。它通常是一个文件夹里面有一个说明文件常见命名是SKILL.md或PROMPT.md也可能附带脚本、模板、参考文档。这个说明文件会告诉 Agent这个 Skill 是干什么的。在什么场景下应该启用它。启用后按照什么步骤执行。需要调用哪些脚本或外部工具。举个例子你安装了一个“视频脚本生成”Skill那么当 Codex 接到“帮我想一个关于 AI 工具推荐的短视频脚本”时它就能从 Skill 目录里找到对应技能包按里面写好的脚本结构、分镜格式、口播风格来生成内容。Skill 和普通的 Prompt 有什么区别普通 Prompt 是你每次手动输入一大段指令而 Skill 相当于把这段指令“固化”成了文件并且增加了结构化说明和可执行脚本让 Agent 能稳定复现这套能力。1.3 为什么“装得多≠装得对”这是全文核心先说结论Skill 不是越多越好而是越对越好。原因有以下几点Skill 会占用上下文窗口。Agent 在决定是否使用某个 Skill 时需要读取 Skill 的描述信息。装得越多描述信息累积起来可能占掉不少 token留给真正任务处理的窗口就变小了。Skill 之间可能互相干扰。比如“视频脚本生成”和“内容创作助手”两个 Skill 描述范围重叠Agent 可能选错输出风格完全不对。质量参差不齐。Skill 生态刚火起来很多 Skill 是随手打包的指令模糊、步骤混乱装上之后不但没提升效率反而让 Agent 的行为变得不可控。维护成本高。装了几十个 Skill你很难记得每个 Skill 对应什么能力、版本有没有更新、是否和当前 Codex 版本兼容。等某天 Skill 突然不生效排查起来非常痛苦。所以这篇文章的核心观点是Skill 应该像书架上的工具书一样按需查阅而不是把整个书店搬回家。2. 环境准备与版本说明在动手之前先确认你的环境。Codex 的安装和配置方式在不同版本里略有差异本文以常见的 CLI 环境为例演示思路实际使用时请以你下载到的版本为准。2.1 基础环境要求操作系统Windows / macOS / Linux 均可我演示路径以 macOS 和 Linux 风格为主Windows 用户将~/.codex替换为C:\Users\你的用户名\.codex即可。Node.jsCodex CLI 通常通过 npm 分发需要安装 Node.js 18 或更高版本。Codex 客户端CLI、桌面版、VS Code 扩展三种形态任选其一。模型访问权限你可以使用 OpenAI 官方接口也可以配置兼容 OpenAI 接口协议的第三方模型服务。安装命令一般是这样npm install -g openai/codex codex --version如果你之前已经装过可以先更新到较新版本再继续避免旧版本对 Skill 目录的识别有差异。npm update -g openai/codex codex --version2.2 登录与基础配置安装完成后第一步是登录或配置 API Key。codex login如果你使用的是第三方兼容服务可以在配置文件里指定模型供应商。Codex 的配置文件一般位于~/.codex/config.toml。下面是一个兼容服务配置的示例# 文件路径~/.codex/config.toml model gpt-5 model_providers [ { name my-provider, base_url http://localhost:8000/v1, env_key MY_PROVIDER_API_KEY, wire_api responses } ] model_provider my-provider这里要重点说明一下name是这个模型供应商的名称可以自定义。base_url是接口地址可以是本地调试服务也可以是你有权限访问的远程服务。env_key是读取 API Key 的环境变量名。wire_api表示接口协议格式常见的是responses或chat风格具体取决于你的服务端支持哪种协议。这段配置只是演示思路不同版本对字段名的要求可能不同。如果填错Codex 启动时会报配置解析错误这时候不要急着删配置先检查字段名是否和当前版本文档一致。2.3 确认 Skill 目录Skill 的存放位置通常分为两类全局目录和项目目录。# 全局 Skill 目录 ~/.codex/skills/ # 项目 Skill 目录 你的项目目录/.codex/skills/全局目录对所有项目生效项目目录只在当前项目里生效。如果需要验证目录是否被识别可以先手动创建一个空目录再在 Codex 会话里问它“你能看到哪些 Skill”如果回答能列出目录里的内容说明路径正确。版本差异提醒部分旧版本 Codex 对 Skill 目录的识别规则可能不同。如果你发现 Skill 没有生效优先检查版本升级日志或官方文档里的目录约定而不是盲目把文件复制到多个位置。3. Skill 的格式与选择原则3.1 Skill 文件的标准结构目前社区里最常见的 Skill 格式是一个文件夹内放一个SKILL.md文件文件开头是 YAML 格式的 frontmatter后面是 Markdown 格式的指令正文。--- name: video-script-writer description: 根据用户给出的视频主题生成结构化的视频脚本、分镜和画面提示词。适合短视频、口播视频、教程视频等场景。 --- # 视频脚本生成器 当用户需要生成视频脚本时按照以下步骤执行 1. 先向用户确认视频类型、时长和目标观众。 2. 输出脚本大纲。 3. 按分镜表格输出每一镜的画面描述和口播文案。 4. 最后生成一组可用的 AI 视频提示词。其中name是 Skill 的唯一标识description是 Agent 判断“什么时候该用这个 Skill”的关键信息。描述写得越具体Agent 选择越准确。3.2 Skill 如何被 Codex 调用Codex 不一定会强制使用某个 Skill它通常是“根据用户意图 Skill 描述”来决定是否启用。所以描述里不要写笼统的话比如“这个 Skill 很强大”“万能助手”而要写清楚适用场景。举个例子模糊描述帮助用户写视频。清晰描述当用户需要生成短视频脚本、视频分镜、口播文案或 AI 视频提示词时使用。不适用于图片生成和长视频剪辑。第二种描述能让模型快速判断是否命中场景减少误用。3.3 如何挑选 Skill先列需求再搜技能包很多人的习惯是“看到 Skill 就装”我建议反过来先列需求再找技能包。你可以用下面这个清单来判断一个 Skill 值不值得装这个技能包解决的问题是不是我每周都会遇到的它的description是否清晰能不能一眼看出适用场景它是单纯指令还是包含脚本和模板包含脚本的 Skill 通常更实用。它的维护活跃度如何太长时间没更新的 Skill 要谨慎。它依赖的外部工具或 API 是否合法、是否容易获取如果只是“看起来有意思”那不建议装。每装一个 Skill都是在给 Agent 的决策空间里增加一个变量。4. 完整实战手写一个“视频脚本生成”Skill下面我们用“Codex 辅助做视频”这个场景从零创建一个真正能用的 Skill。这里要先澄清一个概念Codex 本身不是视频生成工具它不能直接渲染视频。但通过 Skill它可以把“做视频”这件事拆解成可执行的脚本和提示词比如生成视频主题和大纲。生成分镜描述。生成口播文案。生成 AI 视频生成服务的调用代码。我们动手来写这个技能包。4.1 创建目录结构mkdir -p ~/.codex/skills/video-script-writer/scripts目录结构如下~/.codex/skills/video-script-writer/ ├── SKILL.md └── scripts/ └── generate_video_prompt.py4.2 编写 SKILL.md文件路径~/.codex/skills/video-script-writer/SKILL.md--- name: video-script-writer description: 生成短视频脚本、口播文案、分镜表格和 AI 视频提示词。适用于知识科普、产品介绍、教程讲解等视频场景。 --- # 视频脚本生成助手 当用户要求生成视频相关内容时严格按以下流程执行 ## 第一步信息确认 先向用户确认以下信息如果用户没有提供主动询问 - 视频主题 - 视频时长 - 目标观众 - 视频风格正式、轻松、幽默等 ## 第二步输出脚本大纲 按“开头引入 三个核心要点 结尾引导”的结构输出脚本大纲。 ## 第三步输出分镜表格 使用 Markdown 表格输出分镜每一行包含镜号、画面描述、口播文案、字幕。 ## 第四步生成 AI 视频提示词 根据分镜内容生成适合视频生成服务的提示词每一条提示词应包含主体、动作、环境、镜头语言、风格关键词。 ## 注意事项 - 不要生成与主题无关的内容。 - 口播文案要口语化避免书面语。 - 如果主题涉及不熟悉的技术或事实先说明需要核实信息。4.3 编写辅助 Python 脚本单纯靠指令Agent 只能生成文案如果能配一个脚本它就能按照固定模板快速产出结构化的提示词。下面这个脚本可以从命令行接收主题然后生成一组 AI 视频提示词。文件路径~/.codex/skills/video-script-writer/scripts/generate_video_prompt.py#!/usr/bin/env python3 根据视频主题生成 AI 视频提示词。 用法 python3 generate_video_prompt.py AI 编程工具推荐 import sys def build_prompt(topic: str) - str: scenes [ { scene: 1, subject: 一位开发者在电脑前使用 AI 编程工具, action: 手指在键盘上快速输入代码屏幕显示代码补全, environment: 简洁的办公室暖色灯光, camera: 近景侧拍镜头缓慢推近, style: 写实科技感明亮通透, }, { scene: 2, subject: 屏幕特写, action: 展示 AI 工具自动生成代码并运行成功, environment: 深色 IDE 背景代码高亮, camera: 特写镜头聚焦屏幕, style: 写实高对比度科技蓝, }, { scene: 3, subject: 开发者微笑点头, action: 端起咖啡杯看向镜头, environment: 办公室背景微虚化, camera: 中景正面镜头, style: 写实自然光轻松氛围, }, ] lines [f视频主题{topic}, , 分镜提示词] for item in scenes: lines.append( f{item[scene]}. 主体{item[subject]}动作{item[action]} f环境{item[environment]}镜头{item[camera]}风格{item[style]} ) return \n.join(lines) def main() - None: if len(sys.argv) 2: print(请提供视频主题例如python3 generate_video_prompt.py \AI 编程工具推荐\) sys.exit(1) topic sys.argv[1] print(build_prompt(topic)) if __name__ __main__: main()这个脚本非常简单没有依赖任何第三方库Python 3 直接可以运行。它的作用不是替代 Agent 的创意能力而是让结果更稳定当 Codex 调用这个脚本时输出的提示词结构是固定的不会因为每次对话上下文不同而“自由发挥”。4.4 在 Codex 中调用 Skill配置完成后启动 Codex 会话codex然后在对话里输入帮我写一个关于“AI 编程工具推荐”的 60 秒短视频脚本使用 video-script-writer 技能包。如果 Skill 被识别Codex 会按SKILL.md里定义的流程输出大纲和分镜表格。如果希望输出更稳定也可以让它执行脚本运行 scripts/generate_video_prompt.py 脚本主题是“AI 编程工具推荐”。4.5 验证 Skill 是否生效如果 Codex 没有按预期调用 Skill可以用下面几种方式排查直接问 Codex你能看到哪些 Skill如果它列出了video-script-writer说明目录被识别。检查目录权限~/.codex/skills目录是否可读。检查文件名大小写部分系统对文件名区分大小写SKILL.md不要写成skill.md。验证通过后这个 Skill 就可以重复使用了。5. 常见问题与排查思路Codex 和 Skill 相关报错最近在社区里问得不少。下面整理了我见过的高频问题按“现象 - 原因 - 排查思路”的方式列出。问题现象常见原因排查思路配置本地服务后报cc switch local proxy failed while handling codex endpoint /responses本地服务未启动、端口错误或协议不匹配先确认本地服务进程是否存在再用 curl 手动访问/responses接口最后检查base_url是否写错提示模型不支持agent skill当前模型或 harness 版本与 Skill 机制不兼容升级 Codex 到最新版或更换为支持 Agent Skill 的模型Skill 不自动生效description描述不清晰或目录位置不对检查 Skill 是否放在全局/项目目录尝试在对话中显式点名 Skill装了 Skill 之后回答反而变差Skill 指令与用户需求冲突或 Skill 之间描述重叠临时禁用部分 Skill逐个对比输出效果下载的 Skill 没有SKILL.md来源不是标准 Skill 包查看压缩包内文件结构找到说明文件后自行整理API Key 鉴权失败环境变量未设置或 Key 权限不足检查env_key对应的环境变量是否已导出Key 是否有相关模型权限5.1 本地接口报错的完整排查思路如果你自己搭了本地调试服务或兼容端点遇到类似cc switch local proxy failed while handling codex endpoint /responses的报错可以按下面顺序排查第一步确认服务确实在运行curl http://localhost:8000/v1/responses如果服务没启动会直接连接失败这时候只需要启动服务。如果返回了非200状态码说明服务在运行但接口路径或协议不对。这时候需要检查 Codex 配置里的base_url是否指向了正确的路径前缀。第二步检查配置里的wire_api字段。Codex 访问模型服务时不同协议对应的端点和请求体结构不同。如果你用的是 chat 风格的接口却配置了responses协议就会在/responses端点上报错。第三步查看 Codex 的详细日志。通常可以在运行时增加--debug或-v参数日志里会记录实际的请求 URL 和响应状态码这是定位问题最直接的手段。5.2 模型报错的处理建议社区里有人反馈某些模型在使用 Agent Skill 时会出现类似not supported的提示。这种情况多数是模型或 harness 版本的问题而不是 Skill 内容写错。处理方法很简单优先升级 Codex 版本。查看当前模型是否在官方支持列表里。如果不支持换个兼容模型或者不用 Skill直接把SKILL.md的内容作为普通 Prompt 发给 Codex。在排查这类问题时记得先确认你拥有目标模型和接口的合法使用权限并遵守服务提供方的使用条款。6. 最佳实践与工程建议6.1 用“最小化原则”管理 Skill我现在的建议是全局 Skill 控制在 5 个以内项目 Skill 按项目实际需要单独添加。为什么是 5 个因为 Skill 的生效依赖 Agent 在每次对话中自动判断“要不要调用、调用哪个”。给它的候选越少它选错的概率越低。你可以在需要时临时把某个 Skill 放进目录用完再移出。具体操作# 禁用某个 Skill改名即可 mv ~/.codex/skills/video-script-writer ~/.codex/skills/.video-script-writer.disabled # 启用某个 Skill改回原名 mv ~/.codex/skills/.video-script-writer.disabled ~/.codex/skills/video-script-writer6.2 自建 Skill 的通用模板如果你想自己写更多 Skill可以参考下面这个模板--- name: skill-name description: 用一两句话说明触发场景避免模糊描述。 --- # 技能名称 当用户提出相关需求时按以下步骤执行 1. 明确需求边界。 2. 输出固定格式的内容。 3. 检查结果是否符合要求。 ## 关键规则 - 规则一。 - 规则二。写完后建议在SKILL.md里补充至少一个示例输入和输出。示例能显著提升 Agent 对 Skill 的理解准确度。6.3 推荐的工作流Skill 脚本 外部服务一个真正能稳定运行的 Skill通常不是“纯文字指令”而是包含脚本或模板文件。因为纯指令容易受对话上下文影响输出质量波动大而脚本可以固化流程让 Agent 每次执行结果都保持一致。以“Codex 做视频”为例一个更完整的链路是Skill 负责生成视频脚本和分镜。Python 脚本把分镜转换成结构化的提示词。Codex 读取提示词调用外部视频生成服务的 API。脚本把生成的视频片段拼接成完整视频。这个链路里Skill 是“指挥大脑”脚本是“稳定执行的手”外部服务是“生产工具”。三者各司其职才能把复杂任务落地。6.4 定期审计你的 Skill 目录建议每两周做一次审计哪些 Skill 最近一次使用是什么时候有没有内容重复或覆盖的 Skill有没有已经失效的脚本或链接描述是否还能准确反映当前能力审计的目的不是让你“清空目录”而是让你对每个 Skill 的用途、质量和维护状态心里有数。这样当 Codex 出现异常输出时你能快速定位到是哪个 Skill 在捣乱而不是把所有 Skill 全部删除。6.5 留意上下文与 token 成本Skill 本身不占太多 token但如果某个 Skill 附带大量参考文档Codex 在读取它时就会消耗更多上下文。写 Skill 时保持精简把详细资料放到单独文件中让 Agent 按需读取而不是一次性全塞进来。这就像写代码一样一个函数只做一件事一个 Skill 也只解决一个场景。7. 写在最后Codex 的 Skill 机制很好用但越强大的机制越需要克制使用。我见过一些项目因为装了太多来源不明的 Skill最终输出结果变得不可预测最后排查了一下午罪魁祸首竟然是两个描述重叠的 Skill 在互相干扰。所以回到标题那句话装的多≠装的对。真正高效的做法是明确自己的高频任务选几个足够精准的 Skill自己动手写那些社区里还没有的能力。需要视频脚本就写一个视频脚本 Skill需要 PPT就写一个 PPT 的 Skill需要数据处理就写一个数据处理模板。按需安装定期清理保持目录干净Codex 反而会给你更稳定的答案。如果你在配置 Skill 时遇到报错建议先把报错原文、Codex 版本、Skill 目录结构这三样信息记录下来这是最快定位问题的关键。毕竟工具是死的排查思路是活的掌握方法比收藏技能包更重要。