AGENTS.md、Skill、Plugin 到底有什么区别？一篇讲清 Codex 工作流复用

使用 Codex 一段时间后，你可能会遇到三类需求：

希望所有项目任务都遵守同一组规则；
希望重复使用一套专项工作流程；
希望把流程、工具和外部连接打包给团队安装。

它们分别对应 AGENTS.md、Skill 和 Plugin。

先记住这张对照表

概念	解决的问题	类比
`AGENTS.md`	当前项目里所有任务都要遵守什么	项目工作守则
Skill	某一类任务应该按什么步骤完成	专项操作手册
Plugin	如何安装和分发一组能力	工具箱或安装包

例如：

“不要读取 .env，提交前必须跑测试”适合放进 AGENTS.md。
“怎样审查一篇 Markdown 文档”适合写成 Skill。
“把文档审查、GitHub 工具、Hooks 和图标一起安装”适合做成 Plugin。

Skill 是可复用的任务流程

一个最小 Skill 只需要一个 SKILL.md：

---
name: doc-review
description: Review Markdown documentation for structure, factual accuracy, links, and unclear wording. Use when the user asks to review documentation.
---

Read the target document first.
Report concrete issues before rewriting.
Check links and validation results.

name 是稳定标识，通常使用小写 kebab-case；description 同时要写清能力和触发场景，因为 Codex 会用它判断什么时候启用这个 Skill。

“Helps with documents”太模糊；“Review Markdown documentation for structure, factual accuracy and links”就清楚得多。

Skill 为什么要渐进式加载

一个完整 Skill 可以包含：

doc-review/
├── SKILL.md
├── scripts/
├── references/
└── assets/

SKILL.md：入口、步骤、边界和完成标准；
scripts/：可重复执行的脚本；
references/：需要时才读取的长资料；
assets/：模板、图片和示例文件。

Codex 启动时通常只看到 Skill 的名称和描述。真正匹配任务后才读取完整 SKILL.md，再按需打开脚本和参考资料。

这样既能安装多个 Skill，又不会让每一份完整说明一开始就占满上下文。

什么任务值得写成 Skill

适合沉淀成 Skill 的任务通常具备三个特征：

会重复出现；
步骤相对稳定；
需要特定判断和验证。

典型场景包括：

按团队标准做 PR Review；
修复 CI 并整理原因；
把 PDF 转成知识库笔记；
生成 PPT、PDF 或固定格式报告；
检查文档链接和事实来源；
按统一流程操作 GitHub、飞书或知识库。

一次性的回复偏好不需要写成 Skill；整个项目都要遵守的通用规则更适合 AGENTS.md。

Plugin 是能力的分发单元

当一个流程不仅需要说明，还需要连接工具和外部系统时，可以考虑 Plugin。

一个 Plugin 可以组合：

多个 Skills；
MCP 服务；
Apps 或外部连接；
Hooks；
图标、截图和模板。

典型结构如下：

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
├── hooks/
├── .app.json
├── .mcp.json
└── assets/

其中 .codex-plugin/plugin.json 是入口。Plugin 解决的是“如何安装和统一分发”，而 Skill 解决的是“这个任务具体怎么做”。

什么时候从 Skill 升级到 Plugin

可以用下面的判断方式：

需求	选择
自己复用一套写作或审查流程	Skill
流程需要脚本和模板	Skill
多个流程需要统一安装	Plugin
同时需要 Skills、MCP、Hooks 或 App	Plugin
需要面向团队发布和版本管理	Plugin

最稳妥的路线是：先做一个小 Skill，验证有效后再打包成 Plugin。

写 Skill 时的六条建议

名称稳定，目录名和 name 保持一致；
description 写清触发场景；
正文聚焦执行步骤，不写成百科；
明确输入、输出、边界和异常处理；
把长资料、脚本和模板拆到独立目录；
涉及联网、写文件或外部系统时，明确权限和人工复核点。

另外，不要把 token、密码和私有凭据放进 Skill 或 Plugin。

写在最后

把工作流复用起来，可以沿着这条路径：

一次成功任务
→ 整理成稳定步骤
→ 写成 Skill
→ 加入脚本与模板
→ 多能力组合成 Plugin
→ 团队统一安装和迭代

真正有价值的不是囤积大量 Skills，而是把那些已经被真实任务验证过的经验，变成下一次可以可靠调用的能力。