OpenAI Codex Skills 深度技术解读

一、项目概述

1.1 什么是 Codex？

Codex 是 OpenAI 于 2025 年推出的云端软件工程 Agent，它可以：

在云端沙箱环境中并行处理多个任务
自主编写代码、修复 Bug、执行测试
与 GitHub 集成，直接创建 PR
在隔离环境中安全执行代码

Codex 的定位是软件工程 Agent，而非简单的代码补全工具。

1.2 什么是 Agent Skills？

Agent Skills 是由 Anthropic 开发并开源的一种轻量级、开放格式标准（agentskills.io），用于扩展 AI Agent 的能力和专业知识。

核心理念：Write once, use everywhere（一次编写，处处可用）。

Skills 本质上是一组包含指令、脚本和资源的文件夹，AI Agent 可以自动发现并使用这些 Skills 来执行特定任务。

1.3 OpenAI Codex 对 Agent Skills 的实现

OpenAI 的 Codex 采用了 Anthropic 的 Agent Skills 开放标准，并在此基础上构建了自己的 Skills 生态系统（GitHub: openai/skills）。

层级	说明
开放标准	Agent Skills（Anthropic 制定，agentskills.io）
实现方案	OpenAI Codex Skills（基于标准的具体实现）
Skills 仓库	github.com/openai/skills

这种设计将通用 AI Agent 转变为领域专家，使其具备模型本身无法完全掌握的程序性知识（Procedural Knowledge）。

1.4 为什么需要 Skills？

问题	Skills 的解决方案
LLM 知识截止日期	通过外部文档提供最新 API、工具使用方法
缺乏公司内部知识	打包公司特定的 schema、流程、规范
重复编写相同代码	提供可复用脚本，直接执行
上下文窗口有限	渐进式加载，按需读取
操作一致性要求	提供确定性脚本，避免每次重新生成

1.5 核心价值

维度	价值
可复用性	团队和个人可以打包特定任务的能力，重复使用
模块化	每个 Skill 独立自包含，易于维护和分发
渐进式加载	三级加载机制，高效管理上下文窗口
开放标准	遵循 agentskills.io 开放标准
社区驱动	开源仓库，接受社区贡献

二、技术架构深度解析

2.1 Skill 目录结构


skill-name/├── SKILL.md              # 必需：核心指令文件│   ├── YAML frontmatter  # 元数据（name + description）│   └── Markdown body     # 详细指令├── agents/               # 推荐：UI 元数据│   └── openai.yaml       # 界面展示配置└── Bundled Resources/    # 可选：捆绑资源    ├── scripts/          # 可执行脚本（Python/Bash）    ├── references/       # 参考文档    └── assets/           # 输出资源（模板、图标等）

2.2 SKILL.md 核心文件解析

SKILL.md 是每个 Skill 的核心，由两部分组成：

Frontmatter（YAML 元数据）


---name: skill-namedescription: 完整描述 Skill 功能和触发场景---

关键设计决策：

description 是 主要触发机制，决定 Agent 何时使用该 Skill
必须包含 "when to use" 信息，因为 body 只在触发后加载
不包含其他字段，保持简洁

Body（Markdown 指令）

Body 部分包含详细的使用指令，只有在 Skill 被触发后才会加载到上下文中。

2.3 渐进式披露（Progressive Disclosure）设计

这是 Agent Skills 最精妙的技术设计之一：


┌─────────────────────────────────────────────────────────────┐│ Level 1: Metadata (name + description)                      ││ ├── 始终在上下文中                                           ││ └── 约 100 词                                                │├─────────────────────────────────────────────────────────────┤│ Level 2: SKILL.md Body                                      ││ ├── 仅在 Skill 触发时加载                                    ││ └── < 5000 词                                                │├─────────────────────────────────────────────────────────────┤│ Level 3: Bundled Resources                                  ││ ├── 按需加载                                                 ││ └── 无限制（脚本可直接执行，无需加载到上下文）                  │└─────────────────────────────────────────────────────────────┘

设计哲学：上下文窗口是公共资源，必须高效利用。

三、资源类型详解

3.1 Scripts（脚本）

用途：需要确定性可靠性或重复编写的可执行代码

示例：


# scripts/rotate_pdf.py# PDF 旋转脚本，避免每次重写相同代码

优势：

Token 高效（可直接执行，无需加载到上下文）
确定性输出
可被 Agent 读取以进行环境适配

3.2 References（参考文档）

用途：供 Agent 在工作时参考的文档资料

最佳实践：

文件超过 100 行时，顶部添加目录
文件超过 10k 词时，在 SKILL.md 中提供 grep 搜索模式
避免与 SKILL.md 内容重复

组织模式：


# 按领域组织（BigQuery 示例）bigquery-skill/├── SKILL.md└── references/    ├── finance.md    # 收入、计费指标    ├── sales.md      # 机会、管道    └── product.md    # API 使用、功能

3.3 Assets（资产）

用途：不加载到上下文，而是用于输出的文件

示例：

品牌 Logo（assets/logo.png）
PPT 模板（assets/slides.pptx）
前端模板（assets/hello-world/）

四、系统级 Skills 解析

4.1 skill-creator：Skill 创建器

这是一个元 Skill，用于创建新的 Skills。

核心脚本：

脚本	功能
`init_skill.py`	初始化新 Skill 目录结构
`generate_openai_yaml.py`	生成 UI 元数据配置
`quick_validate.py`	验证 Skill 结构正确性

创建流程：


# 1. 初始化 Skillscripts/init_skill.py my-skill --path skills/public --resources scripts,references
# 2. 编辑 SKILL.md 和资源文件
# 3. 验证 Skillscripts/quick_validate.py <path/to/skill-folder>

自由度设计原则：

自由度	适用场景	示例
高	多种方法有效，依赖上下文	文本指令
中	存在首选模式，允许变化	伪代码/参数化脚本
低	操作脆弱易错，一致性关键	具体脚本，少量参数

4.2 skill-installer：Skill 安装器

功能：从 GitHub 仓库安装 Skills

核心命令：


# 列出可用 Skillsscripts/list-skills.py
# 安装 curated Skillscripts/install-skill-from-github.py --repo openai/skills --path skills/.curated/<skill-name>
# 安装 experimental Skillscripts/install-skill-from-github.py --url https://github.com/openai/skills/tree/main/skills/.experimental/<skill-name>

安装位置：$CODEX_HOME/skills/<skill-name>（默认 ~/.codex/skills）

五、Curated Skills 技术分析

5.1 playwright：浏览器自动化

触发场景：终端浏览器自动化（导航、表单填充、截图、数据提取）

核心工作流：


# 1. 设置路径export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
# 2. 核心循环"$PWCLI" open https://example.com"$PWCLI" snapshot          # 获取稳定元素引用"$PWCLI" click e3           # 使用引用交互"$PWCLI" snapshot          # 导航后重新快照

关键设计：

使用 npx 包装器，无需全局安装
元素引用（如 e15）基于快照，导航后需重新获取
CLI 优先，非测试文件导向

5.2 gh-fix-ci：GitHub CI 修复

触发场景：调试或修复 GitHub PR 检查失败

工作流：


1. 验证 gh 认证2. 解析 PR（当前分支或指定）3. 检查失败的 GitHub Actions4. 获取日志并总结失败原因5. 创建修复计划6. 用户批准后实施7. 重新检查状态

核心脚本：


python scripts/inspect_pr_checks.py --repo "." --pr "123" --json

5.3 figma：设计到代码

触发场景：Figma URL、节点 ID、设计转代码

必需流程：


1. get_design_context  → 获取节点结构化表示2. get_metadata        → 响应过大时获取高层节点映射3. get_screenshot      → 获取视觉参考4. 下载资产并开始实现5. 转换为项目约定（React + Tailwind → 项目风格）6. 与 Figma 验证 1:1 视觉一致性

资产处理规则：

直接使用 Figma MCP Server 返回的 localhost 图片源
禁止导入新图标包，所有资产来自 Figma payload

5.4 vercel-deploy：Vercel 部署

触发场景："deploy my app"、"push this live"

核心逻辑：


# 检查 CLIcommand -v vercel
# 部署（默认 preview，非 production）vercel deploy [path] -y  # 10 分钟超时
# 回退方案（无认证时）bash "$skill_dir/scripts/deploy.sh" /path/to/project

5.5 sentry：错误监控

触发场景：检查 Sentry issues、总结生产错误

API 端点：

端点	用途
`/api/0/projects/{org}/{project}/issues/`	列出 issues
`/api/0/issues/{issue_id}/`	Issue 详情
`/api/0/issues/{issue_id}/events/`	Issue 事件
`/api/0/projects/{org}/{project}/events/{event_id}/`	事件详情

安全规则：

只读操作
脱敏 PII（邮箱、IP）
不打印原始堆栈跟踪
不回显认证令牌

六、openai.yaml 配置详解

agents/openai.yaml 是面向机器/界面的配置文件：


interface:  display_name: "用户可见名称"  short_description: "简短描述（25-64字符）"  icon_small: "./assets/small-400px.png"  icon_large: "./assets/large-logo.svg"  brand_color: "#3B82F6"  default_prompt: "Use $skill-name to..."
dependencies:  tools:    - type: "mcp"      value: "github"      description: "GitHub MCP server"      transport: "streamable_http"      url: "https://api.githubcopilot.com/mcp/"

关键约束：

default_prompt 必须显式提及 $skill-name
字符串值必须加引号
键名不加引号

七、设计哲学与最佳实践

7.1 简洁至上

"上下文窗口是公共资源。"

默认假设：Agent 已经很聪明
每条信息都要质疑："Agent 真的需要这个解释吗？"
偏好简洁示例而非冗长解释

7.2 避免冗余文件

禁止创建：

README.md
INSTALLATION_GUIDE.md
QUICK_REFERENCE.md
CHANGELOG.md

Skill 只包含 AI Agent 完成任务所需的信息，不包含创建过程、设置测试、用户文档等辅助内容。

7.3 迭代优化


使用 Skill → 发现问题 → 识别改进点 → 实施更新 → 再次测试

八、Skill 分类体系

类别	位置	说明
System	`.system/`	预装，核心功能（skill-creator, skill-installer）
Curated	`.curated/`	官方精选，经过验证
Experimental	`.experimental/`	实验性，可能不稳定

九、技术创新点总结

渐进式披露架构：三级加载机制，最大化上下文效率
触发机制设计：description 作为主要触发器，精准匹配用户意图
资源分离策略：scripts/references/assets 各司其职
自由度控制：根据任务脆弱性调整指令精确度
元 Skill 设计：skill-creator 用于创建 Skills，形成自举能力
开放标准：可跨平台、跨 Agent 使用

十、Codex 与 Skills 的协作机制

10.1 Skills 可用平台

Skills 在以下 Codex 产品中可用：

Codex CLI – 命令行界面
IDE Extension – VS Code 等 IDE 扩展
Codex App – Web 应用

10.2 Skill 触发方式

Codex 支持两种 Skill 激活方式：

方式	说明	示例
显式调用	在 prompt 中直接引用 Skill	CLI/IDE 中输入 `/skills` 或 `$skill-name`
隐式调用	Codex 根据任务自动匹配 Skill	任务描述匹配 Skill 的 `description`

重要：隐式匹配依赖 description 字段，因此必须清晰描述 Skill 的适用范围和边界。

10.3 渐进式加载流程


用户请求 → Codex 读取所有 Skill 的元数据（name, description, 路径, openai.yaml）         → 匹配相关 Skill         → 加载完整 SKILL.md 指令         → 按需读取 references/         → 执行 scripts/ 或生成代码         → 返回结果

10.4 Skill 存储位置

Codex 从多个位置读取 Skills，按优先级扫描：

位置类型	路径	说明
REPO	`$CWD/.agents/skills`	当前目录
REPO	`$CWD/../.agents/skills`	上级目录（递归到仓库根）
REPO	`$REPO_ROOT/.agents/skills`	仓库根目录
USER	`$HOME/.agents/skills`	用户级 Skills
ADMIN	`/etc/codex/skills`	管理员级 Skills
SYSTEM	内置	系统预装 Skills

注意：如果两个 Skill 同名，Codex 不会合并它们，两者都会出现在选择器中。支持符号链接。

10.5 Codex 沙箱环境

Codex 在云端沙箱中运行，Skills 需要考虑：

约束	应对策略
网络受限	脚本标注 `sandbox_permissions=require_escalated`
无持久状态	使用 `$CODEX_HOME` 存储 Skill 数据
隔离环境	提供依赖安装指令

10.6 安装与管理 Skills

安装 Skills：


# 使用内置安装器$skill-installer install the linear skill from the .experimental folder
# 从其他仓库安装$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/playwright

启用/禁用 Skills：

在 ~/.codex/config.toml 中配置：


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

修改配置后需重启 Codex。

十一、如何创建自己的 Skill

11.1 使用内置创建器（推荐）

最简单的方式是使用内置的 $skill-creator：


$skill-creator

创建器会询问：

Skill 的功能是什么
何时应该触发
是否需要脚本（默认仅指令）

11.2 手动创建

创建一个包含 SKILL.md 文件的文件夹：


mkdir -p .agents/skills/my-skill

SKILL.md 模板：


---name: skill-namedescription: 清晰说明该 Skill 何时应该触发，何时不应该触发。---
Codex 需要遵循的具体指令。

Codex 会自动检测 Skill 变更。如果更新未生效，重启 Codex。

11.3 使用脚本初始化


# 使用 init_skill.py 脚本python scripts/init_skill.py my-skill --path .agents/skills --resources scripts,references
# 验证 Skill 结构python scripts/quick_validate.py .agents/skills/my-skill/

11.4 配置 openai.yaml（可选）

添加 agents/openai.yaml 配置 UI 元数据和调用策略：


interface:  display_name: "用户可见名称"  short_description: "简短描述"  icon_small: "./assets/small-logo.svg"  icon_large: "./assets/large-logo.png"  brand_color: "#3B82F6"  default_prompt: "Use $my-skill to..."
policy:  allow_implicit_invocation: false  # 禁用隐式调用
dependencies:  tools:    - type: "mcp"      value: "github"      description: "GitHub MCP server"      transport: "streamable_http"      url: "https://api.githubcopilot.com/mcp/"

关键配置项：

字段	说明
`allow_implicit_invocation`	默认 `true`；设为 `false` 时，Codex 不会隐式调用该 Skill，但显式 `$skill` 调用仍有效
`dependencies.tools`	声明 Skill 依赖的 MCP 服务器等工具

11.5 最佳实践（官方推荐）

保持专注 – 每个 Skill 只做一件事
指令优先 – 除非需要确定性行为或外部工具，否则优先使用指令而非脚本
祈使句式 – 使用明确的输入和输出编写步骤
测试触发 – 用不同 prompt 测试 Skill 的 description，确认触发行为正确
清晰边界 – 在 description 中明确说明何时应该/不应该使用该 Skill

十二、结语

OpenAI Codex Skills 代表了 AI Agent 能力扩展的一种优雅范式。通过模块化、渐进式加载和开放标准，它解决了 AI Agent 在特定领域任务中的知识局限性问题。

这套架构的核心洞察是：将程序性知识外部化，让 Codex 能够像人类专家一样，在需要时查阅"操作手册"，而不是试图将所有知识都塞进模型参数中。

关键要点回顾

概念	说明
Agent Skills	Anthropic 开源的轻量级开放标准
Codex	OpenAI 云端软件工程 Agent
Codex Skills	OpenAI 基于 Agent Skills 标准的实现
SKILL.md	Skill 的核心文件，包含元数据和指令
渐进式披露	三级加载机制，优化上下文使用
触发机制	基于 description 匹配用户意图

资源	链接
Agent Skills 开放标准	agentskills.io
Anthropic Skills 示例	github.com/anthropics/skills
OpenAI Codex Skills	github.com/openai/skills
Codex 官方文档	developers.openai.com/codex/skills

{{userData.name}}已认证