Codex Skills 实战指南：从零构建可复用的 AI 开发工作流

在实际 AI 辅助开发工作中很多开发者会遇到一个典型困境工具装好了基础命令也会用了但总感觉它只能完成一些零散的、简单的任务无法真正融入自己的核心工作流。比如你希望它能自动生成符合团队规范的 API 接口代码、一键执行复杂的本地构建部署流程或者根据 Jira 工单自动生成 Git 提交信息。这些都不是单一指令能解决的它们需要一系列连贯的、可复用的步骤组合。这正是 Codex 的 Skills技能机制要解决的核心问题。Skills 不是简单的命令别名而是将指令、上下文、脚本和资源打包在一起的“任务级能力单元”它让 Codex 从一个被动的问答工具转变为一个能主动遵循预设流程、稳定执行复杂任务的智能体。本文面向已经安装 Codex 但尚未深入使用其高级功能的开发者。我们将从零开始彻底理解 Skills 的概念、工作机制和最佳实践。你将学会如何创建自己的第一个技能如何组织和管理技能库以及如何利用技能搭建可复用的自动化工作流最终将 Codex 深度集成到你的日常开发、测试和部署环节中。整个过程不需要你预先掌握复杂的 AI 或脚本知识我们将通过具体的示例和清晰的步骤带你从“会用”走向“精通”。1. 理解 Codex Skills从指令到可复用工作流在深入动手之前我们必须先厘清几个核心概念什么是 Skill它和普通的提示词、插件有什么区别为什么我们需要它1.1 Skill 的本质封装确定性的工作流一个 Skill技能本质上是一个目录其中至少包含一个SKILL.md文件。这个文件定义了技能的元数据名称、描述和具体的执行指令。你可以把它想象成一个针对特定任务的“超级模板”或“自动化脚本说明书”。当 Codex 决定使用某个技能时它会将SKILL.md中的完整指令加载到其上下文中从而确保执行过程的稳定性和可预测性。与一次性的聊天提示词相比Skill 的核心优势在于可复用性和确定性。一次精心编写的提示词可能这次有效下次因为上下文细微变化就失效了。而一个定义良好的 Skill通过明确的触发条件和步骤描述能在相同场景下被反复、稳定地调用。1.2 Skill 与 Plugin 的定位差异这是初学者最容易混淆的一点。根据官方设计两者的分工非常明确Skill技能是工作流的创作格式。它关注的是“做什么”和“怎么做”是逻辑和指令的集合。它最适合在本地或团队仓库内定义和迭代具体的工作流程比如“为新功能分支创建标准的目录结构”或“运行项目的全套代码质量检查”。Plugin插件是能力的分发和安装单元。一个插件可以包含一个或多个技能同时还能打包 MCP 服务器配置、应用映射、界面资源等。当你希望将开发好的技能分享给更广泛的用户或者将其与某个应用程序捆绑分发时才需要将其打包成插件。简单来说先设计 Skill 来解决具体问题再考虑是否将其打包为 Plugin 进行分发。对于个人或团队内部使用直接在.agents/skills目录下维护技能库就足够了。1.3 Codex 如何发现和使用技能Codex 采用一种称为“按需展开”的智能上下文管理策略。启动时它并不会加载所有技能的完整内容那样会迅速耗尽有限的上下文窗口。相反它只读取每个技能目录下的SKILL.md文件中的name和description字段生成一个轻量级的技能列表。当用户提出需求时Codex 会基于这个列表中的描述判断哪个技能最适合当前任务。只有在确定要使用某个技能后才会将该技能完整的SKILL.md指令内容加载到上下文中。这种机制既保证了技能匹配的灵活性又最大限度地节约了宝贵的上下文资源。技能可以通过两种方式触发显式调用用户直接在对话或命令中指定技能名称例如在 Codex CLI 中输入/skills后选择或在提示词中写入$skill-name。隐式调用Codex 根据用户自然语言描述的意图自动匹配技能描述中合适的关键词和场景从而推荐或直接使用该技能。这就要求技能的description必须写得精准、清晰。2. 环境准备与技能目录结构在创建第一个技能之前我们需要确保 Codex 环境就绪并理解技能文件的存放位置规则。2.1 确认 Codex 安装与基础功能首先打开终端运行以下命令检查 Codex CLI 是否已正确安装并可访问技能相关功能# 检查 Codex CLI 版本 codex --version # 列出当前已发现的技能初始可能为空或只有系统内置技能 codex /skills list # 尝试调用内置的技能创建器如果可用 codex $skill-creator如果codex命令未找到请根据官方文档重新完成安装和配置。确保你的 Codex 版本支持 Skills 功能。2.2 理解技能的多级存储位置Codex 会从多个层级的位置扫描并加载技能优先级从高到低局部覆盖全局如下表所示作用范围扫描路径示例用途与建议REPO (仓库)./.agents/skills/最常用。位于项目根目录或子目录下适用于该项目或模块特有的技能如项目特定的构建脚本、代码生成模板。REPO (仓库)../.agents/skills/当你在 Git 仓库的子目录中启动 Codex 时可以访问父目录中共享的技能。USER (用户)~/.agents/skills/用户全局技能。存放你个人在任何项目中都想使用的技能例如通用的 Git 操作、个人笔记模板等。ADMIN (系统管理员)/etc/codex/skills/系统或容器级别的共享技能。通常由运维或团队管理员统一配置如公司内部的部署规范、安全扫描脚本。SYSTEM (系统)OpenAI 内置Codex 自带的通用技能如skill-creator技能创建器本身。关键规则Codex 会从当前工作目录$CWD开始向上扫描直到仓库根目录寻找.agents/skills文件夹。如果不同位置存在同名技能它们会同时出现在技能列表中不会被合并Codex 可能会提示你进行选择。对于初学者我们建议从仓库级技能开始。在你的项目根目录下创建.agents/skills目录。# 进入你的项目目录 cd /path/to/your/project # 创建技能存储目录 mkdir -p .agents/skills # 查看目录结构 tree .agents -a预期输出应显示一个空的skills目录。3. 创建你的第一个技能自动化生成 RESTful API 控制器让我们通过一个实战案例来学习技能的创建。假设我们有一个 Spring Boot 项目需要频繁地为新的资源创建符合团队规范的 RESTful Controller。手动编写虽然简单但容易遗漏注解、格式不一致。我们将创建一个名为generate-spring-controller的技能来自动化这个过程。3.1 使用技能创建器推荐给新手Codex 内置了skill-creator工具它能通过交互式问答引导你完成技能的创建。在项目根目录下运行codex $skill-creator创建器会询问一系列问题以下是一个示例对话流程及回答思路What should this skill do?(这个技能做什么)回答Generate a Spring Boot REST controller for a given resource name, following our teams coding standards. It should include standard CRUD endpoints, proper annotations, and placeholder method bodies.When should Codex use this skill?(Codex 应在什么场景下使用它)回答When the user asks to create a new API controller, generate a REST controller, or scaffold a CRUD endpoint for a resource. Keywords: “controller”, “REST”, “API”, “CRUD”, “scaffold”.Should this skill include runnable scripts, or is it instructions-only?(这个技能包含可运行脚本还是仅是指令)回答Instructions-only.对于纯代码生成任务通常先使用纯指令技能。回答完毕后skill-creator会在当前目录或你指定的目录下生成一个技能文件夹例如.agents/skills/generate-spring-controller/并包含一个初步的SKILL.md文件。3.2 手动创建与编写 SKILL.md理解技能结构后手动创建能让你更清晰地控制细节。按照以下步骤操作# 在项目的技能目录下创建技能文件夹 mkdir -p .agents/skills/generate-spring-controller # 创建并编辑核心的 SKILL.md 文件 cd .agents/skills/generate-spring-controller用文本编辑器创建SKILL.md文件内容如下--- name: generate-spring-controller description: Generates a standard Spring Boot REST controller with CRUD endpoints for a given resource name. Use when user asks to create an API controller, REST endpoint, or scaffold CRUD operations. --- You are an expert Java and Spring Boot developer. Your task is to generate a complete, production-ready Spring Boot REST controller class based on the users request. **Instructions:** 1. First, ask the user for the **singular resource name** (e.g., Product, User, Order). 2. Based on the resource name, generate a corresponding Java class file. 3. The controller must be placed in the com.example.demo.controller package (adjust if the user specifies a different base package). 4. Follow these coding standards: * Use RestController and RequestMapping(/api/v1/{resource-kebab}) annotations. * Inject a service using Autowired (field injection for simplicity in this scaffold). * Implement standard CRUD endpoints: * GET / - getAll() returns ListResource * GET /{id} - getById(PathVariable Long id) returns Resource * POST / - create(RequestBody Resource resource) returns Resource * PUT /{id} - update(PathVariable Long id, RequestBody Resource resource) returns Resource * DELETE /{id} - delete(PathVariable Long id) returns ResponseEntityVoid * Use Slf4j for logging (ensure project has Lombok). * Include placeholder method bodies with TODO comments and log statements. * Use proper Javadoc for the class and public methods. 5. After generating the code, provide a brief explanation of the structure and remind the user to create corresponding Service, Repository, and Entity classes. **Output Format:** Provide the complete Java code in a markdown code block labeled java. Then, add a summary section. **Example Interaction:** User: Create a controller for managing books. Assistant: Ill help you generate a Book controller. First, whats the singular name of the resource? (e.g., Book) User: Book Assistant: [Generates the BookController.java code]这个SKILL.md文件的结构非常清晰Front-matter (元数据)被---包裹的 YAML 块定义了技能的name和description。description是隐式匹配的关键务必准确描述触发场景。指令主体详细说明了技能的目标、交互步骤、代码规范、输出格式甚至包含了一个示例对话。这相当于给 Codex 的一份“工作手册”。3.3 为技能添加可选资源与配置一个技能目录下还可以包含其他文件使其功能更强大scripts/存放可执行的 Shell、Python 等脚本技能指令中可以调用它们来执行外部操作。references/存放参考文档、API 说明等供 Codex 在生成内容时查阅。assets/存放代码模板、配置文件等静态资源。agents/openai.yaml用于配置技能在 Codex App 中的界面显示和高级策略。让我们为控制器生成技能添加一个agents/openai.yaml文件以控制其调用策略# .agents/skills/generate-spring-controller/agents/openai.yaml interface: display_name: 生成 Spring 控制器 short_description: 根据资源名生成标准的 Spring Boot REST CRUD 控制器代码。 # icon_small: ./assets/controller-icon.svg # 可选图标 # icon_large: ./assets/controller-icon-lg.png brand_color: #10B981 # Emerald green policy: # 设为 false 则只能通过 $generate-spring-controller 显式调用不会自动推荐 allow_implicit_invocation: true dependencies: # 声明此技能依赖的工具或上下文此处为示例实际需根据项目调整 # tools: # - type: mcp # value: javaDocServer # description: Access to Java SDK documentation创建完成后你的技能目录结构应如下所示your-project/ ├── .agents/ │ └── skills/ │ └── generate-spring-controller/ │ ├── SKILL.md │ └── agents/ │ └── openai.yaml └── (其他项目文件)4. 技能的调用、测试与验证技能创建后需要重启 CodexCLI 或 IDE 插件以重新扫描并加载新技能。之后就可以进行测试了。4.1 触发与使用技能方法一隐式调用基于描述匹配在 Codex 对话窗口中直接输入自然语言请求“我需要一个用于管理订单的 REST API 控制器。”如果技能的description写得好并且allow_implicit_invocation为trueCodex 应该能识别出这个请求与generate-spring-controller技能匹配并自动应用该技能的指令来与你交互。方法二显式调用直接指定在 Codex 输入中直接使用技能名称带$前缀$generate-spring-controller或者在支持斜杠命令的 CLI 或 IDE 中输入/skills可能会列出可用技能供你选择。4.2 验证技能输出一个成功的交互应该遵循SKILL.md中定义的流程。以上面的技能为例理想的交互过程是Codex 识别技能并首先提问“我将为您生成一个控制器。请问资源的单数名称是什么例如Order”用户回答“Order”Codex 生成完整的OrderController.java代码包含所有要求的注解、CRUD 方法和日志。你应该检查生成的代码是否包路径正确。包含了RestController,RequestMapping,Autowired等注解。有GET,POST,PUT,DELETE方法。方法签名和返回值类型符合规范。包含了Slf4j和日志语句。有清晰的TODO注释。4.3 调试技能不生效的常见问题如果技能没有按预期触发或工作请按以下清单排查问题现象可能原因检查与解决步骤技能完全未出现在列表中1. 目录位置错误2. Codex 未重启3. 缺少SKILL.md1. 确认技能目录在.agents/skills/下且位于 Codex 启动时的工作目录或其父路径中。2. 完全重启 Codex CLI 或 IDE 插件。3. 确认技能目录内有SKILL.md文件。技能列表中有但描述是空的或被截断SKILL.md的 front-matter 格式错误检查SKILL.md开头的---分隔符和name、description的 YAML 语法是否正确。隐式调用不触发1.description不匹配用户请求2.allow_implicit_invocation设为 false3. 技能太多描述被截断1. 优化description包含更具体、更可能被用户提及的关键词。2. 检查agents/openai.yaml中的policy设置。3. Codex 初始列表有字符数限制确保核心关键词在description靠前位置。技能被触发但输出不符合指令SKILL.md中的指令不够清晰或存在矛盾1. 简化指令使用更明确的祈使句。2. 在指令中提供更具体的输出格式示例。3. 在技能中增加references/提供更详细的规范文档。修改技能后未生效修改未保存或 Codex 缓存1. 保存文件。2. 重启 Codex 以重新加载所有技能。5. 设计高效技能的最佳实践与进阶模式掌握了基础创建和调用后遵循以下最佳实践能让你的技能更强大、更可靠。5.1 技能设计原则单一职责一个技能只做好一件事。不要创建“生成控制器并连接数据库还运行测试”的巨无霸技能。将其拆分为generate-controller、generate-service、run-unit-tests等多个技能组合使用。指令优先于脚本除非必须调用外部工具或执行确定性操作如文件移动、执行命令否则尽量用清晰的文字指令指导 Codex 完成工作。这保持了灵活性并能利用 Codex 最新的模型能力。清晰的输入与输出在指令中明确说明技能需要用户提供什么信息如资源名、文件路径以及最终会输出什么如代码块、文件列表、总结报告。用真实提示词测试描述不断用你期望用户会说的各种话来测试技能的description确保它在该触发时触发在不该触发时保持“沉默”避免误匹配。5.2 组合技能以构建工作流真正的自动化威力来自于技能的串联。Codex 可以在一轮对话中依次或根据条件使用多个技能。示例新功能开发工作流你可以设计三个技能$create-feature-branch基于 Jira issue key 创建并切换 Git 分支。$scaffold-crud-module根据模块名生成 Entity, Repository, Service, Controller 的骨架代码。$run-local-validation运行项目的代码格式化、静态检查和单元测试。当开始一个新功能时你可以依次调用它们或者在一个更高级的“总管”技能中按顺序调用这些子技能。5.3 利用脚本和外部工具当任务需要与本地环境交互时可以在技能目录的scripts/子目录下放置可执行脚本。例如创建一个deploy-to-staging技能其SKILL.md指令中包含步骤“运行部署脚本scripts/deploy.sh”。而scripts/deploy.sh内容可能如下#!/bin/bash # scripts/deploy.sh echo 开始部署到预发环境... # 假设使用某个部署工具 ./your-deploy-tool --env staging --version $(git rev-parse --short HEAD) if [ $? -eq 0 ]; then echo ✅ 部署成功 echo 预发环境地址https://staging.example.com else echo ❌ 部署失败请检查日志。 exit 1 fi在SKILL.md中你可以这样指示 Codex“请执行项目根目录下的部署脚本scripts/deploy.sh并将结果反馈给我。” Codex 在沙箱环境中执行该脚本后会将输出返回给你。注意执行脚本涉及安全与权限。请仅在可信的技能中包含脚本并清楚了解脚本的行为。Codex 的沙箱环境会限制某些操作。5.4 管理个人与团队技能库随着技能增多管理变得重要。个人技能库 (~/.agents/skills): 将通用的、与特定项目无关的技能放在这里如format-code、commit-with-convention、docker-build。项目技能库 (./.agents/skills): 放置项目特有的技能如项目独有的代码生成模板、部署脚本。使用 Git 管理: 将项目的.agents/skills目录纳入版本控制这样团队所有成员都能共享同一套自动化标准。技能文档化: 在团队 Wiki 或README.md中维护一个技能清单说明每个技能的用途、触发方式和示例。6. 从技能到插件打包与分发当你开发了一个非常有用的技能并希望分享给其他项目或社区时就需要考虑将其打包为插件。6.1 插件与技能的关系回顾再次强调技能是工作流插件是包装。插件是一个更大的分发单元可以包含一个或多个技能。配置说明。图标、主题等界面资源。对 MCP 服务器的配置。6.2 使用技能安装器探索社区技能在考虑自己分发之前可以先使用内置的$skill-installer来安装他人分享的技能如果该技能已打包为插件并发布在已知仓库。例如尝试安装一个可能存在的linear项目管理工具集成技能codex $skill-installer linear这会将技能及其相关资源安装到你的用户全局或当前仓库技能目录中。这是快速扩展 Codex 能力的有效方式。6.3 创建你自己的插件高级创建插件涉及更多配置通常需要一个plugin.toml或类似的清单文件来描述插件元数据、包含的技能路径、依赖关系等。具体步骤请参考 Codex 官方文档中关于“构建插件”的章节。核心思路是将你的技能目录、agents/openai.yaml以及其他资源按照插件规范组织然后通过 Codex 的插件机制进行安装。7. 生产环境考量与安全将 Skills 用于生产环境或团队协作时需注意以下几点权限控制对于能执行脚本尤其是写操作、系统调用的技能要严格控制其使用范围和权限。避免技能被误用导致数据丢失或系统损坏。代码审查将技能定义文件SKILL.md,agents/openai.yaml, 脚本纳入团队的代码审查流程确保其安全性和符合规范。版本管理技能的迭代和变更应有记录。当技能逻辑更新后需要通知团队成员更新其本地的技能库或插件。环境隔离明确区分开发、测试、生产环境所使用的技能。例如部署技能应指向正确的环境端点避免误操作。错误处理在技能的指令或脚本中考虑加入基本的错误处理和用户提示让失败的情况也有清晰的反馈。通过系统地应用 Codex Skills你可以将大量重复、繁琐的开发操作转化为稳定、可复用的自动化流程。从创建一个简单的代码生成技能开始逐步构建起属于你个人或团队的智能体技能矩阵最终让 Codex 成为你开发工作中不可或缺的高效协作者。