一句话总结
Codex 的 skill 就是一个带 SKILL.md 文件的文件夹（可以再加脚本和参考资料），Codex 会在需要时按需加载它，用来跑一套可重复的工作流。平时 Codex 只看到每个 skill 的名字、描述和路径，等到判断某个 skill 匹配你的任务时，才会读完整的 SKILL.md。你可以用 /skills 浏览、用 $skill-name 强制调用，也可以让 Codex 根据你的措辞自动选。本文讲清楚 skill 放在哪、好的 SKILL.md 长什么样，以及什么时候用 skill 比写 AGENTS.md 规则、接 MCP 或装插件更合适。
版本提醒：Agent Skills 在 2025 年 12 月为 Codex 上线，之后一直在迭代。本文按 2026 年 6 月的 Codex CLI 与桌面版行为整理。最终以你当前会话里的
/skills列表和官方 Agent Skills 文档 为准。
skill 到底是什么
skill 的作用，是把你反复解释的那套流程变成一个可发现的能力。与其每周都粘贴同一段“我们的发布检查是这样做的”提示词，不如把它写成一份 SKILL.md，放进 skills 目录，之后直接按名字调用。
让这件事在上下文成本上很划算的机制叫渐进式加载（progressive disclosure）。启动时 Codex 只读取它能看到的每个 skill 的元数据（名字、描述、文件路径）。按 OpenAI 文档的说法，这份索引的上限大约是模型上下文窗口的 2%，在窗口未知时则约为 8,000 个字符，所以哪怕有几十个 skill，不用它们时几乎不占上下文。只有当 Codex 选中某个 skill，它才会去读完整的 SKILL.md 指令以及里面引用的文件。
/skills 是什么
| 项目 | 作用 |
|---|---|
/skills | 打开一个交互式选择器，列出当前会话可见的 skill；你选中的那个会被插入为下一条请求的上下文。 |
$skill-name | 在提示里直接点名调用某个 skill，强制使用，前提是你知道名字。 |
| 自动选择 | 当任务明显匹配 skill 的 description 时，Codex 会自己加载它。 |
SKILL.md | 指令入口：YAML 头部信息加上 Markdown 步骤。 |
| skill 附件 | 工作流可选用的 scripts/、templates/、references/。 |
/skills 不是“运行所有 skill”，也不是“安装 skill”。它是一个发现入口：告诉你这个会话里有哪些能力可用，并让你挑一个来应用。
Codex 在哪些位置找 skill
Codex 会从多个范围按“就近优先”的顺序查找 skill。截至 2026 年 6 月，标准位置如下：
| 范围 | 路径 | 用途 |
|---|---|---|
| 仓库（最近层） | .agents/skills/ | 某个目录或模块专用的工作流 |
| 仓库（上一层） | ../.agents/skills/ | 嵌套的项目结构 |
| 仓库（根目录） | $REPO_ROOT/.agents/skills/ | 整个仓库 / 团队共享的 skill |
| 用户 | $HOME/.agents/skills/ | 你个人的跨仓库 skill |
| 管理员 | /etc/codex/skills/ | 全组织的系统默认值 |
| 系统 | 随 Codex 内置 | OpenAI 自带的内置 skill |
几点实用提醒：同名 skill 不会合并，两份都会出现在选择器里，所以名字要保持唯一；支持软链接的 skill 文件夹，方便在多台机器间共用同一套 skill；如果某个 skill 在 /skills 里看不到，基本都是因为它在 Codex 读不到的路径，或者对应插件没启用。
skill、AGENTS.md、prompt、MCP、plugin 怎么选
这五种定制层会有重叠，按意图来选最清楚：
| 你要做什么 | 用什么 | 为什么 |
|---|---|---|
| 给项目一套长期规则 | AGENTS.md | 仓库约定、测试命令、代码风格、不可碰的目录。始终生效，不是工作流。 |
| 一套可复用的多步骤工作流 | skill | 发布检查、SEO 审计、渲染验证，按需加载。 |
| 一句简短的指令 | 普通 prompt | 太小，不值得做成 skill。 |
| 连接外部系统 | MCP | 浏览器、数据库、GitHub、内部 API。 |
| 把一组 skill + 工具打包分发 | plugin | 给团队或市场分发的整套能力包。 |
| 看当前有哪些 skill | /skills | 浏览并选择已加载的 skill。 |
经验判断：如果流程需要“步骤 + 约束 + 示例 + 可能的脚本”，就做成 skill；如果只是一句长期生效的策略，写进 AGENTS.md；如果只用一次，直接说就行。（注意：Codex 早先独立的自定义 prompt 功能已被弃用，可复用指令现在改用 skill。）
常见的 skill 类型
| 类型 | 说明 | 例子 |
|---|---|---|
| 内置 / 系统 | 随 Codex 或宿主环境自带，通常只读 | imagegen、文档查询类 skill |
| 插件 skill | 来自已启用的插件，常伴随 MCP 工具或产物工作流 | 浏览器、文档、演示文稿、表格 |
| 用户 skill | 放在 $HOME/.agents/skills/ 里的自定义工作流 | release-check、seo-audit |
| 项目 skill | 仓库范围，随代码提交、团队共享 | repo-qa、design-system-review |
一个 skill 在磁盘上长什么样
release-check/
SKILL.md
scripts/
check-links.mjs
templates/
pr-description.md
references/
release-policy.md一个最小的 SKILL.md：
---
name: release-check
description: Use when the user asks to prepare a release, verify the changelog or version, run pre-release tests, or produce a go/no-go checklist.
---
# Release Check
1. Read AGENTS.md and package scripts.
2. Inspect git status and changed files.
3. Run the repo's fastest relevant tests first.
4. Verify changelog, version, and migration notes.
5. Produce a release checklist with blockers first.要点：
name要短、稳定、好记，它就是你$后面要打的那个词。description决定 Codex 会不会自动选中这个 skill，所以要把触发词放在前面、把适用范围写清楚，别用“强大”“自动化”这类广告词。- 正文写清执行步骤、约束和输出格式。
- 把可运行的代码放
scripts/，把要填的模板放templates/，把较长的策略放references/，让主体SKILL.md保持精简。
如何调用一个 skill
| 调用方式 | 示例 | 适合场景 |
|---|---|---|
$ 显式点名 | Use $release-check to prepare this PR. | 你明确知道 skill 名字。 |
从 /skills 选 | 输入 /skills 再选 | 忘了名字或想先看看有哪些。 |
| 自然语言触发 | “帮我做发布前检查。” | description 写得够清楚，能被自动选中。 |
| 结合文件 | Use $seo-audit on these MDX files. | skill 需要检查具体文件。 |
| 结合工具 | Use $browser to inspect localhost:4321. | skill 背后需要浏览器、文档或表格工具。 |
一个稳妥的调用写法，是把范围和输出都讲明：
Use $release-check on the current repo.
Scope: changed files only.
Output: blockers first, then commands run, then remaining risks.
Do not commit unless I ask.对应的中文写法：
使用 $release-check 检查当前仓库。
范围：只看本次改动的文件。
输出：先列阻塞问题，再列已运行的命令，最后列剩余风险。
不要提交，除非我明确要求。怎么写一个 Codex 真会触发的 description
description 是最关键的一个字段，因为自动选择就是靠它匹配的。要写触发条件，而不是写宣传语。
| 差 | 好 |
|---|---|
Helps with releases. | Use when the user asks to prepare a release, verify changelog/version, run pre-release tests, or produce a go/no-go checklist. |
SEO skill. | Use for auditing MDX article metadata, internal links, canonical slugs, hreflang, thin sections, and sitemap readiness. |
Documents. | Use when creating, editing, redlining, or visually verifying .docx documents. |
好的 description 要包含触发词、任务边界和预期的产出类型。
skill 设计清单
| 检查项 | skill 里要回答的问题 |
|---|---|
| 触发 | Codex 什么时候该用它？ |
| 边界 | 哪些东西绝对不能碰？ |
| 输入 | 需要哪些文件、链接、数据？ |
| 输出 | 最终结果应该长什么样？ |
| 工具 | 要不要浏览器、表格、文档渲染或 MCP 工具？ |
| 验证 | 怎么确认它正确完成了？ |
| 风险 | 是否可能改文件、跑命令、花钱、泄露数据？ |
什么不该做成 skill
- 只用一次、不会重复的任务。
- 一句话的偏好，比如“回答短一点”（这类应放进
AGENTS.md或直接写在提示里）。 - 会频繁变化的临时业务数据。
- 私密 token、密码或客户资料。
- 需要人来拍板的伦理、法律、财务等高风险最终决策。
怎么和团队共享 skill
因为项目 skill 放在 $REPO_ROOT/.agents/skills/，它会像普通代码一样被提交和审查。那就按代码的方式来管理：
| 做法 | 为什么重要 |
|---|---|
| 版本化 | 在 PR 里 review skill 改动；一份糟糕的 SKILL.md 会变成所有人的糟糕指令。 |
| 指定 owner | 每个 skill 都要有维护人。 |
| 写清禁区 | 明确这个 skill 不能改哪些目录、不能跑哪些命令。 |
| 先只读 | 先发只做审计的版本，之后再允许改文件。 |
| 留示例 | 在正文里放 2-3 个真实调用示例。 |
| 定期清理 | 过期的 skill 比没有 skill 更糟。 |
要把一组 skill 分发到单个仓库之外，或者跟工具一起打包，就做成 plugin。截至 2026 年 6 月，Codex CLI 提供了插件管理命令，比如 codex plugin list --json，还有插件市场，因此内部的 skill 包可以像依赖一样发布和更新。
常见问题 / FAQ
为什么 /skills 里看不到我的 skill？
多半是它在 Codex 读不到的路径。确认文件名就是 SKILL.md（一字不差），并且位于受支持的范围里，比如 $HOME/.agents/skills/你的-skill/SKILL.md 或 $REPO_ROOT/.agents/skills/...。如果是插件提供的 skill，确认该插件在当前会话已启用。
skill 会自己运行命令吗？
skill 只是指令加资源，不是授权。Codex 是否真的执行某条命令，仍取决于你的 approval policy（/permissions）和你的请求。skill 不能绕过审批。
一定要用 $skill-name 吗？
不一定。$skill-name 是强制指定某个 skill，/skills 打开选择器，写清楚的 description 则让 Codex 根据普通措辞自动选。想要确定性时就用 $。
skill 和 prompt library 有什么区别？ prompt 是文本，skill 是可加载的工作流包：指令加上可选的脚本、模板、参考资料和工具指引，而且有渐进式加载，只在用到时才占上下文。
Codex skills 和 Claude Code skills 一样吗？
概念相似（都是放在 SKILL.md 里的按需工作流指令），Claude Code 用的格式也类似。但查找路径、slash 命令和插件系统不同。Codex 在 .agents/skills/ 里找；别想当然地把 Claude Code 的目录结构或命令照搬过来。
要不要把旧的自定义 prompt 迁成 skill？ 要。Codex 独立的自定义 prompt 功能已被弃用，可复用指令现在应该以 skill 形式存在，Codex 既能显式调用也能自动调用。
值得先做的几个 skill
| Skill | 作用 |
|---|---|
repo-tour | 新仓库导览：架构、关键目录、测试入口。 |
bug-audit | 改代码前先顺着调用链查 bug。 |
release-check | 发布前测试、版本、changelog 和风险清单。 |
seo-mdx-audit | 内容站 MDX 的 metadata、内链、slug 和薄内容检查。 |
test-generation | 先读现有测试风格，再补最小测试。 |
migration-plan | 大改之前先输出阶段计划和回滚点。 |
想了解更多细节，可以参考 OpenAI 官方的 Agent Skills 文档 和 Codex slash 命令参考，里面有当前的字段名和命令列表。