你花了一下午终于把 Codex 装好了。看着命令行里那个闪烁的光标你满怀期待地输入了第一个指令“帮我分析一下这个项目的代码结构。” 然后你得到了一个礼貌但略显空洞的回应它似乎理解了你的问题但给出的答案却像是一篇通用的代码分析模板离你想要的、能直接嵌入工作流的自动化洞察还差得很远。这不是 Codex 不够聪明也不是你的指令有问题。问题很可能出在中间那个缺失的环节——Skills技能。很多人把 Codex 装好就以为万事大吉可以像电影里那样指挥 AI 完成一切。但现实是一个没有“技能包”的 Codex就像一个空有强大算力却不知如何施展的学徒。它需要你或者说需要你为它定义的“技能”来将模糊的意图转化为具体、稳定、可复用的自动化动作。今天我们不谈复杂的多智能体协同也不深究底层的强化学习原理。我们就聚焦一件事如何通过Skills把一个“能对话的 AI”变成一个“能替你干活的自动化伙伴”。这不仅仅是安装几个现成的技能更是理解如何设计、组织和管理这些技能让它们成为你工作流中真正可复用的组件。1. 从“对话”到“执行”理解 Skills 的本质当你对 Codex 说“分析代码”时它的大脑里发生了什么它可能会调用内置的知识库生成一段分析文本。但如果你为它装备了一个名为code-review的技能情况就完全不同了。这个技能里可能包含了明确的指令如何定位项目根目录、识别主流框架、按模块遍历文件、提取关键函数和类、评估代码复杂度、并生成结构化报告。参考资料你团队内部的代码规范文档、安全扫描的 Checklist。可选脚本一个可以自动运行静态分析工具如pylint,eslint并解析结果的 Shell 或 Python 脚本。Skills 的本质是将一次性的、依赖临场发挥的“提示工程”沉淀为可重复调用、有明确输入输出规范的“工作流模板”。它解决了大模型应用中最核心的痛点之一输出的不可控性和随机性。通过 Skills你为 Codex 划定了执行任务的轨道让它能更稳定、更可靠地完成特定工作。1.1 技能 vs. 插件先搞清你要创作什么在 Codex 的生态里有两个容易混淆的概念技能Skill和插件Plugin。理解它们的区别是有效利用这套系统的第一步。技能Skill这是工作流的创作格式。它关注的是“怎么做”这件事本身。一个技能就是一个包含指令、参考资料和脚本的目录核心文件是SKILL.md。它是你本地开发、调试和复用工作流的基本单元。当你脑子里有一个清晰的自动化流程想固化下来时你应该先创建技能。插件Plugin这是工作流的分发与安装单元。一个插件可以包含一个或多个技能还可以打包应用配置、MCP 服务器连接信息等。当你希望把调试好的技能分享给团队或者集成到一个更大的应用中一起交付时才需要将它打包成插件。简单来说技能是源代码插件是可执行安装包。对于绝大多数个人开发者和团队内部协作从创建和积累技能开始是最高效的路径。不要一开始就想着复杂的分发先把那个能帮你节省半小时的流程固化下来。1.2 “按需展开”Codex 管理技能的智能方式你可能会担心如果我安装了上百个技能每次对话都要把它们全部加载进上下文岂不是会挤占宝贵的 Token拖慢速度Codex 采用了一种称为“按需展开”On-demand Expansion的聪明机制启动时轻量加载Codex 启动时只会读取每个技能的name名称、description描述和文件路径。这份精简的列表最多只占用模型上下文窗口的 2%或最多8000字符。如果技能太多Codex 甚至会智能地缩短描述来满足这个限制。使用时完整加载只有当 Codex 根据当前对话判断“这个技能可能有用”或者你显式调用如输入$skill-name时它才会去读取该技能完整的SKILL.md指令内容。这意味着你可以放心地积累大量技能而无需担心性能开销。同时这也对技能描述description的撰写提出了要求必须简洁、准确把最关键的触发词放在前面确保即使在描述被截短的情况下Codex 也能做出正确的匹配判断。2. 技能的诞生从构思到可运行文件知道了技能是什么接下来就是如何创建一个。Codex 提供了两种主流的创建方式适合不同的场景。2.1 方式一录屏式创作Record Replay如果你觉得“演示一遍比写一千字描述更容易”那么Record Replay是你的首选。这个功能允许你在 Codex App 或 CLI 中启动录制。像平时一样手动完成一遍你想要自动化的工作流例如登录某个内部系统、下载日志、用grep过滤错误、保存结果。停止录制。Codex 会分析你的所有操作步骤命令、输出、文件变更等。基于你的演示Codex 会自动为你起草一个技能的SKILL.md草稿包括步骤指令和可能需要的脚本。这种方式极大地降低了创作门槛特别适合将那些你经常重复、但步骤固定的手动操作自动化。它捕捉的是你的“肌肉记忆”然后将其转化为 AI 可理解的流程。2.2 方式二描述式创作使用$skill-creator如果你更习惯用文字定义流程或者流程本身逻辑清晰但操作复杂可以使用内置的$skill-creator技能。在 Codex 中调用$skill-creator。它会引导你回答几个关键问题这个技能要做什么用一句话概括核心任务在什么场景下应该触发它描述用户可能会说的话或遇到的状况它是“纯指令”型还是“带脚本”型skill-creator通常建议新手先从纯指令开始根据你的回答它会生成一个结构化的SKILL.md文件框架你可以在其基础上进行细化和完善。2.3 手动创建理解技能的文件结构无论用哪种方式创建最终都会落地的技能目录结构。理解这个结构是进行高级定制的基础。my-git-helper/ ├── SKILL.md # 【必需】技能的核心指令与元数据 ├── scripts/ # 【可选】可执行的脚本文件.sh, .py, .js等 │ └── create-branch.sh ├── references/ # 【可选】参考文档、规范、模板 │ └── commit-convention.md ├── assets/ # 【可选】静态资源如图片、模板文件 └── agents/ # 【可选】高级配置如界面元数据 └── openai.yaml核心文件SKILL.md 这个文件采用 YAML Front Matter 定义元数据后面跟 Markdown 格式的指令。--- name: create-feature-branch # 技能的唯一标识调用时用 $create-feature-branch description: 当用户需要基于主分支创建一个新的特性分支并关联JIRA任务时触发。输入应包含JIRA任务号如PROJ-123和简短特性描述。 --- # 创建特性分支 请遵循以下步骤为用户创建一个Git特性分支 1. **确认当前仓库**确保你位于正确的Git仓库中。如果不是请提示用户。 2. **获取输入**向用户询问或确认以下信息 - JIRA任务号例如PROJ-456 - 新分支的简短描述例如add-user-auth 3. **构造分支名**使用格式 feature/PROJ-456-add-user-auth。确保描述部分使用短横线连接小写单词。 4. **执行创建** bash git checkout main git pull origin main git checkout -b feature/PROJ-456-add-user-auth 5. **验证与输出**创建成功后告知用户新分支名称并提示下一步操作如git push -u origin feature/PROJ-456-add-user-auth。这个例子展示了一个纯指令型技能。如果任务更复杂比如需要调用外部API、处理特定文件格式你就可以在scripts/目录下放置脚本并在指令中通过相对路径调用它们。3. 技能的安家与生效多级作用域管理创建了技能放在哪里才能生效Codex 设计了清晰的作用域Scope体系让你能灵活地管理个人技能、团队共享技能和系统级技能。作用域Scope典型路径推荐用途REPO仓库$CWD/.agents/skills最常用。当前项目或微服务专属的自动化脚本如项目特定的构建、部署流程。REPO仓库$REPO_ROOT/.agents/skills整个Git仓库共享的技能适合团队规范如统一的代码审查、提交信息检查。USER用户$HOME/.agents/skills你个人全局可用的技能比如你的个人笔记整理、常用系统诊断命令。ADMIN管理员/etc/codex/skills系统或容器级别共享的技能通常由运维人员管理如服务器健康检查、日志轮转。SYSTEM系统OpenAI 内置Codex 自带的通用技能如skill-creator、skill-installer。Codex 的扫描规则是从当前工作目录$CWD开始向上递归查找.agents/skills目录直到仓库根目录。同时它也会加载 USER 和 ADMIN 作用域下的技能。这意味着当你在一个项目子目录下工作时可以同时使用项目根目录的共享技能和你个人的全局技能。一个重要提示如果不同位置存在同名技能name相同Codex不会合并它们而是会同时出现在可选列表中。这可能导致混淆因此建议团队内对技能命名建立简单的约定。4. 从技能到工程化进阶配置与最佳实践当技能数量增多或者需要更精细的控制时你就需要了解一些进阶配置。4.1 启用与停用动态管理技能库你不需要通过删除文件来禁用某个技能。可以在 Codex 的配置文件~/.codex/config.toml中进行管理[[skills.config]] path /full/path/to/skill/SKILL.md enabled false # 将此技能禁用修改配置后需要重启 Codex 以使变更生效。这个功能在调试技能冲突或者临时关闭某些实验性技能时非常有用。4.2 界面与策略提升使用体验agents/openai.yaml如果你想在 Codex App 中获得更好的可视化体验或者控制技能的调用策略可以在技能目录下创建agents/openai.yaml文件。interface: display_name: 数据库查询助手 # 在App中显示的名称 short_description: 安全地查询预定义数据库表 # 更友好的描述 icon_small: ./assets/db-icon.svg brand_color: #10B981 policy: allow_implicit_invocation: false # 关键设置禁止隐式调用 dependencies: tools: - type: mcp value: postgresql description: 连接到PostgreSQL数据库的MCP服务器这里最关键的设置是policy.allow_implicit_invocation。对于涉及敏感操作如数据库写入、服务器重启或需要非常精确触发条件的技能强烈建议将其设为false。这样Codex 就不会根据用户的只言片语自动触发该技能必须通过显式输入$skill-name来调用大大增加了安全性。4.3 技能创作的最佳实践清单为了让你的技能更可靠、更易用请遵循以下原则单一职责一个技能只做好一件事。不要创建“瑞士军刀”式的巨型技能。将复杂流程拆分为多个小技能通过组合使用。指令优先能用清晰的自然语言指令让 Codex 完成的就不要写脚本。脚本应留给需要确定性、需要调用外部工具或处理复杂计算的场景。明确输入输出在技能指令的开头清晰地定义这个技能需要用户提供什么输入以及最终会产出什么输出。使用祈使句给 Codex 的指令应直接、明确。“获取当前分支名”比“你可以尝试获取一下当前的分支名称吗”更有效。测试描述字段用你预想中用户会说的各种话去测试技能的description。确保它在该触发时触发在不该触发时保持沉默。处理边界和错误在指令中考虑常见错误情况如文件不存在、命令执行失败、网络超时并告诉 Codex 此时该如何应对或向用户报告。5. 技能的获取与共享安装与分发你不需要所有技能都从零开始创作。Codex 社区和官方提供了一些现成的技能。5.1 安装社区技能你可以使用内置的$skill-installer来安装精选的技能。例如想安装一个与 Linear项目管理工具集成的技能$skill-installer linearskill-installer会从预定义的源如 GitHub 仓库下载技能并放置到你的用户技能目录$HOME/.agents/skills中。安装后重启 Codex 即可使用。5.2 从技能到插件当需要分享时当你精心打磨的技能需要在团队内部分享或者作为产品的一部分交付给客户时就应该考虑将其打包为插件。插件通过plugin.toml清单文件定义可以包含一个或多个技能应用配置映射MCP 服务器配置图标、描述等展示信息将技能打包成插件后其他人可以通过简单的命令如codex plugins install your-plugin一键安装所有依赖的技能和配置都会就位。这实现了技能从“个人工具”到“团队资产”或“可分发产品”的跃迁。6. 构建你的自动化工作流一个实战案例让我们通过一个完整的例子将以上所有概念串联起来。假设你是一个全栈开发者经常需要从 JIRA 领取一个新任务。在本地创建对应的 Git 分支。初始化一个简单的 React 组件模板。将任务详情自动写入组件的注释中。步骤 1分解与创建技能我们将这个流程分解为三个可复用的技能Skill A:fetch-jira-task调用 JIRA API根据任务号获取详情。scripts/下放一个 Python 脚本处理 API 调用和解析。Skill B:create-react-component根据组件名在指定路径创建标准的 React 函数组件文件并填充基础模板。assets/下可以放模板文件。Skill C:sync-task-to-code协调性技能。它显式调用 A 和 B将 A 获取的任务描述插入到 B 创建的组件文件的注释区块。步骤 2放置与作用域将fetch-jira-task和create-react-component放在团队仓库的根目录.agents/skills/下作为共享技能。将sync-task-to-code放在你个人项目的.agents/skills/下因为它组合了前两者的使用方式更具个人色彩。步骤 3使用与迭代现在当你开始一个新任务时只需在项目目录下打开 Codex 并输入$sync-task-to-code PROJ-789。Codex 会依次执行三个技能你将在几分钟内获得一个准备好的开发环境和初始代码文件。在这个过程中如果发现create-react-component的模板不符合新项目要求你只需更新仓库根目录的那个共享技能文件团队所有成员下次使用时都会自动获得更新。这就是可复用工作流的力量。真正的进阶不在于安装了多少个技能而在于你是否能将一个模糊的需求清晰地分解、定义并固化成一个个精准、可靠、可组合的 Skills。这本质上是一种思维模式的转变从“我如何让 AI 理解我这一次要做什么”转变为“我如何设计一个能让 AI 无数次稳定执行某类任务的程序”。当你开始用 Skills 的思维去审视日常工作中的重复环节时Codex 才真正从一个对话工具进化为你工作流中不可或缺的自动化引擎。
