Codex Agent Skills（智能体技能体系）
Agent Skills 是 Codex 的能力扩展模块，相当于给智能体附加一套领域专业能力包，封装角色设定、系统提示、工具调用逻辑与标准化工作流。Skill 文件以 Markdown 格式存放于项目 .codex/skills/ 目录，支持内置技能、自定义私有技能以及从技能市场安装第三方技能。和一次性提示词不同，Skill 可以按需激活复用，让 Codex 在特定开发场景输出行为稳定、流程统一。本文讲解 Agent Skills 的基础概念、内置技能、自定义编写、技能管理命令、最佳实践与常见问题。
一、Agent Skills 基础概念
Agent Skill 是封装好的领域能力包，由角色定义、系统提示、工具调用规则、完整工作流、输出格式共同组成。
| 维度 | 说明 |
|---|---|
| 定义 | 面向特定开发领域的专业能力扩展包 |
| 组成 | 角色设定 + 系统提示 + 工具调用 + 标准化工作流 |
| 文件格式 | Markdown |
| 存放路径 | 项目目录下 .codex/skills/ |
重要区分：
AGENTS.md属于全局项目规则，对全部任务永久生效；Agent Skills 是可选能力扩展，需要手动激活才生效。
Skill 与普通提示词的差异
- 普通提示词：单次对话临时生效，每次需要重复描述规则，输出行为不稳定。
- Agent Skill：文件固化定义，可复用、可团队共享，通过斜杆命令按需激活，自带完整工作流与校验规则。
技能触发方式
- 显式触发（推荐）：使用
/skill斜杆命令手动指定技能，精准控制本次任务使用的能力包。 - 隐式触发：Codex 根据用户任务意图自动匹配可用技能，适合简单场景；复杂任务建议显式调用，避免匹配错误。
二、Codex 内置 Skills
Codex 自带一组开箱即用的内置技能，无需编写任何文件，直接通过斜杆命令调用。
| Skill名称 | 核心能力 | 典型适用场景 |
|---|---|---|
| code‑review | 代码审查，检查质量、规范、耦合问题 | PR/MR变更评审 |
| debug | 自动调试定位、修复Bug | 报错、异常堆栈修复 |
| test‑gen | 批量生成单元、集成测试用例 | 补充项目测试覆盖 |
| doc‑gen | 自动生成注释、API文档、说明文档 | 接口文档、模块说明生成 |
| refactor | 在不改变业务前提下做代码重构优化 | 代码结构优化、整理旧代码 |
| security | 安全漏洞扫描，识别密钥注入、越权风险 | 项目安全审计 |
内置技能调用示例
# 调用代码审查技能 /skill code-review 审查 src/auth.ts 的代码质量调用调试修复技能/skill debug
修复 TypeError: Cannot read property 'id' of undefined
使用 security 安全审计技能示例
/skill security
扫描整个项目的安全漏洞
输出样例：
🔴 [严重] src/auth.ts:45 - 硬编码密钥
🟡 [中等] src/api.ts:23 - SQL 拼接未做参数化
🟢 [低] src/utils.ts:12 - 缺少输入参数校验
三、自定义 Skills
当内置技能无法满足团队业务规范、技术栈要求时，可以编写自定义 Skill，保存到项目 .codex/skills/ 目录，提交到代码仓库即可实现团队共享。
一份标准自定义 Skill 文件包含：角色、执行规则、工作流步骤、输出格式，可引入项目模板文件作为参考。
示例1：React组件生成技能 .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
调用自定义技能：
/skill react-component
创建一个 DatePicker 组件，支持日期范围选择
示例2：FastAPI接口生成技能 .codex/skills/api-endpoint.md
# API Endpoint Generator ## 角色 你是 FastAPI 端点开发专家。## 规则
- 使用 Pydantic 模型做请求/响应验证
- 所有端点包含错误处理
- 使用 dependency injection
- 包含 Swagger 文档
- 编写 pytest 测试 ## 模板
参考 src/api/templates/standard_endpoint.py 工作流定义 Pydantic 请求模型 定义 Pydantic 响应模型 实现端点逻辑 添加错误处理 编写测试确保 pytest 通过
四、Skills 管理命令
所有客户端（桌面、CLI、IDE）均支持技能管理斜杆命令：
# 列出当前项目全部可用技能 /skills list# 查看某个技能的详细定义
/skills info code-review # 启用、禁用指定技能
/skills enable react-component
/skills disable doc-gen# 从技能市场安装第三方技能包
/skills install graphql-api
注意：内置技能不能直接修改；如果需要改写内置行为，可以创建同名自定义Skill，会自动覆盖内置版本。
五、Skills 最佳实践
| 实践原则 | 说明 |
|---|---|
| 领域专一 | 一个Skill只解决一类问题，不要把多种无关能力写进同一个Skill |
| 引用模板 | 在Skill内指定项目内部模板文件路径，统一输出风格 |
| 明确工作流 | 写明完整执行步骤，减少AI随机发挥 |
| 定义验证方式 | 写明任务完成后的自测、验证标准 |
| 持续迭代 | 根据团队反馈持续更新Skill规则 |
| 单任务单Skill | 一次任务尽量只启用一个Skill，避免多条规则互相冲突 |
六、常见问题
Q：Skills 和 AGENTS.md 的区别？
A：AGENTS.md 是项目全局规则，所有任务永久生效；Skills 是可选能力包，需要 /skill 命令手动激活。
Q：如何在团队内共享自定义 Skill？
A：把 .codex/skills/ 目录提交到Git仓库，团队其他成员拉取代码即可直接使用。也可以发布到公共Skills市场供外部下载。
Q：使用Skills会不会增加Token消耗？
A：Skill的角色、规则、工作流会占用上下文Token；但对比每次手动重复写一大段提示词，整体token开销更低，输出稳定性更好。
Q：可以修改官方内置Skills吗？
A：不能直接修改内置源文件，可以创建同名自定义Skill，本地会优先加载自定义版本，实现覆盖。
Q：同一个任务可以同时启用多个Skill吗？
A：不建议，多条规则容易发生冲突，导致输出混乱，一个任务尽量只激活一个Skill。
七、总结
Agent Skills 是 Codex 的模块化能力扩展，分为官方内置技能、项目自定义技能、市场第三方技能。Skill文件存放在 .codex/skills/，通过 /skill 系列斜杆命令完成调用、查看、启用、禁用。它和全局规则文件AGENTS.md互为补充：AGENTS.md管全局约束，Skills管按需加载的领域工作流。团队可以把高频开发流程沉淀为Skill，减少大量重复提示词，让AI输出更加标准化、可复用。
0 条笔记