Codex CLI Skills

Skills（技能）是 Codex CLI 的扩展机制，允许你创建自定义的工作流程和自动化任务。通过技能，你可以定义 Codex 在特定场景下的行为方式。

什么是技能？

技能是一种可配置的行为模式，它告诉 Codex 如何处理特定类型的任务。你可以创建自己的技能来：

自动化常见的开发任务
定义特定领域的处理流程
定制代码审查的标准
创建项目特定的模板和规则

技能系统让 Codex 能够适应不同项目和工作流程的需求，就像为你的团队分配了一位专职开发助手。

技能目录

Codex 会从以下位置加载技能：

位置	说明
`~/.codex/skills/`	全局技能目录，所有项目可用
`{项目目录}/.codex/skills/`	项目级技能目录
`配置指定的目录`	通过 config.toml 中的 skills.directory 指定

配置技能目录

自定义技能目录

[skills]
enabled = true
directory = "~/my-codex-skills"

技能文件结构

每个技能是一个独立的文件夹，包含以下文件：

skill-name/
├── skill.md          # 技能定义文件（必需）
└── (可选的辅助文件)

skill.md 文件格式

技能定义示例

---
name: 代码审查
description: 执行深度代码审查并提供改进建议
trigger: /review
---

# 代码审查技能

当用户请求代码审查时，执行以下步骤：

## 审查标准

1. 代码可读性
2. 性能问题
3. 安全隐患
4. 最佳实践遵循情况
5. 测试覆盖度

## 输出格式

提供以下结构化报告：
- 问题列表（按严重程度排序）
- 改进建议
- 代码评分（1-10）

技能元数据

每个技能文件的开头必须包含 YAML 格式的元数据：

字段	类型	说明	必需
`name`	string	技能名称	是
`description`	string	技能描述	是
`trigger`	string	触发关键词	否

当你的输入匹配技能的 trigger 时，Codex 会自动使用该技能来处理任务。

创建自定义技能

让我们创建一个简单的技能作为示例：

步骤 1：创建技能目录

创建技能文件夹

mkdir -p ~/.codex/skills/生成测试

步骤 2：编写技能定义

创建 skill.md

---
name: 生成测试
description: 为代码生成单元测试
trigger: 测试
---

# 生成测试技能

当用户请求生成测试时，执行以下步骤：

## 步骤

1. 分析现有代码的功能
2. 识别需要测试的边界情况
3. 选择合适的测试框架
4. 生成测试用例

## 测试标准

- 覆盖率应该包括正常情况、边界情况和错误情况
- 每个测试用例应该独立，不依赖其他测试的执行顺序
- 使用清晰的测试函数命名

## 输出格式

生成可以直接运行的测试代码，并包含必要的测试数据。

步骤 3：使用技能

现在，当你输入包含"测试"相关的内容时，Codex 会自动使用这个技能：

触发技能

# 这些输入会触发"生成测试"技能
帮我为这个函数生成测试
请测试这个模块

内置技能

Codex 自带了一些常用技能：

技能名称	触发词	说明
代码审查	review、审查	执行代码审查并提供改进建议
调试	debug、调试	帮助定位和修复问题
重构	refactor、重构	优化代码结构而不改变功能
文档	doc、文档	生成代码文档

你可以覆盖内置技能的行为，创建符合项目需求的版本。

技能优先级

当多个技能匹配时，Codex 按以下优先级选择：

精确匹配（完全一致的触发词）
包含匹配（输入包含触发词）
语义匹配（AI 判断相关性）

强制使用特定技能

你可以通过斜杠命令强制使用某个技能：

强制使用技能

# 使用技能命令
@skill-name 你的任务描述

高级技能配置

条件触发

你可以通过配置让技能在特定条件下触发：

条件触发示例

---
name: Python 技能
description: Python 项目特定处理
trigger: python
when:
file_pattern: "*.py"
directory: "src/"
---

# Python 项目技能

此技能仅在处理 Python 文件时生效。

多步骤任务

技能可以定义复杂的多步骤流程：

多步骤技能

---
name: 完整功能开发
description: 从需求到实现完整流程
trigger: 开发功能
---

# 完整功能开发流程

## 阶段 1：需求分析
- 理解功能需求
- 识别边界情况
- 设计数据结构

## 阶段 2：设计
- 设计函数/类结构
- 定义接口
- 选择算法

## 阶段 3：实现
- 编写代码
- 添加注释
- 编写文档

## 阶段 4：测试
- 编写单元测试
- 验证边界情况
- 检查覆盖率

## 阶段 5：提交
- 创建 Git commit
- 编写提交信息

技能最佳实践

命名规范

使用清晰、描述性的名称
名称应该表达技能的功能
避免使用中文名称（可能导致编码问题）

触发词选择

选择常用的关键词
避免过于宽泛的触发词
考虑用户的自然表达方式

技能粒度

保持技能职责单一
一个技能解决一类问题
复杂流程可以通过技能组合实现

好的技能应该让用户感觉"Codex 懂我的需求"，而不是需要学习特殊语法。

管理技能

列出可用技能

查看技能列表

# 在 Codex 中输入
/skills

禁用技能

如果你不想使用某个技能，可以删除对应的文件或移动到其他目录。

更新技能

修改技能文件后，需要重启 Codex 才能生效。

技能示例库

OpenAI 官方提供了一些预制技能供你参考和使用：

访问 GitHub 仓库查看更多示例：https://github.com/openai/codex/tree/main/skills

常见问题

Q: 技能不触发？

检查技能文件的元数据格式是否正确，确保 YAML 头部格式正确且文件以 .md 结尾。

Q: 如何调试技能？

可以在 Codex 中使用 /debug 命令查看技能匹配的详细信息。

Q: 技能会影响 Codex 的正常行为吗？

技能只是提供指导方针，Codex 仍然会进行独立判断。如果技能配置不当，Codex 会使用默认行为。

菜鸟教程 -- 学的不仅是技术，更是梦想！

Codex Cli