Codex 斜杠命令与技能系统实战指南：让 AI 编程助手更懂你的工作流

Codex CLI 不仅是一个可以跟对话的终端 AI 编程助手，它还提供了两套强大的自定义机制——斜杠命令（Slash Commands） 和 技能系统（Skills）。这两套系统让你能够为 Codex "定制肌肉记忆"：斜杠命令让高频操作一键触发，技能则让 Codex 在特定领域变成专家。本文将深入讲解两者的配置和使用方式，并给出实际可运行的示例。

Slash Commands 概述

在 Codex 的交互式 TUI 界面中，你可以通过输入 / 触发斜杠命令面板。这些命令分为两大类：

内置命令：Codex 自带的标准命令，如 /clear 清空对话、/exit 退出、/help 帮助等

自定义命令：你在配置文件中定义的个性化命令，可以执行任意 shell 脚本或发送预置 Prompt

内置命令速查

以下是 Codex 常用的内置斜杠命令：

| 命令 | 功能 |
|------|------|
| /clear | 清空当前对话上下文，重新开始 |
| /help | 显示帮助信息与可用命令列表 |
| /exit 或 /quit | 退出 Codex TUI |
| /model | 查看或切换当前使用的模型 |
| /undo | 撤销上一次 Codex 对文件的修改 |
| /diff | 查看当前对话中的代码变更差异 |
| /memory | 打开或编辑 Codex 的记忆文件 |

这些命令的背后其实是 Codex 对不同类型用户操作的抽象。你不需要记住模型特定的 Prompt 或执行冗长的操作步骤——一个斜杠命令就够了。

自定义斜杠命令

除了内置命令，你可以在 Codex 配置文件中定义自己的斜杠命令，把它绑定到一段自定义 Prompt 或 Shell 脚本上。

配置方式

自定义命令定义在 config.toml（或项目级的 .codex/config.toml）中。来看一个最小示例：

[[slash_commands]]
command = "/review"
description = "让 Codex 审查当前分支的代码变更"
prompt = """
请审查当前分支所有的代码变更（git diff main...HEAD），重点关注：
1. 潜在的 bug 和逻辑错误
2. 安全隐患（SQL 注入、XSS 等）
3. 性能问题
4. 代码风格和可维护性

输出格式：按严重程度从高到低列出所有问题，并给出修复建议。
"""

[[slash_commands]]
command = "/changelog"
description = "根据最近的 commit 生成 CHANGELOG"
prompt = """
请根据 `git log --oneline main..HEAD` 的输出，生成一份 CHANGELOG.md 格式的发布说明。
按以下类别分组：新功能、Bug 修复、性能优化、重构、文档。
每一条用中文描述变更内容。
"""

在 TUI 中输入 /review，Codex 就会自动把上面定义的 Prompt 提交给模型，让它执行代码审查。

Shell 命令类斜杠命令

有些时候，你希望斜杠命令直接执行一段 Shell 脚本而非发送 Prompt。Codex 同样支持：

[[slash_commands]]
command = "/format"
description = "格式化当前项目的所有 Go 文件"
script = "gofmt -w ./... && echo 'All Go files formatted.'"

[[slash_commands]]
command = "/reset-db"
description = "重置本地开发数据库并重新导入种子数据"
script = """
mysql -u root -e 'DROP DATABASE IF EXISTS myapp_dev; CREATE DATABASE myapp_dev;'
php artisan migrate:fresh --seed
echo 'Database reset complete.'
"""

script 字段中的内容会在用户的 Shell 中直接执行。注意：命令在 Codex 的默认执行策略下可能需要确认授权。

斜杠命令的层级

Codex 支持多级配置文件，斜杠命令也可以在不同层级定义：

• 用户级（~/.codex/config.toml）：全局生效，适用于所有项目
• 项目级（.codex/config.toml）：仅对当前项目生效
• 会话级：在 TUI 中临时执行的命令

项目级配置会与用户级合并，如果同一个命令在两层都定义了，项目级覆盖用户级。

技能系统（Skills）

如果说斜杠命令是"快捷指令"，那技能系统就是"专业化培训"。Skill 是一段结构化的指令文件，它告诉 Codex 在面对特定任务时应该遵循什么工作流、调用哪些工具、注意哪些规范。

Skill 文件结构

一个 Skill 本质上是一个 Markdown 文件，存放在项目的 .codex/skills/ 目录下。文件结构如下：

.codex/
├── config.toml
├── skills/
│   ├── code-review.md
│   ├── deploy-k8s.md
│   └── write-tests.md

每个 Skill 文件遵循以下约定：

# skill-name

描述这个技能的用途。

## 触发条件

- 用户要求执行代码审查
- 用户提到了 "review" 或 "审查"
- ...

## 工作流程

1. 第一步做什么
2. 第二步做什么
3. ...

## 注意事项

- 特别需要注意的点
- 边界条件处理

## 示例

输入示例 → 输出示例

实战：编写一个代码审查 Skill

下面是一个完整的 code-review.md 技能文件示例：

# code-review

对 Pull Request 或代码变更执行系统性代码审查。

## 触发条件

- 用户明确请求代码审查
- 用户提到 review、审查、PR review 等关键词

## 工作流程

1. **确定变更范围**：运行 `git diff main...HEAD --stat` 获取变更文件列表和统计
2. **分批审查**：对大变更按文件分组，每次审查不超过 500 行
3. **逐项检查**：
   - 逻辑错误：边界条件、空值处理、死循环风险
   - 安全漏洞：注入攻击、敏感信息泄露、越权访问
   - 性能问题：N+1 查询、未使用索引、内存泄漏
   - 代码质量：命名规范、函数长度、圈复杂度
4. **生成报告**：按严重程度（Critical / Major / Minor）分类输出，附带文件路径和行号

## 审查清单

| 类别 | 检查项 |
|------|--------|
| 安全 | SQL 注入、XSS、CSRF、敏感信息硬编码 |
| 可靠 | 异常处理、超时设置、重试机制 |
| 性能 | 避免循环中查询、缓存策略、批量操作 |
| 可读 | 命名语义化、复杂逻辑注释、Magic Number 消除 |

## 输出格式

审查报告

分支：《branch-name》
变更文件：N 个
总行数变更：+XXX / -YYY

#### Critical

• [文件:行号] 问题描述 → 修复建议

#### Major

• [文件:行号] 问题描述 → 修复建议

#### Minor

• [文件:行号] 问题描述 → 修复建议

## 注意事项

- 对于不熟悉的语言或框架，主动声明并建议人工审查
- 不要对测试文件提出代码风格相关的 Critical 意见
- 如果变更量超过 2000 行，建议分批审查

当你把这个文件放到 .codex/skills/ 目录后，Codex 会在对话上下文中自动加载相关技能。当你输入类似"帮我审查一下这次的代码"的指令时，Codex 就会按照 Skill 中定义的工作流来执行。

技能触发机制

Codex 的技能系统并不是硬编码的规则匹配，而是基于语义相似度的智能匹配。当用户发送一条消息时，Codex 会：

扫描 .codex/skills/ 目录下所有的技能文件

提取每个技能的 触发条件 描述

将用户消息与技能描述进行语义匹配

如果匹配度超过阈值，将该技能的完整内容注入到对话上下文中

这意味着你不需要精确匹配关键词——Codex 能理解自然语言的意图。

一个更实用的例子：K8s 部署技能

# deploy-k8s

帮助用户将应用部署到 Kubernetes 集群。

## 触发条件

- 用户提到 Kubernetes 部署
- 用户要求部署、更新、回滚 K8s 服务
- 用户询问 kubectl 或 helm 相关操作

## 工作流程

1. **确认目标环境**：询问用户目标集群（dev / staging / production）
2. **检查 kubeconfig**：运行 `kubectl config current-context` 确认当前上下文
3. **构建镜像**：
   - 读取 Dockerfile 确认构建步骤
   - 执行 `docker build -t <registry>/<app>:<tag> .`
   - 推送到镜像仓库
4. **更新部署**：
   - 修改 k8s deployment 的 image tag
   - 执行 `kubectl apply -f k8s/deployment.yaml`
5. **验证部署**：
   - 运行 `kubectl rollout status deployment/<name>`
   - 检查 Pod 状态：`kubectl get pods -l app=<label>`

## 回滚流程

当用户请求回滚时：
1. `kubectl rollout history deployment/<name>` 查看历史版本
2. `kubectl rollout undo deployment/<name> --to-revision=<N>` 回滚到指定版本

## 安全检查

- 生产环境操作前**必须**向用户二次确认
- 避免直接使用 `latest` 标签
- 建议在非生产环境先验证

## 注意事项

- 不要修改 Ingress 或 Service 配置，除非用户明确要求
- Namespace 操作前确认上下文

斜杠命令 + Skill 的组合技巧

这两套系统可以组合使用，形成非常强大的工作流。例如：

用 Skill 定义审查标准，用 /review 触发：

# config.toml
[[slash_commands]]
command = "/review"
description = "按团队标准审查当前 PR"
prompt = "请按照 code-review 技能中定义的标准，审查当前分支的所有变更。"

用 Skill 定义部署规范，用 /deploy 触发：

[[slash_commands]]
command = "/deploy-staging"
description = "部署到 staging 环境"
prompt = "请按照 deploy-k8s 技能中的工作流，将当前项目部署到 staging 环境。"

用 Skill 定义测试规范：

# write-tests

为给定代码编写单元测试。

## 触发条件

- 用户要求编写测试
- 用户提到 "测试" "test" "unittest" 等

## 工作流程

1. 分析待测试的函数/方法签名和业务逻辑
2. 确定测试框架（从项目配置中自动检测）
3. 编写覆盖以下场景的测试：
   - 正常路径（Happy Path）
   - 边界条件
   - 异常路径
   - 空值/null 处理
4. 确保测试可独立运行，不依赖外部状态
5. 运行测试验证通过

## 输出格式

- 先给测试文件路径
- 然后贴上完整测试代码
- 最后显示测试运行结果

然后在 config.toml 中绑定：

[[slash_commands]]
command = "/test"
description = "为当前修改的文件生成测试代码"
prompt = "请按照 write-tests 技能中定义的标准，为当前已修改的源文件编写完整的单元测试。"

最佳实践

1. Skill 文件保持聚焦

一个 Skill 只做一件事。不要创建一个"万能助手" Skill，这样做反而会让匹配精度下降。每个 Skill 应该控制在 500 行以内，聚焦在单一领域。

2. 触发条件要具体而多样

在"触发条件"部分列出多种可能的用户表述方式，这能提高匹配命中率：

## 触发条件

- 用户要求执行代码审查 / review
- 用户说"帮我看下这段代码"、"review 一下"
- 用户提到 PR、MR、Pull Request
- 用户粘贴了 Diff 或 Patch 并要求评审

3. 利用记忆系统增强技能

Codex 的记忆系统（memory）可以与技能联动。在 Skill 中引用记忆中的信息：

## 工作流程

1. 读取 Codex 记忆，获取用户的项目偏好和习惯
2. 根据记忆中的代码风格偏好调整审查标准

4. 版本控制你的 Skills

由于 Skill 存放在项目目录中，建议将它们纳入 Git 版本控制。这样做有两个好处：

• 团队成员共享一致的 AI 工作标准
• 通过 Code Review Skills 文件本身，可以持续改进 AI 辅助流程

5. 分层配置

• 用户级 Skill（~/.codex/skills/）：与个人习惯相关的通用技能，如代码风格偏好
• 项目级 Skill（.codex/skills/）：与项目特定相关的技能，如部署流程、测试框架

Codex 在匹配时会同时搜索这两个路径。

调试技巧

查看已加载的技能

在 TUI 中，你可以输入 /help 或查看 Codex 的系统消息来确认哪些 Skill 被注入了上下文。你也可以在执行命令时将 Codex 的输出日志级别调高，以观察技能匹配过程。

验证斜杠命令

定义好斜杠命令后，在 TUI 中输入 / 就能看到命令列表。如果你定义的命令没有出现，检查以下几点：

config.toml 文件路径是否正确：用户级是 ~/.codex/config.toml，项目级是 .codex/config.toml

TOML 语法是否正确：建议用 codex --validate-config 验证

斜杠命令名称是否以 / 开头

prompt 和 script 不能同时为空

测试技能匹配

可以通过以下方式验证技能是否被正确匹配：

# 在项目目录下启动 Codex
codex

# 输入一条与技能相关的指令
> 帮我review一下最近的代码

如果技能被匹配，它会出现在对话的上下文注入中（可以在日志中看到）。

总结

斜杠命令和技能系统是 Codex 两个关键的自定义能力。简单来说：

• 斜杠命令是"快捷键"——让你不用每次都把长篇 Prompt 打一遍
• 技能系统是"专家手册"——让 Codex 在特定领域按你定义的标准流程工作

两者结合使用，可以极大地提升 Codex 在真实项目中的实用性。与其每次都从零开始指导 AI，不如花点时间把团队的工作规范沉淀为 Skill 文件，把高频操作封装为斜杠命令——这才是使用 AI 编程助手的正确姿势。

在下一篇文章中，我们将深入探讨 Codex 的 MCP（Model Context Protocol）服务器集成，看看如何让 Codex 与外部工具和 API 进行深度协作。