从对话到能力：20分钟构建你的第一个Codex Skill实现工作流自动化

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

你装好了 Codex，看着它在你面前运行，但总感觉哪里不对。它好像什么都懂一点，又好像什么都做不深。你让它写个脚本，它写了；你让它分析日志，它也分析了。但每次都是“一次性”的对话，下次遇到类似问题，又得从头解释一遍，甚至还得纠正它上次犯过的错误。你隐约觉得，这个强大的工具不应该只是个“高级聊天机器人”，它应该能记住你的工作方式，能复用成功的经验，能像一个真正的助手一样，把零散的操作沉淀成一套可靠的流程。

这种感觉，就像你拿到了一把瑞士军刀，却只用它来拧螺丝。Codex 真正的威力，不在于它能回答多少问题，而在于它能通过Skills（技能），将一次性的指令固化、封装、复用，最终构建出属于你自己的自动化工作流。很多人卡在“装好不会用”的阶段，问题往往不是出在模型能力上，而是没有掌握这套将“对话”升级为“能力”的核心机制。

今天，我们不谈复杂的底层原理，就从最实际的场景出发，聊聊如何用 20 分钟理解并开始构建你的第一个 Codex Skill，让 AI 智能体真正成为你工作流中可预测、可复用的一环。

1. 从“一次性对话”到“可复用技能”：理解 Skills 的本质

很多人对 Codex Skills 的第一印象是“高级一点的提示词模板”。这个理解只对了一半，而且是比较浅的那一半。如果 Skills 只是模板，那它和你在笔记里存一段文本没什么区别。Skills 的核心价值，在于它定义了一个完整的、可被智能体理解和稳定执行的“任务单元”。

1.1 Skills 解决了什么根本问题？

在没有 Skills 之前，你和 Codex 的交互模式是“问答驱动”的。你描述问题，它生成回答。这种模式存在几个天然缺陷：

1. 上下文依赖性强：每次都需要你提供完整的背景信息，智能体没有“记忆”你偏好的处理方式。
2. 结果不可预测：同样的指令，在不同上下文或模型状态下，可能产生风格、格式甚至逻辑不同的输出。
3. 无法沉淀经验：你花时间调教出来的、针对某个特定任务（比如“生成符合团队规范的 API 接口代码”）的最佳提示词，无法方便地保存和复用。
4. 难以集成复杂操作：对于需要多步骤、调用外部工具（如执行脚本、读取文件、调用 API）的任务，纯聊天界面难以清晰、稳定地组织。

Skills 的出现，就是为了将这种临时的、不稳定的“对话”，转变为持久的、可预测的“能力”。一个 Skill 至少包含三个部分：

• 指令（Instructions）：告诉 Codex “做什么”和“怎么做”。这是核心。
• 元数据（Metadata）：主要是name和description，告诉 Codex “我是什么”以及“在什么情况下应该调用我”。
• 可选资源（Optional Assets）：如脚本（scripts/）、参考资料（references/）、资源文件（assets/）等，为指令的执行提供必要的工具和上下文。

1.2 Skills 与插件（Plugins）的区别：创作与分发

这是另一个容易混淆的概念。根据官方文档的清晰界定：

• Skill（技能）是“可复用工作流”的创作格式。它的核心是设计工作流本身。你关心的是如何把一件事的步骤、规则、边界定义清楚。
• Plugin（插件）是“可安装分发单元”。它的核心是打包和分发。当你设计好一个或多个 Skills，希望分享给团队、集成到应用，或者进行版本管理时，才需要将其打包成 Plugin。

简单来说：先有 Skill，后有 Plugin。对于绝大多数个人开发者和团队内部使用场景，你只需要专注于创建和优化 Skills。只有当需要跨项目、跨团队共享或进行商业化集成时，才需要考虑 Plugin。

1.3 “按需展开”的上下文管理：Skills 如何保持高效

一个常见的担忧是：如果我安装了很多 Skills，会不会把宝贵的模型上下文窗口（Context Window）塞满，影响主要任务的执行？

Codex 采用了一种聪明的“按需展开（On-demand Expansion）”机制：

1. 启动时：Codex 只读取每个 Skill 目录下的SKILL.md文件中的name和description等元数据，生成一个轻量级的技能列表。这个列表最多只占用模型上下文窗口的 2%（如果窗口大小未知，则上限为 8000 个字符）。如果技能太多，Codex 甚至会智能地缩短描述来满足这个预算。
2. 运行时：只有当 Codex 根据当前对话判断某个 Skill 可能被需要，或者你显式调用了某个 Skill（如输入$skill-name）时，它才会将这个 Skill 的完整SKILL.md指令内容加载到上下文中。

这意味着，你可以放心地安装和管理数十甚至上百个 Skills，而无需担心它们会拖慢或干扰日常的、与这些 Skills 无关的对话。智能体只在需要时才“展开”完整的技能手册。

2. 手把手创建你的第一个 Skill：从想法到可执行工作流

理论说再多，不如动手做一个。我们以一个非常实际且常见的开发场景为例：“为现有函数生成单元测试”。

2.1 规划你的 Skill：明确输入、输出与边界

在动手写代码或指令之前，先想清楚：

• 触发条件（When）：我什么时候会想用这个 Skill？比如：“当我有一段核心业务逻辑代码，需要确保其健壮性时”。
• 输入（Input）：我需要提供给 Skill 什么？通常是一段代码（函数/类），可能还有语言、测试框架偏好（如 pytest, Jest）。
• 输出（Output）：我希望得到什么？一套完整的、可运行的、覆盖了主要路径和边界条件的单元测试代码。
• 边界（Boundaries）：这个 Skill不应该做什么？比如，它不应该去修改原始的生产代码，不应该处理非代码的文本分析。

把这些想清楚，你的description和指令就会非常精准。

2.2 创建 Skill 目录与核心文件

Skill 就是一个具有特定结构的目录。在你的项目根目录或用户目录下，创建一个新目录，例如generate-unit-tests。

mkdir -p ~/.agents/skills/generate-unit-tests cd ~/.agents/skills/generate-unit-tests

接下来，创建最核心的文件SKILL.md：

--- name: generate-unit-tests description: Generates comprehensive unit tests for a given function or class code snippet. Focus on edge cases, mocking dependencies, and high coverage. Trigger when user provides code and asks for tests. --- # 单元测试生成技能 ## 目标 为用户提供的函数或类代码生成高质量、可执行的单元测试。 ## 输入 1. 待测试的源代码（必需）。 2. 编程语言（如 Python、JavaScript）。如果未指定，尝试从代码语法推断。 3. 首选的测试框架（如 `pytest` for Python, `Jest` for JavaScript）。如果未指定，使用该语言最流行的框架。 ## 输出 1. 一个完整的测试文件或测试代码块。 2. 测试应包含： * 对主要功能路径的测试。 * 对边界条件（如空输入、极值、非法参数）的测试。 * 必要的模拟（Mock）或桩（Stub），用于隔离外部依赖。 * 清晰的测试描述（Test Description）。 3. 在测试代码上方，用注释简要说明测试策略和覆盖的重点。 ## 步骤 1. **分析代码**：理解函数/类的输入、输出、副作用和依赖。 2. **识别测试点**：列出所有需要测试的逻辑分支、边界条件和异常场景。 3. **选择框架**：根据输入或语言惯例确定测试框架。 4. **构建测试用例**： * 为每个测试点创建独立的测试函数/方法。 * 使用 `Arrange-Act-Assert` 或 `Given-When-Then` 模式组织测试。 * 合理设置和清理测试环境（如 `setUp`/`tearDown`）。 5. **处理依赖**：识别外部依赖（如数据库、API、文件系统），并说明如何模拟它们（例如，使用 `unittest.mock` 或 `Jest.fn`）。 6. **生成代码**：输出格式良好的测试代码，包含必要的导入语句。 ## 示例（Python/pytest） **用户输入：** ```python def calculate_discount(price: float, is_member: bool) -> float: if price <= 0: raise ValueError("Price must be positive") discount = 0.1 if is_member else 0.0 return price * (1 - discount)

Skill 输出：

import pytest from your_module import calculate_discount """ 测试策略： 1. 验证正常情况：会员和非会员的价格计算。 2. 验证边界条件：价格为0或负数的异常处理。 3. 验证浮点数计算精度。 """ def test_calculate_discount_member(): """测试会员折扣计算""" # Arrange price = 100.0 is_member = True # Act result = calculate_discount(price, is_member) # Assert assert result == 90.0 # 100 * (1 - 0.1) def test_calculate_discount_non_member(): """测试非会员（无折扣）计算""" # Arrange & Act result = calculate_discount(100.0, False) # Assert assert result == 100.0 def test_calculate_discount_zero_price(): """测试价格为0时抛出异常""" with pytest.raises(ValueError, match="Price must be positive"): calculate_discount(0.0, True) def test_calculate_discount_negative_price(): """测试价格为负数时抛出异常""" with pytest.raises(ValueError, match="Price must be positive"): calculate_discount(-50.0, False) # 可选：测试浮点数精度 def test_calculate_discount_float_precision(): result = calculate_discount(33.33, True) # 使用 pytest.approx 处理浮点数比较 assert result == pytest.approx(29.997, rel=1e-9)

不适用场景

• 生成集成测试或端到端测试。
• 为整个代码库生成测试（本技能针对片段）。
• 运行测试或计算覆盖率（需要额外工具）。

### 2.3 让 Skill 更强大：加入脚本和参考资料 纯指令型 Skill 已经很强大了，但有时你需要 Codex 执行一些确定性的操作。这时可以在 `scripts/` 目录下放置可执行脚本。 例如，创建一个 `scripts/setup_test_env.sh`，用于在生成测试后，自动安装依赖并运行一次测试（假设是 Python 项目）： ```bash #!/bin/bash # scripts/setup_test_env.sh # 这是一个示例脚本，Skill 可以建议用户运行它。 echo "Setting up Python test environment..." python -m pip install --upgrade pip pip install pytest pytest-cov echo "Running generated tests to verify..." # 假设生成的测试文件是 test_generated.py if [ -f "test_generated.py" ]; then python -m pytest test_generated.py -v else echo "Generated test file not found. Please check the output." fi

在SKILL.md的步骤中，你可以增加一条：“6.（可选）验证：你可以运行./scripts/setup_test_env.sh来安装测试框架并运行生成的测试。”

同样，references/目录可以放一些团队内部的测试规范文档，assets/目录可以放一些测试模板文件。Codex 在执行 Skill 时，可以引用这些资源。

2.4 测试与触发你的 Skill

创建完成后，重启 Codex（如果它正在运行）。Codex 会自动扫描并加载新技能。

现在，你有两种方式使用它：

1. 隐式调用：直接在聊天框里说：“帮我为下面的函数写单元测试，用 pytest。” 然后粘贴代码。Codex 会识别你的意图与generate-unit-tests技能的 description 匹配，自动应用该技能的指令来生成测试，结果会比普通对话更结构化、更符合规范。
2. 显式调用：在输入中直接引用技能名，如：“$generate-unit-tests请为以下代码生成测试：...”。这会强制 Codex 使用该技能。

3. 技能的组织、管理与进阶配置

当你创建的 Skills 越来越多，就需要考虑如何组织和管理它们。

3.1 技能的保存位置与优先级

Codex 从多个位置读取技能，优先级从高到低通常是：仓库级 > 用户级 > 管理员级 > 系统内置。

最佳实践：将大多数技能放在仓库级（REPO）目录下。这能保证技能与项目上下文紧密绑定，方便版本控制（.agents/skills/目录可以提交到 Git）。只有那些真正跨项目的、个人偏好的技能，才放在用户级目录。

3.2 通过配置精细控制技能行为

你可以在~/.codex/config.toml文件中管理技能。

• 启用/停用技能：如果你暂时不想删除某个技能，但希望禁用它，可以这样配置：

  [[skills.config]] path = "/full/path/to/skill/SKILL.md" enabled = false

• 配置技能元数据：在技能目录中创建agents/openai.yaml文件，可以进行更丰富的配置：

  interface: display_name: “生成单元测试” # 在App中显示的名称 short_description: “为代码片段快速生成 pytest/Jest 单元测试” icon_small: “./assets/test-icon.svg” policy: allow_implicit_invocation: true # 默认为true，允许隐式调用。设为false则只能通过$skill-name显式调用。 dependencies: tools: - type: “mcp” value: “github” description: “访问GitHub API查询项目结构”

  这个yaml文件让你能控制技能在 GUI 中的展示，以及声明技能运行所依赖的外部工具（通过 MCP）。

3.3 技能的发现与共享

• 本地安装社区技能：你可以使用内置的$skill-installer技能来安装一些精选的社区技能。例如，在 Codex 聊天框中输入$skill-installer linear，可以安装与 Linear（项目管理工具）集成的技能。
• 从源码构建：更通用的方式是从 Git 仓库直接克隆技能目录到你的~/.agents/skills/或项目下的.agents/skills/目录。
• 打包为插件进行分发：当你和团队沉淀出一套优秀的 Skills 后，可以将其打包成 Plugin，便于在其他项目或团队中一键安装和版本化管理。

4. 构建自动化工作流：将多个 Skills 串联起来

单个 Skill 已经能提升效率，但 Codex 更大的潜力在于将多个 Skills 组合起来，形成自动化工作流。这不再是简单的“一问一答”，而是“一键触发一个多步骤的智能流程”。

4.1 工作流思维：从单点到管线

假设你有一个代码审查的需求：

1. 静态代码检查（使用skill-code-lint）
2. 生成单元测试（使用我们刚创建的skill-generate-unit-tests）
3. 运行测试并检查覆盖率（使用skill-run-tests-with-cov）
4. 生成审查报告（使用skill-generate-review-report）

在传统方式下，你需要分别触发这四个步骤，并手动传递中间结果。而在 Codex 中，你可以通过几种方式串联：

• 在同一个对话中顺序调用：你可以描述完整任务：“请对我的utils.py文件进行代码审查。” 一个设计良好的、通用的code-reviewSkill 可以在其内部逻辑中，按顺序调用或模拟调用上述子技能。
• 利用工作流（Workflows）功能：Codex 支持更正式的工作流定义，允许你以可视化或声明式的方式编排多个 Skills 和工具的执行顺序、条件分支和输入输出映射。这是实现复杂自动化的终极形态。
• 创建“元技能”（Meta-Skill）：你可以创建一个高级 Skill，它的指令就是“协调调用其他几个 Skills 来完成代码审查”。这个元 Skill 负责管理整个流程。

4.2 示例：创建一个“代码变更提交流程”技能

让我们构思一个更复杂的 Skill，它模拟一个标准的 Git 提交前检查流程：

--- name: pre-commit-helper description: Guides the user through a comprehensive pre-commit checklist for code changes. It suggests running linters, formatters, generating tests, and crafting commit messages. Trigger when user mentions “commit”, “ready to submit”, or “pre-commit”. --- # 提交助手技能 ## 目标 自动化并规范代码提交前的检查与准备流程。 ## 流程 1. **代码质量检查** * 建议用户运行 `$code-lint`（假设已存在）对变更文件进行静态分析。 * 解释发现的主要问题类型（如语法错误、风格违规、潜在 bug）。 2. **代码格式化** * 建议用户使用项目约定的格式化工具（如 `black` for Python, `prettier` for JS）。 * 提供格式化命令示例。 3. **测试保障** * 询问用户是否为新功能或改动添加了测试。 * 如果未添加，建议使用 `$generate-unit-tests` 为关键函数生成测试草稿。 * 建议运行现有测试套件：`$run-tests`。 4. **提交信息撰写** * 分析 `git diff` 的输出（或用户提供的变更摘要）。 * 根据[约定式提交](https://www.conventionalcommits.org/)规范，帮助用户草拟一个清晰的提交信息。 * 提供格式示例：`feat(api): add user authentication endpoint`。 5. **最终确认** * 汇总所有检查结果。 * 给出 `git add` 和 `git commit` 的最终命令建议。 ## 输出 一个分步骤的报告，包含建议的命令、生成的代码片段（如测试）、以及最终的提交信息模板。

这个pre-commit-helperSkill 本身不直接执行脚本（除非你在scripts/里放了自动化脚本），但它作为一个“指挥中心”，引导用户调用一系列其他 Skills 和命令，将零散的操作整合为一个连贯的、可重复的工作流。

4.3 从技能到智能体：赋予 Codex 角色和边界

当你拥有一套丰富的 Skills 后，你可以通过配置 Codex 的初始提示词（System Prompt），为其定义一个明确的“角色”。例如，你可以将它设定为“全栈开发助手”，并在提示词中说明：“你擅长使用一系列技能来协助开发工作，包括代码生成、测试、调试、容器化和基础运维。请根据用户需求，主动推荐或使用合适的技能。”

这样，Codex 就不再是一个被动的问答机器，而是一个能够主动运用“工具箱”解决问题的智能体。Skills 就是这个工具箱里一件件棱角分明的专用工具。

5. 避坑指南与最佳实践

在创建和使用 Skills 的过程中，有一些常见的“坑”需要注意。

5.1 技能设计与描述

• 描述要精准：description是隐式调用的关键。用简洁的语言写明技能的触发场景和核心价值。避免模糊词汇。好的描述：“Refactors Python functions to use async/await patterns.” 坏的描述：“Makes code better.”
• 单一职责：一个 Skill 只做好一件事。不要创建“代码处理全能王”这样的技能，而是拆分成“代码格式化”、“复杂度分析”、“依赖检查”等多个小技能。
• 指令清晰、步骤化：在SKILL.md的指令部分，使用祈使句和明确的步骤。告诉 Codex 第一步看什么，第二步做什么。提供清晰的示例输入和输出。
• 定义边界：明确说明技能“不做什么”，这能防止 Codex 在不合适的场景误用技能。

5.2 性能与上下文

• 技能别太“胖”：虽然 Codex 按需展开，但一个 Skill 的SKILL.md文件也不宜过长。如果指令非常复杂，考虑拆分成子技能，或者将部分详细说明移到references/目录下，让 Codex 在需要时去读取。
• 谨慎使用脚本：只有在需要确定性操作（如执行一条固定命令、调用特定 API）时才使用scripts/。大多数情况下，清晰的指令足以让 Codex 生成正确的代码或命令让用户执行。脚本会增加复杂性和维护成本。

5.3 测试与迭代

• 用真实场景测试：不要只测试理想情况。用边缘案例、模糊的指令去测试你的技能，看它是否健壮，description是否能准确触发或避免触发。
• 技能也需要版本管理：将.agents/skills/目录纳入 Git 管理。这样你可以追踪技能的变更，协同开发，并且方便地回滚到旧版本。
• 从纯指令开始：最佳实践是，先创建一个只有SKILL.md的“纯指令”技能。让它跑通工作流。只有当指令无法满足需求（比如需要精确调用某个本地工具）时，再考虑加入脚本。

回到最初的问题，为什么装好 Codex 却感觉“不会用”？核心在于，你还在用它处理“点状”的任务。而 Skills 机制，是你将“点”连成“线”，进而编织成“面”式自动化工作流的桥梁。它要求的不是更复杂的编程，而是一种思维转换：从向 AI 提问，转变为向 AI 定义可重复的任务规范。

今天花 20 分钟创建的第一个generate-unit-testsSkill，就是一个起点。随着你不断将日常开发中的重复性操作——代码审查、数据库迁移脚本生成、API 文档起草、部署配置检查——封装成 Skills，你会发现 Codex 逐渐从一个“聪明的实习生”，成长为一位深刻理解你工作习惯、手握标准化操作流程的“资深搭档”。真正的效率提升，始于将一次性的成功，转化为随时可调用的标准能力。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度