Agent Skills 技能系统

16.1 Skills 是什么

Agent Skills(代理技能) 是 Codex 的可复用工作流封装单元。一个技能会把指令、资源以及可选脚本打包在一起,使 Codex 能够可靠地遵循某一工作流。

来自 51CTO《Codex 完整指南(七)》:

技能都是基于开放的 Agent Skills 标准 构建。一个技能通过位于 SKILL.md 文件中的 Markdown 指令来表达某种能力,技能文件夹中还可以包含脚本、资源和素材。

16.2 渐进式披露机制

Skills 采用渐进式披露(progressive disclosure) 高效管理上下文:

启动时:Codex 只加载每个可用技能的名称和描述
激活后:才加载完整指令、脚本、资源

这样即使有几十个技能,启动开销也很小。

16.3 激活技能的两种方式

方式	说明
显式调用	在 prompt 中用 `$` 提及技能,或 `/skills` 选择
隐式触发	描述匹配时自动激活

16.4 创建方式一:$skill-creator 交互式生成

官方内置一个 $skill-creator 技能,专门帮你生成新技能:

$skill-creator

交互式回答几个问题(技能名、用途、输入输出),它会生成 SKILL.md 初版。这是起步的最佳方式。

16.5 创建方式二:手动编写 SKILL.md

手动在技能目录下创建 SKILL.md,遵循 YAML front matter 规范:

---
name: log-triage
description: |
  排查应用日志,定位异常和错误。
  当用户说"查日志"、"日志报错"、"排查异常"时触发。
---

# Log Triage 技能

## 输入
- 日志文件路径或日志内容
- 关注的时间范围
- 关注的关键词(可选)

## 步骤
1. 读取日志文件
2. 按时间范围过滤
3. 提取 ERROR / WARN 级别
4. 关联同一请求的上下文
5. 输出:错误摘要 + 根因假设 + 建议排查方向

## 输出格式
- 错误时间、级别、消息
- 上下文(前后 N 行)
- 根因假设
- 建议下一步

16.6 技能格式详解

一个技能文件夹结构:

log-triage/
├── SKILL.md          # 必需,技能定义
├── scripts/          # 可选,辅助脚本
│   └── parse.py
├── templates/        # 可选,模板
│   └── report.md
└── data/             # 可选,参考数据
    └── known-issues.json

SKILL.md 的关键字段:

字段	作用
`name`	技能名(唯一标识)
`description`	描述——最重要的部分,决定何时触发
正文	指令(执行步骤、输入输出)

📌 官方强调:技能的 description 应该说清“这个技能做什么”和“什么时候用”,包含用户实际会说的触发短语。

16.7 作用域与加载优先级

Codex 按优先级从高到低依次加载(来自 51CTO 整理):

优先级	作用域	位置
1(最高)	REPO(当前目录)	`./.agents/skills/`
2	REPO(上一级)	`../.agents/skills/`
3	REPO(根目录)	仓库根 `.agents/skills/`
4	USER(用户级)	`$HOME/.agents/skills/`
5	ADMIN(系统级)	系统目录
6(最低)	SYSTEM(内置)	Codex 内置

支持符号链接与 config.toml 粒度启停。

16.8 保存位置:个人 vs 团队

类型	位置	用途
个人技能	`$HOME/.agents/skills`	自己用
团队技能	`.agents/skills`(仓库内)	check-in 到 Git,新人 onboarding

💡 团队技能 check-in 到仓库是新成员快速上手的好方法——他们 clone 仓库后自动获得所有团队技能。

16.9 显式调用与隐式触发

显式调用

/skills            # 选择技能
$log-triage        # 用 $ 提及技能名

隐式触发

当你的 prompt 描述匹配技能的 description 时,Codex 自动激活。所以 description 要写清触发条件。

16.10 主流 Skills 仓库

仓库	说明
openai/skills	官方推荐,可作为模板
agentskills.io	社区索引/市场,分类齐全
anthropics/skills	Claude 社区示例,可借鉴复杂技能设计

16.11 Skills 设计原则

官方建议:

小而精:每个技能聚焦单一职责
指令优先:用清晰的步骤指令,而不是堆脚本
描述明确:写清触发条件,避免歧义
示例验证:用示例 prompt 验证触发逻辑
不要一上来覆盖所有边界:先选典型任务,跑几次,补失败经验

16.12 什么时候应该做成 Skill

官方判断标准:

If you keep reusing the same prompt or correcting the same workflow, it should probably become a skill.

(如果你反复用同一段 prompt,或反复纠正同一个流程,它大概率应该变成技能。)

适合做成 Skill 的场景:

日志排查
发布说明生成
PR checklist review
数据迁移计划
事故复盘摘要
标准调试流程

16.13 打包为 Plugin 共享

技能成熟后,可以打包成 Plugin 共享给社区。$skill-creator 生成的初版建议先本地迭代,稳定后再打包发布。

资料来源

51CTO《Codex 完整指南(七):Agent Skills 详解》——核心概念、作用域、社区仓库
OpenAI 官方 Codex best practices——Skills 使用建议
官方 Skills 文档
官方 Plugin build 文档