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 按以下优先级选择：

1. 精确匹配（完全一致的触发词）
2. 包含匹配（输入包含触发词）
3. 语义匹配（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 会使用默认行为。

参考来源与说明

本文技术内容整理自 runoob 公开教程，版权归原作者所有；具体参数与版本请以 Codex 官方文档为准。