用 Skills 复用能力

Skill 是可复用工作流的编写格式。它把任务说明、资源和可选脚本放进一个目录，让 Codex 在匹配任务时按同一套方法执行。

如果你反复复制同一段 prompt，或反复纠正 Codex 的同一类错误，它大概率应该变成 skill。

Skills

查看 Codex skills 的官方说明。

Create skills

学习如何创建 SKILL.md 和配套资源。

Plugins

当 skill 需要分发给别人安装时，再打包成 plugin。

Skill 解决什么

flowchart LR
    Repeat["重复 prompt / 重复纠错"] --> Skill["Skill"]
    Skill --> Stable["稳定流程"]
    Skill --> Trigger["清楚触发"]
    Skill --> Verify["固定验证"]

适合：

文档美化。
PR review。
release note。
日志分诊。
migration planning。
安全检查清单。
固定格式输出。

不适合：

一次性任务。
还没跑稳的流程。
需要大量临场判断的开放问题。
只是存放一堆资料的目录。

基本结构

my-skill/
  SKILL.md
  scripts/
  references/
  assets/

SKILL.md 至少要说明：

skill 名称。
description：什么时候触发，什么时候不触发。
输入。
步骤。
输出。
验证方式。
风险边界。

脚本、模板和参考资料只在能提升可靠性时加入。不要为了显得复杂而加文件。

Codex 如何选择 skill

Codex 通常先看到 skill 的 name、description 和路径。只有判断任务需要时，才加载完整 SKILL.md。

所以 description 必须准确：

开头写核心任务。
写出用户真实会说的触发词。
写清不适用场景。
避免泛泛写“提高效率”。

描述越泛，误触发越多。

创建流程

推荐顺序：

先用普通 prompt 跑通一次。
重复多次，记录稳定步骤和失败点。
用 $skill-creator 或手动创建 skill。
用真实任务测试触发。
修改 description 和验证步骤。
需要团队分发时，再做 plugin。

Skill 是流程沉淀，不是流程想象。先实践，再封装。

保存位置和分发

官方 skills 支持 CLI、IDE extension 和 Codex app。保存位置决定谁能看到它：

范围	位置	用途
Repo 当前目录	`$CWD/.agents/skills`	只服务当前工作目录。
Repo 父目录	`$CWD/../.agents/skills`	子模块共享同一组技能。
Repo 根目录	`$REPO_ROOT/.agents/skills`	仓库级团队工作流。
User	`$HOME/.agents/skills`	个人所有项目可用。
Admin	`/etc/codex/skills`	受管理机器统一提供。
System	Codex 内置	OpenAI 打包的通用技能。

Codex 支持 symlinked skill folders。对于大体积技能库，可以用软链接复用一份主库，避免复制多份。

如果要跨 repo、跨团队分发，或把 skill 与 MCP、app integration 一起打包，使用 plugin。

显式调用和隐式调用

Codex 使用 skill 有两种方式：

显式调用：在 CLI/IDE 中用 /skills 或 $skill-name 指定。
隐式调用：Codex 根据任务与 description 的匹配自动选择。

隐式调用依赖 description，所以描述要把触发词前置。例如：

---
name: release-note-writer
description: Use when turning merged PRs or git commits into concise release notes. Do not use for general blog writing.
---

这个 description 同时说明“用来写 release notes”和“不用于普通博客”。比“帮助写作”这类泛描述可靠得多。

Progressive disclosure

Skills 的关键机制是 progressive disclosure：Codex 启动时只把 skill name、description 和路径放进上下文；真正需要时才读取完整 SKILL.md。

这意味着：

SKILL.md 可以放详细步骤，但 description 必须短而准。
长参考资料不要塞进 description，放到 references/。
大量 skills 会占初始上下文预算，描述会被压缩或省略，所以最重要的触发词要写在开头。
如果某个技能必须避免误触发，可以在 agents/openai.yaml 中关闭 implicit invocation，只允许显式调用。

质量检查

一个 skill 合格，应满足：

能被正确触发。
不会在错误任务中误触发。
步骤足够短而明确。
输出格式稳定。
验证方式可执行。
不包含密钥或私有路径。
修改后能在干净任务中复验。

Skill 的目标是让 Codex 少问重复问题、少犯重复错误、按稳定标准交付。