Codex: Codex Agent Skills
最后更新：2026-08-31
Agent Skills 让 Codex 获得特定领域的专业能力，类似人类的专业技能认证。
📋 前置知识：了解 Codex 基本操作与配置
1. 你将学到
- Agent Skills 概念
- 内置 Skills
- 自定义 Skills
- Skills 市场
2. 什么是 Agent Skills
Agent Skills 是 Codex 的能力扩展模块，每个 Skill 封装了特定领域的知识和工作流。
| 维度 | 说明 |
|---|---|
| 定义 | 特定领域的专业能力包 |
| 内容 | 系统提示 + 工具调用 + 工作流 |
| 格式 | Markdown 文件 |
| 位置 | .codex/skills/ 目录 |
3. 内置 Skills
Codex 内置了多种常用 Skills：
| Skill | 能力 | 适用场景 |
|---|---|---|
| code-review | 代码审查 | PR 审查 |
| debug | 调试修复 | Bug 修复 |
| test-gen | 测试生成 | 补充测试 |
| doc-gen | 文档生成 | API 文档 |
| refactor | 重构 | 代码优化 |
| security | 安全扫描 | 安全审计 |
(1) 使用内置 Skill
TEXT
📖 仅展示
> /skill code-review
> 审查 src/auth.ts 的代码质量
> /skill debug
> 修复 TypeError: Cannot read property 'id' of undefined
▶ 示例 1: Alice 使用内置 Skills
TEXT
📖 仅展示
# Alice 用 security Skill 做安全审计
> /skill security
> 扫描整个项目的安全漏洞
# 输出：
# 🔴 [严重] src/auth.ts:45 - 硬编码密钥
# 🟡 [中等] src/api.ts:23 - SQL 拼接未参数化
# 🟢 [低] src/utils.ts:12 - 缺少输入验证
4. 自定义 Skills
(1) 创建 Skill 文件
MARKDOWN
<!-- .codex/skills/react-component.md -->
# React Component Generator
## 角色
你是一个 React 组件开发专家，精通 TypeScript 和现代 React 模式。
## 规则
- 使用函数式组件
- 使用 TypeScript 类型注解
- Props 使用 interface 定义
- 使用 CSS Modules 或 Tailwind
- 包含 Storybook story
- 包含单元测试
## 工作流
1. 分析组件需求
2. 定义 Props interface
3. 实现组件逻辑
4. 添加样式
5. 创建 Storybook story
6. 编写单元测试
7. 验证 TypeScript 编译
## 输出格式
- 组件文件：src/components/ComponentName.tsx
- 样式文件：src/components/ComponentName.module.css
- Story 文件：src/components/ComponentName.stories.tsx
- 测试文件：src/components/ComponentName.test.tsx
(2) 使用自定义 Skill
TEXT
📖 仅展示
> /skill react-component
> 创建一个 DatePicker 组件，支持日期范围选择
▶ 示例 2: Bob 创建专属 Skill
MARKDOWN
<!-- .codex/skills/api-endpoint.md -->
# API Endpoint Generator
## 角色
你是 FastAPI 端点开发专家。
## 规则
- 使用 Pydantic 模型做请求/响应验证
- 所有端点包含错误处理
- 使用 dependency injection
- 包含 Swagger 文档
- 编写 pytest 测试
## 模板
参考 src/api/templates/standard_endpoint.py
## 工作流
1. 定义 Pydantic 请求模型
2. 定义 Pydantic 响应模型
3. 实现端点逻辑
4. 添加错误处理
5. 编写测试
6. 确保 pytest 通过
5. Skills 管理
(1) 列出 Skills
TEXT
📖 仅展示
/skills list
(2) 查看 Skill 详情
TEXT
📖 仅展示
/skills info code-review
(3) 启用/禁用 Skill
TEXT
📖 仅展示
/skills enable react-component
/skills disable doc-gen
(4) 从市场安装
TEXT
📖 仅展示
/skills install graphql-api
6. Skills 最佳实践
| 实践 | 说明 |
|---|---|
| 领域专一 | 每个 Skill 只覆盖一个领域 |
| 包含模板 | 提供代码模板作为参考 |
| 明确工作流 | 定义清晰的执行步骤 |
| 包含验证 | 说明如何验证输出 |
| 持续迭代 | 根据使用反馈改进 Skill |
❓ 常见问题
Q Skills 和 AGENTS.md 有什么区别？
A AGENTS.md 是项目级规则（所有任务生效），Skills 是可选的能力扩展（按需激活）。
Q 可以分享 Skills 吗？
A 可以。将 Skill 文件提交到仓库，团队成员自动获得。也可以发布到 Skills 市场。
Q Skills 会增加 token 消耗吗？
A 会。Skill 的系统提示会占用上下文窗口，但比没有 Skill 时反复描述要更高效。
Q 内置 Skills 可以修改吗？
A 不能直接修改内置 Skills，但可以创建同名自定义 Skill 覆盖内置版本。
Q 一个任务能用多个 Skills 吗？
A 不建议。每个任务最好只用一个 Skill，避免指令冲突。
📖 小节
- Skills 是 Codex 的能力扩展模块
- 内置 Skills：code-review / debug / test-gen / doc-gen / refactor / security
- 自定义 Skills：放在
.codex/skills/目录 - Skills 包含：角色定义 + 规则 + 工作流 + 输出格式
- 专一领域、包含模板、明确工作流
📝 作业
- 基础题（难度⭐）：使用一个内置 Skill 完成任务，对比不使用 Skill 的效果差异。
- 进阶题（难度⭐⭐）：为你常用的开发场景创建一个自定义 Skill。
- 挑战题（难度⭐⭐⭐）：创建一套完整的 Skills 库，覆盖你团队的所有开发场景。
