OpenAI Codex Skills 进阶指南：从零构建可复用自动化工作流

30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度很多开发者朋友在安装好 OpenAI Codex 后发现它虽然强大但用起来总感觉“差点意思”——要么是让它写个脚本结果格式不符合团队规范要么是让它处理重复性任务每次都要重新描述一遍流程。这背后的核心原因往往是没有掌握Skills技能这个进阶玩法。Skills 是 Codex 的“肌肉记忆”和“工具箱”。它允许你将一套固定的指令、工作流甚至外部脚本打包成一个可复用的技能包。一旦配置好Codex 就能像调用一个内置函数一样稳定、准确地执行复杂任务极大提升自动化效率和结果的一致性。本文将带你从零开始在 20 分钟内彻底吃透 Codex Skills学会如何创建、组织、分发和优化技能从而搭建属于你自己的、可复用的自动化工作流。1. Codex Skills 核心概念从“聊天”到“工作流”在深入实操之前我们先厘清几个核心概念理解 Skills 为何是 Codex 进阶使用的关键。1.1 什么是 Codex Skills简单来说Skills 是封装了特定任务执行逻辑的指令包。它不仅仅是一段提示词Prompt而是一个包含以下要素的完整工作单元指令Instructions告诉 Codex 如何一步步完成任务的核心文本。元数据Metadata定义技能的名称、描述、触发条件等。参考资料References可选的文档、规范或示例为 Codex 提供上下文。脚本Scripts可选的、可执行的代码文件用于处理确定性操作或调用外部工具。Skills 与普通对话的区别普通对话中你需要每次向 Codex 描述任务背景、步骤和格式要求。而使用 Skills你只需说“请使用$代码审查技能”Codex 就会自动加载预设的、包含完整审查清单、安全规范和输出模板的指令集生成标准化的审查报告。这实现了从“一次性指导”到“标准化流程”的跃迁。1.2 Skills 与插件Plugins的关系这是两个容易混淆但层级不同的概念Skills技能是工作流的创作格式。它关注“如何做一件事”是功能逻辑本身。你可以在本地创建和测试技能。Plugins插件是技能的安装和分发单元。它关注“如何让其他人方便地使用这个技能”包含打包、分发、依赖管理和界面配置。最佳路径是先设计 Skill再考虑打包成 Plugin。当你有一个成熟的、希望分享给团队或社区的工作流时再将其封装为插件。1.3 Skills 如何工作“按需展开”的智能上下文管理Codex 采用了一种高效的上下文管理策略来使用 Skills理解这一点对技能设计至关重要启动扫描Codex 启动时会从多个预设路径后文详述扫描所有可用的 Skills。加载摘要此时它只读取每个 Skill 目录下SKILL.md文件中的name名称和description描述这两个元数据字段。这个过程非常轻量。构建技能列表Codex 会将这个精简的技能列表仅含名称和描述放入其初始上下文窗口供其判断当前任务适合调用哪个技能。为了避免挤占用于任务理解的上下文空间这个列表的大小被限制在模型上下文窗口的2%或最多 8000 个字符。如果技能太多Codex 会自动缩短描述文本。按需加载当用户显式调用如输入$skill-name或 Codex 根据任务描述隐式判断需要某个技能时它才会去完整读取该技能对应的SKILL.md文件内容将其指令加载到上下文中执行。这种“按需展开”的机制意味着技能的description字段至关重要。它必须清晰、简洁、准确地概括技能的用途和触发场景因为这是 Codex 决定是否调用该技能的唯一依据。2. 环境准备与技能目录结构在开始创建技能前你需要一个可用的 Codex 环境。Codex 支持通过 CLI命令行、IDE 扩展如 VS Code和独立的 Codex App 使用。本文以通用的 CLI/本地开发环境为例进行讲解。2.1 确认 Codex 安装与版本确保你的 Codex CLI 已正确安装并可以运行。打开终端输入以下命令检查codex --version你应该能看到类似codex 0.x.x的版本信息。如果未安装请参考官方文档进行安装。本文的操作基于 Codex 对 Skills 功能的通用支持细节可能随版本更新请以实际环境为准。2.2 理解技能的文件系统布局一个 Skill 在文件系统中就是一个标准的目录。其核心结构如下my-git-commit-skill/ # 技能根目录名称建议用短横线连接 ├── SKILL.md # 【必需】技能的核心指令与元数据文件 ├── scripts/ # 【可选】存放可执行脚本如 .sh, .py, .js │ └── validate_branch.py ├── references/ # 【可选】存放参考文档、规范文件 │ └── commit_convention.md ├── assets/ # 【可选】存放模板、图片等静态资源 │ └── commit_template.txt └── agents/ # 【可选】存放高级配置元数据 └── openai.yaml # 用于定义界面显示、调用策略和工具依赖关键文件说明SKILL.md这是技能的“大脑”。它是一个 Markdown 文件但文件开头必须包含一个 YAML Front Matter 块用于定义name和description。后续内容则是给 Codex 的详细指令。scripts/当你的工作流中某些步骤需要确定性的、程序化的操作例如运行一个 linter调用一个 API时可以将脚本放在这里。Codex 可以在执行技能时调用这些脚本。agents/openai.yaml这是一个高级配置文件用于在 Codex App 等图形界面中提供更好的用户体验例如自定义图标、颜色、以及声明该技能需要依赖哪些外部工具如特定的 MCP 服务器。3. 创建你的第一个技能Git 提交消息生成器让我们通过一个实战案例来学习创建技能的完整流程。我们将创建一个git-commit-helper技能它能够根据代码变更自动生成符合 Conventional Commits 规范的提交消息。3.1 方法一使用内置技能创建器推荐新手Codex 内置了一个交互式的技能创建向导$skill-creator。这是最快捷的入门方式。在终端中进入你希望创建技能的目录例如你的项目根目录。启动 Codex CLI 交互模式或直接在对话中键入命令# 启动 Codex CLI 后在对话中输入 $skill-creator创建器会引导你完成以下步骤技能名称输入git-commit-helper。技能描述输入根据代码变更自动生成符合 Conventional Commits 规范的 Git 提交消息。适用于 feat, fix, docs, style, refactor, test, chore 等类型。技能类型选择纯指令。对于这个任务我们只需要用自然语言指令 Codex 分析git diff并生成消息不需要外部脚本。创建器会自动在合适的目录通常是当前目录下的.agents/skills/生成技能文件夹和SKILL.md的草稿。3.2 方法二手动创建与编辑如果你想更精细地控制技能内容可以手动创建。创建技能目录结构# 在你的项目根目录或用户技能目录下 mkdir -p .agents/skills/git-commit-helper cd .agents/skills/git-commit-helper创建并编辑SKILL.md文件 使用你喜欢的文本编辑器如 VSCode, Vim, Nano创建SKILL.md文件。--- name: git-commit-helper description: 分析 git diff --staged 的输出自动生成符合 Conventional Commits 规范的提交消息。识别变更类型feat, fix, docs, style, refactor, test, chore并生成简洁的描述。 --- # Git 提交消息助手 当你被调用时请执行以下工作流 1. **获取变更**首先请求用户运行 git diff --staged --name-status 或提供类似的已暂存文件变更摘要。如果用户无法提供你可以指导他们如何获取。 2. **分析变更类型**根据变更的文件路径和状态M-修改A-新增D-删除R-重命名推断本次提交的主要类型 - feat: 新增功能。 - fix: 修复 bug。 - docs: 仅文档更改。 - style: 不影响代码含义的更改空格、格式化、分号等。 - refactor: 既不是修复 bug 也不是新增功能的代码重构。 - test: 添加或修改测试。 - chore: 构建过程或辅助工具的变动。 3. **生成消息主体**用一句话清晰描述这次提交的目的。使用祈使句、现在时态例如“修复用户登录时的空指针异常”而不是“修复了...”。 4. **组装完整消息**按照 type[optional scope]: description 格式输出。例如fix(auth): 处理登录时用户名缺失的情况。 5. **提供选项**如果可以根据变更分析提供 2-3 个不同侧重点的提交消息选项供用户选择。 6. **输出格式**最终输出应该清晰将推荐的提交消息用代码块包裹并附上简单的使用说明。 **示例交互** 用户“我修改了 src/auth/login.py 修复了一个空指针错误还更新了 README.md。” 你“看起来主要变更是修复fix和文档更新docs。由于代码修复是主要目的建议类型为 fix。以下是建议的提交消息” bash fix(login): 解决用户登录时用户名参数为空的异常你可以使用git commit -m fix(login): 解决用户登录时用户名参数为空的异常来提交。**关键点解析** - **Front Matter (--- 内)**定义了技能的“身份证”name和“招聘广告”description。description 必须精准因为 Codex 靠它来匹配任务。 - **指令部分**使用清晰的编号步骤、祈使句。明确输入git diff 输出、处理逻辑分析类型、输出格式Conventional Commits。提供了示例交互让 Codex 更好地理解预期行为。3.3 测试你的技能创建完成后你需要重启 Codex CLI 或 App让它重新扫描技能目录。重启 Codex如果你在运行 Codex 会话中创建了技能退出并重新启动它。触发技能在新的 Codex 会话中你可以尝试显式调用直接输入$git-commit-helper。隐式调用输入“帮我写一个 git 提交信息我刚刚修复了一个 bug”。Codex 会根据你的description自动匹配到git-commit-helper技能。如果技能被成功调用Codex 的回复风格和内容应该遵循SKILL.md中的指令它会引导你提供git diff信息然后生成格式化的提交消息。4. 技能的组织、管理与高级配置掌握了单个技能的创建后我们需要了解如何管理多个技能以及如何进行更精细的控制。4.1 技能的保存位置与作用域Codex 从四个层次的位置扫描技能优先级从高到低同名称技能不会合并会同时存在作用域典型路径用途说明REPO (仓库)$CWD/.agents/skills最常用。当前项目/仓库特有的技能如项目特定的代码生成规范。REPO (仓库)$REPO_ROOT/.agents/skills仓库根目录下的共享技能适合团队统一的工作流如统一的 PR 模板生成。USER (用户)$HOME/.agents/skills用户全局技能跨所有项目使用如个人常用的代码片段生成、日记助手等。ADMIN (系统)/etc/codex/skills系统级共享技能通常由管理员配置用于公司级别的标准操作流程。SYSTEM (内置)随 Codex 安装OpenAI 官方提供的基础技能如$skill-creator。最佳实践将项目相关的技能放在REPO作用域将个人通用技能放在USER作用域。你可以使用符号链接ln -s来灵活组织这些目录。4.2 启用、停用与配置技能你不需要通过删除文件来禁用一个技能。Codex 的全局配置文件~/.codex/config.toml允许你精细控制。找到或创建配置文件通常位于用户主目录下的.codex文件夹中。编辑配置以停用技能# ~/.codex/config.toml [[skills.config]] path /full/path/to/your/skill/SKILL.md # 技能的完整路径 enabled false # 将此技能禁用修改配置后需要重启 Codex 生效。配置技能参数一些高级技能可能支持通过配置传递参数具体需参考该技能的文档。4.3 为技能添加元数据 (agents/openai.yaml)为了让技能在 Codex App 等图形界面中更有好你可以添加一个元数据文件来定义其展示方式和行为策略。在技能目录下创建agents/openai.yaml文件interface: display_name: Git 提交助手 # 在界面上显示的名称 short_description: 自动生成规范的 Git 提交信息 # 更详细的界面描述 icon_small: ./assets/git-icon-small.svg # 小图标路径相对路径 icon_large: ./assets/git-icon-large.png # 大图标路径 brand_color: #F05032 # Git 的经典橙色用于界面主题 default_prompt: 请使用 git-commit-helper 技能分析我的代码变更并生成提交消息。 # 默认附带的提示词 policy: allow_implicit_invocation: true # 是否允许隐式调用。设为 false 则只能通过 $skill-name 显式调用。 dependencies: tools: - type: mcp value: git description: 访问本地 Git 仓库的 MCP 服务器 # transport 和 url 取决于具体的 MCP 服务器配置这个文件不是必须的但它能显著提升技能在集成环境中的用户体验。5. 从技能到插件分发与复用当你开发了一个非常有用的技能比如一个高级的数据库迁移检查技能并希望与团队成员或其他 Codex 用户分享时就需要考虑将其打包为插件Plugin。5.1 技能 vs. 插件何时转换坚持使用技能当你的工作流仅在当前项目或个人本地环境中使用时。升级为插件当你想实现以下目标时分发让其他人能通过简单的命令如codex plugins install安装你的技能。组合将多个相关的技能、工具配置MCP Servers、应用映射打包成一个功能集。集成交付将技能作为某个软件或服务的一部分一起交付给用户。5.2 使用技能安装器获取社区技能在将自己技能打包前你可以先体验如何安装他人分享的技能。Codex 可能提供类似$skill-installer的内置技能或插件管理命令。例如假设有一个共享的linear技能用于与 Linear 项目管理工具集成你可以尝试安装# 在 Codex 对话中或通过 CLI 命令 $skill-installer linear或者指定一个 Git 仓库地址$skill-installer https://github.com/username/awesome-codex-skill.git安装后重启 Codex 即可在技能列表中找到新技能。6. 设计高效技能的进阶最佳实践创建技能不难但创建出高效、稳定、精准的技能需要遵循一些原则。6.1 技能设计原则单一职责一个技能只做好一件事。不要创建“代码生成与数据库迁移与部署”这样的超级技能。将其拆分为$generate-api$create-migration$deploy-staging等多个技能。指令优先于脚本除非必要否则尽量用清晰的指令指导 Codex 完成工作而不是编写脚本。指令更灵活能利用 LLM 的推理能力脚本适用于确定性高、需调用外部 API 或复杂计算的场景。清晰的输入与输出在SKILL.md中明确说明技能期望的输入例如“请提供错误日志片段”和将产生的输出例如“我将输出一个包含根本原因和修复步骤的表格”。描述Description是门艺术description字段是技能的“搜索引擎优化”。把最核心的触发关键词放在前面。例如好为 Python 函数生成 Google 风格文档字符串。输入函数签名和简要说明。不够好这个技能可以帮助你生成文档它使用 Google 的格式规范适用于 Python...用真实场景测试创建技能后用各种相关的、不相关的提示词去测试它确保它在该触发时触发不该触发时保持沉默。6.2 一个带脚本的进阶技能示例代码风格检查纯指令技能适用于逻辑判断和文本生成。当需要与系统交互时就需要结合脚本。下面是一个code-lint技能的示例它调用一个 Python 脚本进行代码检查。目录结构code-lint/ ├── SKILL.md └── scripts/ └── run_linter.pySKILL.md内容--- name: code-lint description: 对指定的 Python 文件或目录运行预配置的代码风格检查基于 flake8 和 black并返回格式化的检查结果与修复建议。 --- # 代码风格检查技能 请你协调执行以下代码检查工作流 1. **确认目标**询问用户需要检查的 Python 文件路径或目录路径。 2. **验证环境**检查当前 Python 环境中是否已安装 flake8 和 black。如果没有提示用户安装。 3. **执行检查**调用附带的 run_linter.py 脚本并将用户提供的路径作为参数传递给该脚本。 4. **呈现结果**接收脚本的原始输出JSON 格式将其转换为易于阅读的格式分点列出 - 风格违规的数量和位置文件:行号:列号。 - 主要的违规类型如缩进、行过长、未使用导入等。 - 使用 black 进行自动格式化的建议命令。 5. **提供后续步骤**询问用户是否希望直接运行 black 进行格式化。 **注意**你不需要自己执行 flake8 或 black 命令只需调用 scripts/run_linter.py 并处理其输出。scripts/run_linter.py内容#!/usr/bin/env python3 import subprocess import sys import json import os def run_linter(path): 运行 flake8 并返回 JSON 格式结果 if not os.path.exists(path): return {error: f路径不存在: {path}} # 运行 flake8输出为可解析的格式 cmd [flake8, --formatjson, path] try: result subprocess.run(cmd, capture_outputTrue, textTrue, timeout30) if result.returncode 0: # 没有错误返回空列表 issues [] else: # 解析 flake8 的 JSON 输出 issues json.loads(result.stdout) except json.JSONDecodeError: issues {raw_output: result.stdout, stderr: result.stderr} except subprocess.TimeoutExpired: return {error: 检查超时} except FileNotFoundError: return {error: 未找到 flake8 命令请通过 pip install flake8 安装} # 获取 black 检查建议 black_cmd [black, --check, --diff, path] try: black_result subprocess.run(black_cmd, capture_outputTrue, textTrue) needs_format black_result.returncode ! 0 black_diff black_result.stdout if needs_format else except FileNotFoundError: needs_format False black_diff black 未安装 return { path: path, flake8_issues: issues, needs_black_formatting: needs_format, black_diff_suggestion: black_diff, black_command: fblack {path} } if __name__ __main__: if len(sys.argv) ! 2: print(json.dumps({error: 请提供一个文件或目录路径作为参数})) sys.exit(1) target_path sys.argv[1] output run_linter(target_path) print(json.dumps(output, indent2))这个例子展示了如何将确定性的、需要特定工具flake8, black和复杂参数处理的任务封装在脚本中而让 Codex 负责与用户交互、解释结果和提供建议。这是一种强大的混合模式。7. 常见问题与排查指南在创建和使用 Skills 过程中你可能会遇到以下问题问题现象可能原因排查与解决思路技能创建后在 Codex 中不显示或无法调用。1. Codex 未重启。2. 技能未放在正确的扫描路径。3.SKILL.md格式错误如 Front Matter 缺失或格式不对。1.重启 Codex。2. 检查技能目录是否在$CWD/.agents/skills或$HOME/.agents/skills下。3. 检查SKILL.md开头是否有正确的---包裹的name和description。技能被错误地隐式触发在不该出现时出现。description字段描述过于宽泛或包含了常见词汇。优化description使其更精确。例如将“处理文件”改为“解析 CSV 文件并提取特定列”。也可以在agents/openai.yaml中设置allow_implicit_invocation: false。技能被调用但 Codex 没有遵循指令。1. 指令过于模糊或复杂。2. 上下文窗口限制长指令被截断。3. 技能逻辑与 Codex 的基础能力不匹配。1. 将复杂指令拆分为更小、更清晰的步骤。2. 确保SKILL.md核心指令部分简洁。将参考材料移入references/目录让 Codex 按需读取。3. 确保你要求 Codex 做的是它擅长的事文本生成、分析、规划而非替代专业软件。带脚本的技能执行失败。1. 脚本文件没有执行权限。2. 脚本依赖的外部工具未安装。3. 脚本路径引用错误。1. 为脚本添加执行权限chmod x scripts/your_script.sh。2. 在技能指令中明确说明前提依赖或在脚本中做友好错误检查。3. 在指令中明确说明脚本的位置和调用方式。在团队中共享技能其他人看不到。技能放在个人目录 ($HOME/.agents/skills)而非项目仓库目录。将技能目录置于项目根目录的.agents/skills/下并提交到版本控制系统如 Git中。8. 工程化建议与学习路径8.1 将 Skills 融入开发工作流标准化团队操作为团队创建统一的技能库如$generate-crud生成增删改查代码、$pr-description生成 PR 描述模板、$db-migration-check检查数据库迁移脚本。个人效率工具箱创建个人技能如$daily-standup生成每日站会汇报、$code-review-checklist调出代码审查清单、$explain-error分析错误日志。与 CI/CD 结合探索将 Codex 与 Skills 作为 CI/CD 流程中的一环例如自动生成变更日志、检查提交信息规范性等。8.2 持续优化你的技能迭代技能不是一次写成的。根据使用反馈不断调整description和指令。版本化将技能目录纳入 Git 管理记录其演变。文档化在SKILL.md或references/中添加详细的使用示例和边界条件说明。测试集为关键技能维护一组测试用例输入和期望输出确保其行为稳定。8.3 下一步探索方向掌握了基础技能创建后你可以进一步探索插件开发学习如何将技能打包成插件进行版本管理和分发。MCP 服务器集成让技能能够连接外部工具和数据源如数据库、JIRA、Slack实现更强大的自动化。复杂工作流编排结合 Codex 的“子智能体”和“工作流”功能用多个技能协作完成复杂项目。探索社区技能库关注 OpenAI 官方或社区分享的技能集学习他人的设计模式。Codex Skills 是将 AI 助手从“通用聊天伙伴”转变为“专业工作伙伴”的关键。通过将你日常重复的、需要固定流程的任务封装成技能你不仅为自己和团队构建了一个不断成长的自动化资产库更是真正意义上在塑造一个专属的、高效的 AI 协作环境。现在就从创建一个解决你当下最繁琐任务的技能开始吧。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度