OpenAI Codex Skills 实战指南：从零构建 AI 自动化工作流-平芜编程栈

如果你已经安装了 OpenAI Codex，但感觉它除了聊天和写代码之外，好像没发挥出真正的威力，那问题很可能出在“技能”（Skills）上。Codex 本身是一个强大的智能体平台，而 Skills 是解锁其自动化工作流能力的核心钥匙。简单来说，Skills 就是一套标准化的“任务说明书”，它把复杂的操作指令、参考文档甚至可执行脚本打包在一起，让 Codex 能稳定、可复用地执行特定任务，比如自动生成 API 文档、执行代码审查、或者处理 Git 工作流。

这篇文章不讲复杂的理论，直接带你上手实操。我们会从零开始，搞清楚 Codex Skills 到底是什么、怎么安装、如何创建自己的技能，以及如何利用它搭建可复用的自动化流程。无论你是想提升个人开发效率，还是为团队构建标准化的 AI 助手，掌握 Skills 都是进阶使用的必经之路。

1. 核心能力速览

在深入细节之前，我们先通过一个表格快速了解 Codex Skills 的核心特性，让你判断它是否是你需要的工具。

能力项	说明
项目类型	智能体（Agent）任务级能力扩展与工作流封装标准。
核心功能	将复杂、多步骤的指令、参考资料和脚本打包成可复用的“技能”（Skill），供 Codex 智能体调用，实现工作流自动化。
硬件/环境门槛	无特殊硬件要求。主要依赖已安装并正常运行的 Codex 环境（CLI、App 或 IDE 扩展）。
启动与使用方式	技能本身非独立服务，随 Codex 启动自动加载。可通过 Codex 界面中的`/skills`命令显式调用，或由 Codex 根据任务描述隐式匹配触发。
接口/API能力	技能主要通过 Codex 的交互界面（聊天、命令行）触发。高级技能可集成外部工具或 MCP 服务器，实现 API 调用。
批量任务支持	支持。可通过编写技能脚本或结合外部自动化工具（如 n8n, GitHub Actions）来处理批量任务。
技能分发形式	支持本地目录管理、Git 仓库共享，以及通过“插件”（Plugin）形式进行标准化分发和安装。
主要适用场景	1.个人效率：自动化重复开发任务（如代码生成、Commit 信息优化、文档起草）。 2.团队规范：统一代码审查、API 设计、部署流程。 3.复杂工作流：串联多个步骤，如“获取 Issue -> 分析 -> 编码 -> 测试 -> 提交”。

2. 适用场景与使用边界

Codex Skills 不是万能的，理解其边界能帮你更好地应用它。

它非常适合以下场景：

固化最佳实践：当你有一套成熟的、经常重复的操作流程（例如为新微服务生成标准目录结构），可以将其封装成技能，确保每次执行都一致、完整。
降低使用门槛：对于不熟悉特定领域（如 Kubernetes YAML 编写）的团队成员，一个封装好的技能可以引导他们完成正确操作。
连接外部系统：通过技能内嵌脚本或调用 MCP 服务器，让 Codex 能与你的内部 Wiki、项目管理工具（如 Linear）、监控系统交互。
教育与引导：为新员工或实习生创建“ onboarding ”技能，引导他们完成开发环境配置、项目熟悉等步骤。

它可能不适合或需注意：

高度动态、无固定模式的任务：需要大量临场判断和创造性发挥的任务，技能可能限制 Codex 的灵活性。
对执行确定性要求极高：虽然技能提供了更稳定的工作流，但基于大语言模型的输出仍存在一定随机性。关键生产步骤应有复核机制。
安全与权限：技能可能执行脚本或访问网络资源。务必确保技能来源可信，并理解其执行的操作，避免引入安全风险。严禁在技能中嵌入任何可能危害系统安全、侵犯隐私或绕过合规检查的指令。
版权与合规：如果技能用于生成内容（如文档、代码），需确保其引用的参考资料和生成的输出符合相关版权和合规要求。

3. 环境准备与前置条件

开始创建和使用 Skills 前，你需要一个可用的 Codex 环境。

已安装 Codex：确保你已经在本地安装了 OpenAI Codex。它通常以三种形式提供：
- Codex CLI：命令行工具。
- Codex App：桌面应用程序。
- IDE 扩展：如 VS Code 插件。本文的演示和命令主要以 CLI 和 App 环境为准，原理相通。
基础目录结构认知：了解 Codex 查找技能的路径。技能可以存放在多个位置，Codex 会按优先级扫描。最常用的个人技能目录是~/.agents/skills/（用户级）和项目内的.agents/skills/（仓库级）。
文本编辑器：用于创建和编辑技能的核心文件SKILL.md。
（可选）脚本知识：如果你的技能需要执行自动化操作，可能需要编写简单的 Shell、Python 或其他语言的脚本。

4. 安装部署与启动方式

Skills 无需单独“安装”，它们是随着 Codex 启动而加载的。这里所谓的“安装部署”指的是如何让 Codex 发现并使用你创建或获取的技能。

4.1 技能文件的存放位置

Codex 会从以下位置扫描技能目录，优先级通常从具体到通用：

技能范围	默认路径示例	用途说明
REPO (仓库)	`./.agents/skills/`	当前项目独有技能。
REPO (父目录)	`../.agents/skills/`	在项目子目录时，使用父目录共享技能。
REPO (根目录)	`$REPO_ROOT/.agents/skills/`	整个 Git 仓库共享的团队技能。
USER (用户)	`~/.agents/skills/`	用户全局技能，所有项目可用。
ADMIN (系统)	`/etc/codex/skills/`	系统级共享技能，需管理员权限。
SYSTEM (内置)	Codex 安装包内	OpenAI 官方提供的基础技能。

操作步骤：

为你想要存放技能的位置创建.agents/skills目录。例如，创建一个全局技能：
```
mkdir -p ~/.agents/skills
```
在此目录下，每个技能都是一个独立的子文件夹。

4.2 安装社区技能

除了自己创建，你可以安装他人分享的技能。Codex 提供了$skill-installer这个内置技能来简化安装过程。

在 Codex CLI 或 App 的聊天界面中，输入：
```
$skill-installer
```
Codex 会引导你操作。例如，要安装一个名为 “linear” （可能与 Linear 项目管理工具集成）的技能，可以输入：
```
$skill-installer linear
```
安装器可能会从 GitHub 等仓库下载技能包，并放置到正确的技能目录（通常是用户目录~/.agents/skills/）。
安装后，重启 Codex 以确保新技能被正确加载和识别。

5. 功能测试与效果验证：创建你的第一个技能

理论说再多不如动手做。我们来创建一个最简单的技能，验证整个流程。

5.1 测试目标：创建一个“生成 Git 提交信息”技能

这个技能将引导 Codex 根据代码变更，生成符合约定式提交（Conventional Commits）规范的提交信息。

5.2 操作步骤

第一步：创建技能目录和文件

进入你的用户技能目录：
```
cd ~/.agents/skills
```
为技能创建一个新目录，名称即技能 ID：
```
mkdir generate-commit-msg cd generate-commit-msg
```
创建核心文件SKILL.md：
```
touch SKILL.md
```

第二步：编写 SKILL.md 内容用文本编辑器打开SKILL.md，输入以下内容：

--- name: generate-commit-msg description: Analyzes `git diff` output and generates a concise, well-formatted commit message following the Conventional Commits specification. Use this when the user asks about commits, commit messages, or wants to summarize changes. --- # Generate Commit Message Skill ## Instruction You are an expert at writing Git commit messages. When this skill is invoked, your task is to generate a professional commit message based on the provided code changes. ## Workflow 1. **Understand Changes**: First, ask the user to provide the output of `git diff --staged` or `git diff` (if no staging). If not provided, guide them to run it. 2. **Analyze Diff**: Carefully review the diff output. Categorize the changes (e.g., feat, fix, docs, style, refactor, test, chore). 3. **Draft Message**: * **Type**: Start with a conventional commit type (`feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:`). * **Scope**: Optionally add a scope in parentheses (e.g., `feat(api):`). * **Subject**: Write a concise, imperative-mood summary (under 50 chars). Example: "add user authentication endpoint". * **Body**: (Optional) Provide a more detailed explanation, focusing on the *why* not the *what*. Separate from subject with a blank line. * **Footer**: (Optional) Reference issue trackers (e.g., `Closes #123`). 4. **Present & Revise**: Offer the drafted message to the user. Ask if they'd like any modifications (e.g., change type, rephrase subject, add body/footer). ## Examples **User Input (git diff):** ```diff // user_service.py + def create_user(username, email): + # New function to create a user in the database + db.insert(User(username=username, email=email))

Good Output:

feat(user): add create_user function - Implements the `create_user` function in `user_service.py`. - Handles basic user creation logic for database insertion. Closes #45

Trigger Phrases

“Write a commit message for these changes.”
“Generate a commit msg.”
“Help me commit this.”
“What should my commit message be?”

**关键点解析：** * `---` 之间的部分是技能元数据，`name` 是调用标识，`description` 至关重要，它决定了 Codex 何时会隐式触发此技能。描述要简洁、准确。 * 正文部分用清晰的指令和步骤告诉 Codex 该做什么。提供了示例和触发词，帮助 Codex 更好地理解使用场景。 **第三步：重启 Codex 并测试** 1. 保存 `SKILL.md` 后，**重启你的 Codex App 或 CLI 会话**。这是为了让 Codex 重新扫描技能目录。 2. 在 Codex 界面中，你可以尝试显式调用： ``` /skills ``` 然后在列表中选择 `generate-commit-msg`，或者直接输入： ``` $generate-commit-msg ``` 3. 更自然的测试是隐式触发。直接对 Codex 说：“我刚修改了 `api.py` 文件，帮我写个提交信息。” 如果描述写得好，Codex 应该会自动匹配并启用 `generate-commit-msg` 技能来引导你完成后续步骤。 ### 5.3 预期结果与验证 * **成功标志**：Codex 的回复模式发生变化，它会按照 `SKILL.md` 中定义的流程，先向你索要 `git diff` 内容，然后分析并生成结构化的提交信息建议。 * **效果验证**：对比使用技能前后 Codex 的回应。未使用技能时，它可能只会生成一个普通的句子；使用技能后，其输出应严格遵循约定式提交的格式，并且交互过程更有引导性。 * **常见问题**： * **技能未出现**：检查技能目录路径是否正确，`SKILL.md` 的 YAML 头格式是否正确，并确保已重启 Codex。 * **未隐式触发**：优化 `description` 字段，加入更具体、更可能被用户说出的触发关键词。 * **流程不符合预期**：检查 `SKILL.md` 中的指令是否足够清晰、无歧义。可以添加更多示例。 ## 6. 接口 API 与批量任务 Skills 本身不直接提供 HTTP API，但它是构建自动化工作流的核心模块。你可以通过两种主要方式实现“类 API”调用和批量处理。 ### 6.1 通过 CLI 实现脚本化调用 你可以编写 Shell 或 Python 脚本，通过 Codex CLI 以非交互方式调用特定技能。 **示例：批量处理多个 Git 仓库的提交信息生成** 假设你有多个项目目录需要生成统一的提交信息模板。 1. **创建一个脚本 `batch_commit_msg.sh`**: ```bash #!/bin/bash # 遍历所有项目目录 for project_dir in /path/to/projects/*/; do if [ -d "$project_dir/.git" ]; then echo "Processing $project_dir" cd "$project_dir" # 获取暂存区的变更 DIFF_OUTPUT=$(git diff --staged 2>/dev/null) if [ -n "$DIFF_OUTPUT" ]; then # 调用 Codex CLI，使用 generate-commit-msg 技能 # 注意：这里需要根据实际 Codex CLI 的调用方式调整，以下为示例 COMMIT_MSG=$(codex --skill generate-commit-msg --input "$DIFF_OUTPUT" --non-interactive) echo "Generated commit message:" echo "$COMMIT_MSG" echo "---" # 实际应用提交（谨慎使用，建议先预览） # git commit -m "$COMMIT_MSG" else echo "No staged changes in $project_dir" fi fi done ``` *注意：上述 `codex --skill ...` 命令为示例，实际 Codex CLI 的批处理调用参数可能不同，请查阅官方文档。* 2. **技能增强以支持非交互输入**：为了让技能支持从管道或参数读取 `git diff`，你可以在 `SKILL.md` 的指令部分增加判断逻辑，例如：“如果输入内容以 `diff --git` 开头，则直接将其视为 diff 内容进行分析，无需询问用户。” ### 6.2 集成到自动化工作流（如 n8n, GitHub Actions） 你可以将“调用 Codex 技能”作为一个步骤，嵌入到更广泛的自动化工作流中。 **GitHub Actions 示例概念**： ```yaml name: Auto-Generate PR Description on: pull_request: types: [opened, synchronize] jobs: generate-description: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Codex CLI run: | # 假设有方式在 Actions 中安装/配置 Codex CLI echo "Installing Codex CLI..." - name: Get changed files id: changes uses: tj-actions/changed-files@v41 - name: Generate PR description via Skill env: DIFF_CONTENT: ${{ steps.changes.outputs.all_changed_files }} run: | # 调用一个假设存在的“分析PR变更”技能 DESCRIPTION=$(codex-cli --skill analyze-pr-changes --input "$DIFF_CONTENT") echo "PR_DESCRIPTION<<EOF" >> $GITHUB_ENV echo "$DESCRIPTION" >> $GITHUB_ENV echo "EOF" >> $GITHUB_ENV - name: Update PR Description uses: peter-evans/create-pull-request@v5 with: body: ${{ env.PR_DESCRIPTION }}

这个例子展示了如何将技能作为 CI/CD 流水线的一环，实现自动化的 PR 描述生成。

7. 资源占用与性能观察

Codex Skills 机制本身对系统资源的占用微乎其微，主要开销来自于运行 Codex 智能体以及执行技能时可能调用的语言模型。

技能加载开销：Codex 采用“按需展开”策略。启动时，它只读取所有技能的name和description（总字符数有限制），几乎不占额外内存。只有当某个技能被触发时，其完整的SKILL.md内容才会被加载到上下文中。因此，安装大量技能不会显著影响启动速度或初始内存占用。
上下文长度管理：技能描述会被缩短以适应上下文窗口（通常限制在窗口的2%或8000字符）。这意味着为技能编写精准、关键的描述至关重要，确保即使被截断，核心触发词仍在前部。
脚本执行开销：如果技能包含scripts/并执行了外部命令或调用 MCP 服务器，则会产生相应的进程开销（CPU、内存、网络）。这取决于脚本本身的内容。
观察方法：
- 通过系统监控工具（如htop,任务管理器）观察 Codex 主进程的资源使用情况。
- 技能执行复杂任务或长时间运行时，资源占用会相应增加。
- 如果遇到性能问题，首先检查是否是底层语言模型调用（如 GPT-4）导致的延迟或高负载，其次检查技能中的脚本是否有效率瓶颈。

8. 常见问题与排查方法

问题现象	可能原因	排查方式	解决方案
技能在列表中不显示	1. 技能目录位置错误。 2.`SKILL.md`文件缺失或格式错误（如 YAML 头格式不对）。 3. Codex 未重启。	1. 检查技能是否放在正确的扫描路径下（如`~/.agents/skills/`）。 2. 检查`SKILL.md`是否存在，且`---`分隔符内的`name`和`description`字段完整。 3. 重启 Codex。	1. 将技能移动到正确目录。 2. 修正`SKILL.md`格式。 3. 重启 Codex 应用或会话。
技能未被隐式触发	1.`description`描述不够精准或未包含用户常用词汇。 2. 技能过多，描述被截断后关键信息丢失。 3. 用户查询与技能描述匹配度低。	1. 查看技能的`description`，确保它清晰说明了何时使用、何时不使用。 2. 在 Codex 中尝试显式调用`$skill-name`看是否有效。	1. 重写`description`，把核心触发词放在最前面。 2. 精简技能描述，使其更简短有力。 3. 考虑使用显式调用，或在`agents/openai.yaml`中设置`allow_implicit_invocation: false`并引导用户显式使用。
技能执行流程不符合预期	`SKILL.md`内的指令不够清晰、有歧义，或步骤逻辑有问题。	仔细阅读`SKILL.md`的指令部分，模拟 Codex 的视角看是否每一步都明确。	1. 将指令分解为更小、更明确的步骤。 2. 使用祈使句。 3. 增加输入输出示例。 4. 在真实对话中测试并迭代优化指令。
技能中的脚本无法执行	1. 脚本文件没有执行权限。 2. 脚本依赖的环境或命令在 Codex 运行环境中不存在。 3. 路径错误。	1. 检查`scripts/`目录下的文件权限 (`chmod +x`)。 2. 在 Codex 的运行环境（如终端）中手动执行脚本，看是否报错。 3. 检查脚本中的路径是否为绝对路径或相对于技能目录的正确路径。	1. 添加执行权限。 2. 确保环境依赖已安装，或在技能文档中注明前置条件。 3. 使用绝对路径或相对于技能根目录的路径。
安装社区技能失败	1. 网络问题导致下载失败。 2. 技能源仓库不存在或已更改。 3. 安装器 (`$skill-installer`) 内部错误。	1. 检查网络连接。 2. 尝试手动从 GitHub 等源下载技能包，并放置到正确的技能目录。 3. 查看 Codex 的错误日志。	1. 手动下载并安装技能。 2. 联系技能作者或寻找替代技能。
Codex 提示技能太多，部分被忽略	安装的技能总数过多，初始技能列表超出了上下文预算。	Codex 启动时会在日志或界面给出警告。	1. 停用不常用的技能（通过`~/.codex/config.toml`设置`enabled = false`）。 2. 合并功能相似的技能。 3. 优先使用仓库级技能，减少全局技能数量。

9. 最佳实践与使用建议

技能设计原则：
- 单一职责：一个技能只做好一件事。例如，“生成提交信息”和“运行单元测试”应该是两个独立的技能。
- 指令优先：尽量用清晰的文字指令描述工作流，而不是依赖复杂脚本。这使技能更易理解、维护和跨平台。
- 明确边界：在description和指令中清晰定义技能的适用范围和不适用范围，避免误触发。
开发与测试流程：
- 从简单开始：先用“纯指令”技能验证想法和流程，成功后再考虑加入脚本。
- 真实场景测试：用你期望用户会说的真实提示词去测试技能的触发和执行效果。
- 迭代优化：根据测试反馈，不断调整description和指令细节。
工程化管理：
- 版本控制：将技能目录（尤其是团队共享的.agents/skills）纳入 Git 管理。
- 分目录存放：在~/.agents/skills/下可以按项目或功能创建子目录，用符号链接 (ln -s) 组织，保持结构清晰。
- 配置化管理：利用~/.codex/config.toml统一管理技能的启用/停用状态，方便在不同环境间切换。
安全与合规：
- 审核外部技能：从社区安装技能前，检查其SKILL.md和脚本内容，避免执行恶意代码。
- 最小权限：技能脚本应遵循最小权限原则，避免不必要的sudo或高风险操作。
- 敏感信息：不要在技能文件中硬编码 API 密钥、密码等敏感信息。使用环境变量或 Codex 的安全配置功能。
进阶：从技能到插件：
- 当你的技能稳定且希望分享给更多人时，考虑将其打包成插件（Plugin）。插件是更正式的分发格式，可以包含技能、界面配置和资源文件。
- 使用$skill-creator或参考官方文档，开始你的第一个插件项目。