官方原文索引： Agent Skills / Build plugins / Skill Creator
1. 核心架构与原理解析
Skill 是 Codex 的可复用工作流单元，区别于一次性 Prompt：
| 维度 | Prompt | Skill |
|---|---|---|
| 复用性 | 单次使用 | 跨项目复用 |
| 调用方式 | 自然语言 | /skill-name 或隐式匹配 |
| 版本管理 | 无 | 可版本化、可分发 |
| 参数化 | 有限 | 支持命名参数和位置参数 |
Skill 查找路径：
Skill 与 Plugin 的区别：
| 维度 | Skill | Plugin |
|---|---|---|
| 范围 | 单个工作流 | 多个 Skill + 规则集合 |
| 分发 | 文件系统 | npm 包 |
| 安装 | 直接放目录 | codex plugin install |
| 适用 | 个人/小团队 | 团队/企业 |
2. 工程落地与代码示例
Skill 文件结构
# 创建用户级 Skill
mkdir -p ~/.codex/skills
# Skill 文件：~/.codex/skills/security-audit.md
---
name: security-audit
description: 对指定目录进行安全审计，输出风险报告
---
扮演一名资深安全工程师，对 {{path}} 目录进行安全审计。
检查项：
1. 硬编码密钥和 Token
2. SQL 注入风险
3. 不安全的反序列化
4. 缺少输入验证
5. 敏感信息日志泄露
输出格式：
- [Critical/High/Medium] 文件:行号 - 问题描述 - 修复建议带参数 Skill
# ~/.codex/skills/refactor-module.md
---
name: refactor-module
description: 按 Clean Architecture 重构指定模块
---
将 {{MODULE}} 模块重构为 Clean Architecture 分层：
1. Domain（实体、值对象、领域事件）
2. UseCase（应用服务、业务逻辑）
3. Adapter（接口适配、数据库仓库）
4. Infrastructure（框架、外部服务）
约束：
- 保持现有 API 接口不变
- 所有新代码必须有单元测试
- 使用 {{LANGUAGE}} 语言习惯用法
验证：
- 运行 {{TEST_COMMAND}}
- 确保所有测试通过调用 Skill
# 位置参数
> /security-audit src/payment
# 命名参数
> /refactor-module MODULE=auth LANGUAGE=TypeScript TEST_COMMAND="npm test"
# 混合参数
> /security-audit path=src/payment level=high复杂 Skill 示例（API 设计审查）
# ~/.codex/skills/api-review.md
---
name: api-review
description: 审查 REST API 设计是否符合最佳实践
---
审查 {{FILE}} 中的 API 端点设计，检查以下维度：
## 1. RESTful 规范
- [ ] URL 使用名词复数（/users 而非 /getUsers）
- [ ] HTTP 方法语义正确（GET/POST/PUT/DELETE/PATCH）
- [ ] 状态码使用恰当（200/201/204/400/401/403/404/409/422/500）
## 2. 安全性
- [ ] 敏感操作需要认证
- [ ] 输入参数经过校验
- [ ] 响应不包含敏感字段
- [ ] 有速率限制说明
## 3. 可维护性
- [ ] 有 OpenAPI/Swagger 文档
- [ ] 错误响应格式统一
- [ ] 版本控制策略明确（/v1/users）
## 4. 性能
- [ ] 支持分页（limit/offset 或 cursor）
- [ ] 支持字段筛选（fields=）
- [ ] 支持条件过滤（q=）
输出格式：
[Pass/Warning/Fail] 检查项 - 具体位置 - 改进建议3. 场景深入：Skill 在团队中的演进
场景：个人工作流沉淀
场景：团队 Skill 共享
# 1. 团队 Skill 仓库
git clone https://github.com/company/codex-skills.git
# 2. 软链接到本地
ln -s $(pwd)/codex-skills ~/.codex/skills/company
# 3. 使用团队 Skill
> /company/security-audit src/场景：Skill 版本管理
# ~/.codex/skills/migration-v1.md
---
name: migration
description: 数据库迁移（v1 旧版）
version: 1.0.0
---
[旧版逻辑...]
# ~/.codex/skills/migration-v2.md
---
name: migration
description: 数据库迁移（v2 新版，支持回滚）
version: 2.0.0
---
[新版逻辑...]4. 💡 核心避坑与最佳实践 (Takeaways)
- Skill 先本地验证再分发：先在个人
~/.codex/skills/打磨，稳定后再打包为 Plugin - 参数名全大写：
{{CITY}}可被自动补全，小写可能识别失败 - 描述决定隐式匹配：
description是 Codex 决定是否调用 Skill 的依据，需精确描述适用场景 - Skill 不是知识库：存放工作流（"怎么做"），而非静态知识（"是什么"）
- 版本化重要 Skill：核心工作流 Skill 应标注版本，避免更新后破坏现有流程
- 文档即契约：Skill 的头部 YAML 必须包含清晰的 name、description 和参数说明