Codex Skill 是什么：给 agent 的可复用工作流

Codex Skill 是一个文件夹，里面至少有一个 SKILL.md。它把某类重复任务的做法写成说明，让 Codex 在需要时加载这套工作流。

你可以把它理解成：给 agent 的“专业工作说明书”。

Codex 怎么使用 Skill

Codex 不是一开始就把所有 Skill 全文塞进上下文。它采用渐进加载：

阶段	Codex 看到什么	新手应该检查什么
发现	Skill 的 name、description、文件路径	名称和描述是否清楚，是否会误触发
触发	任务和 description 匹配，或你显式提到 $skill-name	这个任务是否真的需要 Skill
加载	Codex 读取完整 SKILL.md	正文是否有步骤、输入、输出、停止条件
执行	按需读取 references/、使用 assets/、运行 scripts/	是否会写文件、联网、运行命令、用账号

所以 description 很重要。它不是广告文案，而是 Codex 判断“什么时候用这个 Skill”的触发器。

一个 Skill 通常长什么样

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── agents/openai.yaml

你第一次只需要看四个问题：

1. SKILL.md 是否有清楚的 name 和 description。
2. 正文是否告诉 Codex 先做什么、后做什么、输出什么。
3. 有没有 scripts/，脚本会不会读写文件或联网。
4. 有没有 references/ 或 assets/，里面是否包含需要复核的资料、模板或版权内容。

Skill 和这些东西有什么区别

名称	解决什么	例子	新手判断
一次性指令	当前这一次任务怎么做	“先只读项目，不要改文件”	适合临时任务
AGENTS.md	当前仓库的长期项目规则	代码风格、测试命令、禁止改哪些目录	适合项目级规则
Skill	某类重复任务的工作流	浏览器验收、CI 修复、威胁建模、部署检查	适合反复出现的任务
MCP	连接外部工具和数据	GitHub、数据库、浏览器、云服务	权限风险更高
Plugin	分发单元，可以打包 Skill、App、MCP 配置	面向多人安装和复用	先理解 Skill，再看 Plugin

一句话：如果只是这次要提醒 Codex，不用 Skill；如果每次都要做同类任务，才考虑 Skill。

什么时候需要 Skill

适合做 Skill 的任务有三个特征：

• 重复：你每周都会做类似任务。
• 有流程：步骤、输入、输出、验收比较固定。
• 容易漏：只靠临时指令时，Codex 经常忘记某个检查项。

例如：

• 每次改前端都要跑移动端截图和控制台检查。
• 每次处理 GitHub PR 评论都要先分类、再逐条回应、再跑测试。
• 每次部署前都要确认环境变量、构建目录、费用风险、回滚方式。
• 每次写安全评估都要列资产、信任边界、攻击路径和缓解措施。

什么时候不要用 Skill

• 你第一次使用 Codex，连只读摸底还没跑通。
• 任务只发生一次，写普通指令更快。
• Skill 来源不清楚，或者没有 License。
• Skill 里有脚本，但你看不懂脚本会做什么。
• Skill 需要 GitHub、云服务、数据库、Token、cookie 或生产 .env。

新手第一条只读指令

请只读解释 Codex Skill 的工作方式，不要安装任何 Skill。

请用我能理解的方式说明：
1. Codex 如何根据 name 和 description 发现 Skill
2. 什么时候会加载 SKILL.md 正文
3. scripts、references、assets 分别可能带来什么价值和风险
4. Skill 和 AGENTS.md、MCP、Plugin 的区别
5. 我当前任务是否真的需要 Skill

成功标志

读完这页，你应该能说出：

• Skill 不是聊天话术，而是可复用工作流。
• description 决定 Codex 什么时候可能用它。
• 有 scripts/ 就要先只读审查，不要直接运行。
• 不是所有重复规则都应该写成 Skill；项目规则通常放 AGENTS.md 更合适。
• 安装 Skill 前要先判断权限、账号、脚本和回滚。

来源与日期

• 来源：Codex Agent Skills、Agent Skills Overview、openai/skills。
• 访问日期：2026-06-17。