OpenAI Codex 的 Skills 系统：让 AI 掌握你的工作流程

OpenAI Codex 支持通过 Skills 扩展能力。Skills 让 Codex 能够可靠地执行特定任务的工作流程。

一个 Skill 本质上是一个文件夹，包含指令、资源和可选的脚本。Codex CLI 和 IDE 扩展都支持 Skills。

Skill 的文件结构

一个 Skill 包含以下部分：

必需文件：

• SKILL.md - 包含指令和元数据

可选目录：

• scripts/ - 可执行代码
• references/ - 文档资料
• assets/ - 模板和资源文件

这个结构很简单。核心是 SKILL.md 文件，其他部分按需添加。

渐进式披露机制

Codex 使用"渐进式披露"策略管理上下文。

启动时，Codex 加载所有可用 Skills 的名称和描述。当某个 Skill 被激活时，Codex 才访问完整的指令和参考文档。

这避免了一次性加载所有 Skills 的完整内容，节省了上下文窗口。

两种调用方式

Skills 可以通过两种方式激活：

显式调用：用户主动选择 Skill

• 使用 /skills 斜杠命令
• 输入 $ 后提及特定 Skill 名称

隐式调用：Codex 自动判断

• 当用户任务与某个 Skill 的描述匹配时
• Codex 自动激活相应的 Skill

隐式调用是关键特性。用户不需要记住有哪些 Skills，Codex 会根据任务自动选择合适的 Skill。

分层加载位置

Skills 可以放在多个位置，Codex 按优先级从高到低加载：

作用域	位置	用途
REPO（文件夹级别）	$CWD/.codex/skills	微服务或模块特定的 Skills
REPO（父目录）	$CWD/../.codex/skills	嵌套仓库的共享 Skills
REPO（根目录）	$REPO_ROOT/.codex/skills	组织级别的仓库 Skills
USER	~/.codex/skills	个人跨项目 Skills
ADMIN	/etc/codex/skills	系统级别共享 Skills
SYSTEM	内置	默认的系统 Skills

当同名 Skill 出现在多个位置时，优先级高的会覆盖优先级低的。

这个设计解决了不同范围的需求。微服务特定的配置放在工作目录，团队规范放在仓库根目录，个人偏好放在用户主目录。

创建 Skill 的方法

快速开始

使用内置的 $skill-creator Skill 来创建新 Skill。如果需要策略规划，可以结合 $create-plan 使用。

手动创建

创建一个文件夹，在其中创建 SKILL.md 文件：

---
name: skill-name
description: 帮助 Codex 选择此 Skill 的描述
metadata:
  short-description: 面向用户的描述
---

这里写 Codex 执行任务时的指令

YAML 前置数据需要包含 name 和 description 字段。description 是 Codex 判断是否激活这个 Skill 的关键依据。

安装现成的 Skill

可以用 $skill-installer Skill 从 GitHub 下载已有的 Skills：

$skill-installer linear
$skill-installer notion-spec-to-implementation

这些是社区提供的 Skills，可以直接使用。

值得关注的 Skill 示例

OpenAI 文档中提到了几个实用的 Skills：

$create-plan（实验性）- 研究和规划功能开发

$linear - 将 Linear 上下文集成到 Codex 任务中

$notion-spec-to-implementation - 访问 Notion 获取额外上下文

$skill-creator - 创建新的自定义 Skill

$skill-installer - 安装社区 Skills

这些 Skills 展示了不同的使用场景：规划、集成外部工具、创建和安装。

Skills 遵循开放标准

Codex 的 Skills 基于 Agent Skills 规范构建。这个规范托管在 agentskills.io。

Agent Skills 最初由 Anthropic 在 2025 年 10 月推出。Anthropic 将其作为开放标准发布，接受社区贡献。同年 12 月，Anthropic 正式发布跨平台可移植的开放规范。

采用开放标准意味着 Skills 不是某一家公司独有的。目前支持 Agent Skills 的工具包括 Claude Code、Cursor、GitHub、VS Code、Letta 等。你为 Codex 写的 Skill，也能在这些工具上使用。

实际应用场景

Skills 解决的是重复性工作流程的问题。

如果你的团队有固定的代码审查流程，可以写成 Skill。如果你经常需要按特定格式生成报告，可以写成 Skill。如果你的项目有特定的测试规范，也可以写成 Skill。

一旦写成 Skill，团队所有人都能用上。新成员不需要花时间学习这些流程，Codex 会按 Skill 定义的步骤执行。

个人开发者也能受益。把自己的工作习惯写成 Skills，这些习惯就能跨项目复用。换项目时，Skills 跟着你走。

优先级覆盖的灵活性

分层加载机制带来了灵活性。

全局有一个代码审查 Skill，但某个项目需要更严格的检查？在项目的 .codex/skills/ 下创建同名 Skill，添加项目特定的要求。

个人有偏好的工作方式，但某个项目有团队规范？团队规范放在仓库，个人偏好放在用户目录。Codex 会优先使用团队规范。

这个设计在标准化和个性化之间找到了平衡。

从简单开始

Skills 的门槛不高。最简单的 Skill 只需要一个 SKILL.md 文件。

先从小的、明确的任务开始。比如"生成 Git 提交信息"、"创建 PR 描述"、"格式化测试报告"。这些都是重复性任务，适合用 Skill 标准化。

用 $skill-creator 可以更快上手。它会引导你填写必要的信息，生成符合格式的文件。

随着使用，你会发现更多可以用 Skill 优化的流程。Skills 可以逐步积累，形成你或你团队的工作方式库。

Skills 的本质

Skills 是一种知识传递机制。

团队的工作方式、最佳实践、注意事项，通常散落在文档里或只存在于某些人的脑子里。Skills 把这些隐性知识显性化、结构化。

更重要的是，Skills 让这些知识可以被 AI 直接使用。不需要每次都向 AI 解释流程，Skill 已经包含了所有必要的指令。

随着 Skills 的积累，Codex 会越来越"懂"你的工作方式。这就是 Skills 系统的价值。

---

往期回顾

• Claude Skills 与 MCP：AI 能力扩展的两种哲学
• uv 上手指南：高效全能的 Python 包管理新选择
• 地图上的问题都问它！智能出行规划专家Claude + 谷歌地图MCP