Codex CLI Skills 技能功能

警告

这是一个实验性且不稳定的功能。如果你依赖此功能，请预期在未来几周内可能会有破坏性更改，并且目前无法保证此功能能够正常工作。使用风险自负！

Codex 可以自动发现你保存在磁盘上的可复用"技能"。技能是一个小型包，包含名称、简短描述（说明它的功能和使用场景），以及一个可选的指令正文，你可以在需要时打开它。Codex 仅将名称、描述和文件路径注入到运行时上下文中；正文内容保留在磁盘上。

启用技能

技能功能位于 skills 实验性功能标志后面，默认禁用。

在配置中启用（推荐）

在 $CODEX_HOME/config.toml（通常是 ~/.codex/config.toml）中添加以下内容并重启 Codex：

[features]
skills = true

单次运行启用

使用以下命令启动 Codex：

codex --enable skills

技能存储位置

• 位置（v1）: ~/.codex/skills/**/SKILL.md（递归搜索）
• 隐藏条目和符号链接会被跳过
• 只有名为 SKILL.md 的文件才会被识别
• 排序: 按名称排序，然后按路径排序以保持稳定性

文件格式

技能文件采用 YAML frontmatter + 正文的格式。

必需字段

字段	要求
name	非空，≤100 字符，会被清理为单行
description	非空，≤500 字符，会被清理为单行

额外的键会被忽略。正文可以包含任何 Markdown 内容；正文不会被注入到上下文中。

加载与渲染

• 在启动时加载一次
• 如果存在有效的技能，Codex 会在 AGENTS.md 之后追加一个仅运行时的 ## Skills 部分，每个技能一个列表项：

  - <name>: <description> (file: /absolute/path/to/SKILL.md)

• 如果没有有效的技能，该部分会被省略
• 磁盘上的文件永远不会被修改

使用技能

• 在消息中使用 $<skill-name> 来提及技能
• 在 TUI 中，你也可以使用 /skills 命令来浏览和插入技能

验证与错误

无效的技能（缺少/无效的 YAML、空字段或超长字段）会在 TUI 中触发一个阻塞式、可关闭的启动模态框，列出每个路径和错误。错误也会被记录到日志中。

你可以关闭模态框继续使用（无效的技能会被忽略），或者退出程序。修复 SKILL.md 文件并重启即可清除模态框。

创建技能

步骤 1：创建技能目录

mkdir -p ~/.codex/skills/<skill-name>/

步骤 2：添加 SKILL.md 文件

---
name: your-skill-name
description: what it does and when to use it (<=500 chars)
---

# Optional body
Add instructions, references, examples, or scripts (kept on disk).

注意事项

• 保持 name 和 description 在限制范围内
• 避免在这些字段中使用换行符
• 重启 Codex 以加载新技能

示例

创建一个 PDF 处理技能：

mkdir -p ~/.codex/skills/pdf-processing
cat <<'SKILL_EXAMPLE' > ~/.codex/skills/pdf-processing/SKILL.md
---
name: pdf-processing
description: Extract text and tables from PDFs; use when PDFs, forms, or document extraction are mentioned.
---

# PDF Processing
- Use pdfplumber to extract text.
- For form filling, see FORMS.md.
SKILL_EXAMPLE