企业官网建设流程全解析

🚀 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，理解这一点对技能设计至关重要：

1. 启动扫描：Codex 启动时，会从多个预设路径（后文详述）扫描所有可用的 Skills。
2. 加载摘要：此时，它只读取每个 Skill 目录下SKILL.md文件中的name（名称）和description（描述）这两个元数据字段。这个过程非常轻量。
3. 构建技能列表：Codex 会将这个精简的技能列表（仅含名称和描述）放入其初始上下文窗口，供其判断当前任务适合调用哪个技能。为了避免挤占用于任务理解的上下文空间，这个列表的大小被限制在模型上下文窗口的2%（或最多 8000 个字符）。如果技能太多，Codex 会自动缩短描述文本。
4. 按需加载：当用户显式调用（如输入$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。这是最快捷的入门方式。

1. 在终端中，进入你希望创建技能的目录（例如你的项目根目录）。

2. 启动 Codex CLI 交互模式，或直接在对话中键入命令：

   # 启动 Codex CLI 后，在对话中输入： $skill-creator

3. 创建器会引导你完成以下步骤：

   • 技能名称：输入git-commit-helper。
   • 技能描述：输入根据代码变更自动生成符合 Conventional Commits 规范的 Git 提交消息。适用于 feat, fix, docs, style, refactor, test, chore 等类型。
   • 技能类型：选择纯指令。对于这个任务，我们只需要用自然语言指令 Codex 分析git diff并生成消息，不需要外部脚本。

4. 创建器会自动在合适的目录（通常是当前目录下的.agents/skills/）生成技能文件夹和SKILL.md的草稿。

3.2 方法二：手动创建与编辑

如果你想更精细地控制技能内容，可以手动创建。

1. 创建技能目录结构：

   # 在你的项目根目录或用户技能目录下 mkdir -p .agents/skills/git-commit-helper cd .agents/skills/git-commit-helper

2. 创建并编辑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，让它重新扫描技能目录。

1. 重启 Codex：如果你在运行 Codex 会话中创建了技能，退出并重新启动它。

2. 触发技能：在新的 Codex 会话中，你可以尝试：

   • 显式调用：直接输入$git-commit-helper。
   • 隐式调用：输入“帮我写一个 git 提交信息，我刚刚修复了一个 bug”。Codex 会根据你的description自动匹配到git-commit-helper技能。

   如果技能被成功调用，Codex 的回复风格和内容应该遵循SKILL.md中的指令，它会引导你提供git diff信息，然后生成格式化的提交消息。

4. 技能的组织、管理与高级配置

掌握了单个技能的创建后，我们需要了解如何管理多个技能，以及如何进行更精细的控制。

4.1 技能的保存位置与作用域

Codex 从四个层次的位置扫描技能，优先级从高到低（同名称技能不会合并，会同时存在）：

最佳实践：将项目相关的技能放在REPO作用域，将个人通用技能放在USER作用域。你可以使用符号链接（ln -s）来灵活组织这些目录。

4.2 启用、停用与配置技能

你不需要通过删除文件来禁用一个技能。Codex 的全局配置文件~/.codex/config.toml允许你精细控制。

1. 找到或创建配置文件：通常位于用户主目录下的.codex文件夹中。
2. 编辑配置以停用技能：

   # ~/.codex/config.toml [[skills.config]] path = "/full/path/to/your/skill/SKILL.md" # 技能的完整路径 enabled = false # 将此技能禁用

   修改配置后，需要重启 Codex 生效。
3. 配置技能参数：一些高级技能可能支持通过配置传递参数，具体需参考该技能的文档。

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. 插件：何时转换？

• 坚持使用技能：当你的工作流仅在当前项目或个人本地环境中使用时。
• 升级为插件：当你想实现以下目标时：
  1. 分发：让其他人能通过简单的命令（如codex plugins install）安装你的技能。
  2. 组合：将多个相关的技能、工具配置（MCP Servers）、应用映射打包成一个功能集。
  3. 集成交付：将技能作为某个软件或服务的一部分，一起交付给用户。

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 技能设计原则

1. 单一职责：一个技能只做好一件事。不要创建“代码生成与数据库迁移与部署”这样的超级技能。将其拆分为$generate-api，$create-migration，$deploy-staging等多个技能。
2. 指令优先于脚本：除非必要，否则尽量用清晰的指令指导 Codex 完成工作，而不是编写脚本。指令更灵活，能利用 LLM 的推理能力；脚本适用于确定性高、需调用外部 API 或复杂计算的场景。
3. 清晰的输入与输出：在SKILL.md中明确说明技能期望的输入（例如，“请提供错误日志片段”）和将产生的输出（例如，“我将输出一个包含根本原因和修复步骤的表格”）。
4. 描述（Description）是门艺术：description字段是技能的“搜索引擎优化”。把最核心的触发关键词放在前面。例如：
   • 好：为 Python 函数生成 Google 风格文档字符串。输入函数签名和简要说明。
   • 不够好：这个技能可以帮助你生成文档，它使用 Google 的格式规范，适用于 Python...
5. 用真实场景测试：创建技能后，用各种相关的、不相关的提示词去测试它，确保它在该触发时触发，不该触发时保持沉默。

6.2 一个带脚本的进阶技能示例：代码风格检查

纯指令技能适用于逻辑判断和文本生成。当需要与系统交互时，就需要结合脚本。下面是一个code-lint技能的示例，它调用一个 Python 脚本进行代码检查。

目录结构：

code-lint/ ├── SKILL.md └── scripts/ └── run_linter.py

SKILL.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", "--format=json", path] try: result = subprocess.run(cmd, capture_output=True, text=True, timeout=30) 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_output=True, text=True) 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": f"black {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, indent=2))

这个例子展示了如何将确定性的、需要特定工具（flake8, black）和复杂参数处理的任务封装在脚本中，而让 Codex 负责与用户交互、解释结果和提供建议。这是一种强大的混合模式。

7. 常见问题与排查指南

在创建和使用 Skills 过程中，你可能会遇到以下问题：

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 持续优化你的技能

1. 迭代：技能不是一次写成的。根据使用反馈，不断调整description和指令。
2. 版本化：将技能目录纳入 Git 管理，记录其演变。
3. 文档化：在SKILL.md或references/中添加详细的使用示例和边界条件说明。
4. 测试集：为关键技能维护一组测试用例（输入和期望输出），确保其行为稳定。

8.3 下一步探索方向

掌握了基础技能创建后，你可以进一步探索：

• 插件开发：学习如何将技能打包成插件，进行版本管理和分发。
• MCP 服务器集成：让技能能够连接外部工具和数据源（如数据库、JIRA、Slack），实现更强大的自动化。
• 复杂工作流编排：结合 Codex 的“子智能体”和“工作流”功能，用多个技能协作完成复杂项目。
• 探索社区技能库：关注 OpenAI 官方或社区分享的技能集，学习他人的设计模式。

Codex Skills 是将 AI 助手从“通用聊天伙伴”转变为“专业工作伙伴”的关键。通过将你日常重复的、需要固定流程的任务封装成技能，你不仅为自己和团队构建了一个不断成长的自动化资产库，更是真正意义上在塑造一个专属的、高效的 AI 协作环境。现在，就从创建一个解决你当下最繁琐任务的技能开始吧。

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