Codex Skills 技能系统实战指南：打造可复用的 AI 编程工作流模块

引言

在使用 Codex CLI 一段时间后，你可能会发现某些场景反复出现：每次调试都要向 AI 解释项目的日志规范，每次写 API 接口都要重复数据库表结构，每次部署都要说明 CI/CD 流程。这些"上下文传递成本"不仅消耗 token，更让 AI 无法在第一时间理解你的真实意图。

Codex 的 Skills 技能系统正是为解决这个问题而生的。它允许你将特定领域的知识、工作流程和最佳实践封装成可复用的模块，让 AI 在需要时自动加载，就像为它安装了一个"专业插件"。

本文将带你从零开始掌握 Codex Skills，从基本概念到实战案例，让你彻底告别重复的上下文灌输。

什么是 Skills 技能系统

Skills 本质上是一组按需加载的专业指令文件。每个 Skill 包含：

  • 元数据：名称、描述，用于 AI 判断何时激活该技能
  • 工作流指令：具体的操作步骤、工具使用规范、领域知识
  • 依赖声明：可引用的脚本、配置文件、工具链

当你在 Codex 中发起一个任务时，AI 会自动扫描所有已安装的 Skill，根据任务描述匹配最相关的技能并加载其上下文。这意味着你不需要每次都手动告诉 AI "这个项目用 PHPUnit 做测试"——只需要在 Skill 中定义一次即可。

Skills 与类似功能的区别

很多同学容易把 Skills 和其他 Codex 扩展机制混淆，这里做一个对比：

| 功能 | 触发方式 | 典型用途 |
|------|----------|----------|
| Skills | AI 自动匹配加载 | 领域知识、工作流模板 |
| Commands | 用户手动输入 /cmd | 快捷操作、常用指令 |
| MCP Servers | 工具调用时连接 | 外部 API、数据库集成 |
| AGENTS.md | 始终生效 | 项目全局规则 |

简而言之：AGENTS.md 是"宪法"（始终生效），Commands 是"快捷键"（手动触发），MCP 是"外部 API"（工具集成），而 Skills 是"专家顾问"（智能加载）。

Skill 文件结构

一个标准的 Skill 目录结构如下：

.opencode/skills/
├── blog-publish/
│   └── SKILL.md           # 技能定义文件
├── laravel-debug/
│   ├── SKILL.md
│   └── scripts/
│       └── analyze_log.sh # 配套脚本
└── api-design/
    └── SKILL.md

SKILL.md 编写规范

一个完整的 SKILL.md 文件通常包含以下部分：

# 技能描述（会用于 AI 匹配）

---
name: laravel-debug
description: 当用户需要调试 Laravel 应用时使用此技能，包括查看日志、追踪请求、分析异常
---

## 工作流程

1. 首先检查 `storage/logs/laravel.log` 获取最新错误
2. 如果涉及数据库查询，使用 `DB::getQueryLog()` 或 Laravel Debugbar
3. 对于 HTTP 请求问题，检查路由定义 `php artisan route:list`
4. 输出诊断报告时包含：错误类型、可能原因、修复建议

## 项目约定

- 日志级别：生产环境为 `error`，开发环境为 `debug`
- 异常上报使用 Sentry，配置在 `config/sentry.php`
- 所有 API 响应统一格式：`{ code: 0, data: {}, message: "" }`

## 常用命令

php artisan route:list
php artisan config:clear
php artisan queue:restart





创建第一个 Skill：代码审查助手


让我们创建一个实用的 Skill —— 自动化的代码审查流程。这个 Skill 会让 Codex 在审查代码时遵循特定的标准和步骤。


步骤 1：创建 Skill 目录


mkdir -p .opencode/skills/code-review


步骤 2：编写 SKILL.md


在 .opencode/skills/code-review/SKILL.md 中：


---
name: code-review
description: 对代码变更进行系统化审查，检查代码质量、安全性、性能和最佳实践
---

## 审查流程

1. **代码风格**：检查是否符合项目编码规范（PSR-12 / ESLint / gofmt）
2. **逻辑正确性**：验证边界条件、空值处理、异常捕获
3. **安全审查**：
   - SQL 注入风险（检查是否存在拼接查询）
   - XSS 防护（输出是否正确转义）
   - 敏感信息泄露（是否打印了密钥、密码）
4. **性能分析**：
   - N+1 查询问题
   - 不必要的循环嵌套
   - 大文件/大数据量的处理方式
5. **可维护性**：函数复杂度、命名清晰度、注释充分性

## 输出格式

审查结果按严重程度分三级：

- 🔴 严重：必须修复，可能导致安全事故或功能故障
- 🟡 警告：建议修复，可能影响性能或可维护性
- 🟢 建议：可选优化，提升代码质量

每个问题提供具体的代码位置和修改建议。


步骤 3：测试 Skill


在 Codex 中提交一个代码审查请求，AI 会自动检测到 code-review Skill 并按照你定义的流程执行审查：


> 请帮我审查 src/UserController.php 的代码变更


AI 会按照你定义的五个审查维度，给出带严重等级的审查报告。


实战：构建常用 Skills


下面分享几个在实际项目中高频使用的 Skill 定义。


API 接口开发 Skill


---
name: api-development
description: 开发 RESTful API 接口，包括路由定义、请求验证、控制器逻辑、响应格式化
---

## 技术栈

- 后端框架：Laravel 11
- API 文档：Scramble (自动生成 OpenAPI)
- 认证方式：Sanctum Token

## 开发规范

1. **路由命名**：使用 `api.{resource}.{action}` 格式，如 `api.users.store`
2. **请求验证**：统一使用 FormRequest 类，放在 `app/Http/Requests/Api/`
3. **响应格式**：


{

  "code": 0,

  "data": {},

  "message": "success"

}
4. **分页参数**：`page`（页码）、`per_page`（每页条数，默认15，最大100）
5. **异常处理**：统一在 `app/Exceptions/Handler.php` 中处理，错误码定义在 `App\Enums\ErrorCode`

## 开发流程

1. 定义路由（`routes/api.php`）
2. 创建 FormRequest 验证类
3. 实现 Controller 逻辑
4. 如果涉及新模型，创建 Migration + Model + Resource
5. 编写 Feature Test
6. 运行 `php artisan test --filter=Api`




Docker 部署 Skill


---
name: docker-deploy
description: Docker 容器化部署，包括构建镜像、编写 Compose 配置、处理环境变量和网络配置
---

## 项目约定

- 基础镜像：`php:8.3-fpm-alpine`
- 反向代理：Caddy Server（自动 HTTPS）
- 数据库：MySQL 8.0 + Redis 7

## 部署流程

1. **构建镜像**：


docker build -t app:latest -f docker/Dockerfile .
2. **启动服务**：



docker compose -f docker/docker-compose.prod.yml up -d
3. **健康检查验证**：



curl -f http://localhost:8080/api/health
4. **数据库迁移**（必须在服务启动后执行）：



docker compose exec app php artisan migrate --force
## 注意事项

- `.env` 文件不要打入镜像，通过 Docker secrets 或环境变量注入
- 日志写到 stdout，由 Docker 日志驱动收集
- 上传文件挂载到数据卷，不要存在容器内




Skills 的最佳实践


1. 控制粒度


Skill 不宜过于宽泛（如整个项目配置写成一个大 Skill），也不宜过于琐碎（每个小功能一个 Skill）。一个有效的粒度为：一个完整的任务工作流。


2. 明确触发条件


description 字段是 AI 判断是否加载 Skill 的关键依据。写得越精准，AI 的匹配就越准确。例如：


❌ 不佳：description: 帮助开发
✅ 推荐：description: 当用户需要创建 Laravel API 资源控制器、定义路由、
编写请求验证和格式化 JSON 响应时使用此技能


3. 保持更新


Skill 文件应该像代码一样接受版本管理。当项目的技术栈、规范发生变化时，同步更新对应的 Skill 文件。


4. 避免信息重复


如果一个约定已经写在 AGENTS.md 中（如"始终使用 PHP 8.3 语法"），就不要再在每个 Skill 中重复。Skill 应该包含该特定工作流独有的知识和步骤。


进阶：Skills 的组合使用


多个 Skills 可以协同工作。例如，当你实现一个新功能时：


Codex 加载 api-development Skill → 按照 API 规范生成代码


完成后，Codex 加载 code-review Skill → 进行代码审查


审查通过后，Codex 加载 docker-deploy Skill → 构建镜像并部署


用户只需要说一句：


> 帮我实现用户列表接口，包含分页和搜索功能


AI 就会自动串联整个开发→审查→部署的完整流程。这正是 Skills 系统的核心价值：将零散的知识整合成自动化的工作流链条。


总结


Codex Skills 技能系统让 AI 编程助手从"通用对话机器人"升级为"领域专家"。它的核心优势在于：


    

  • 知识沉淀：把团队的最佳实践固化到文件中，新人也能享受老手的经验
    • 

  • 自动触发：不需要手动记忆和输入，AI 自动识别场景并加载
    • 

  • 可组合：多个 Skill 可以串联成完整的自动化流程
    • 



如果你已经在使用 Codex CLI，建议从最频繁的重复场景开始，花 15 分钟写第一个 Skill 文件，你很快会发现那些反复"教" AI 的上下文，终于有了一个永久的家。


                        

                    

                

                

                    

                        
叶云梦天

                        

                            
叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客