Codex 的 skill 放在哪、怎么被发现

很多人用 Codex 一段时间后，会卡在几个看似简单的问题上：

• 项目里想版本控制一套 skill，到底放哪个目录 Codex 才认？
• 在一个不是 Git 仓库的目录启动 Codex，放进子目录仓库的 skill 为什么没生效？
• 明明官方推荐 ~/.agents/skills，为什么老的 ~/.codex/skills 还能用？
• skill 已经被发现了，为什么 Codex 没有自动调用？

这些问题其实指向同一件事：Codex 如何发现和加载 skill，以及 skill 被发现后怎样触发。

如果你更关心三家工具对 skills 的横向支持差异，或者 CODEX_HOME 到底影响哪些东西，可以先看这两篇：

• Claude Code、Codex、OpenCode 对 Skills 的支持现状对比
• Codex 的 CODEX_HOME 是什么？会影响哪些目录和行为

如果你想配置独立模型、提示词和权限边界的专用代理，可以看单独拆出的 Codex Subagent 配置与使用指南。

先说结论

Codex 当前推荐的 skill 目录是：

对项目内 skill，Codex 会从当前工作目录开始，逐层向上扫描到 Git 仓库根目录。它不会从当前目录向下搜索子目录。

所以最重要的不是“skill 文件存在于电脑上的哪个地方”，而是：你从哪个目录启动 Codex，这个目录到仓库根之间有没有对应的 .agents/skills/。

核心概念：skill 到底是什么

一个 skill 是一套可以重复使用的任务说明。最简单的 skill 只有一个 SKILL.md，复杂一些的还可以带脚本、参考资料和模板：

1
2
3
4
5

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

SKILL.md 的 frontmatter 至少要有 name 和 description：

1
2
3
4
5
6
7
8

---
name: release-check
description: 检查版本号、变更记录、测试结果和 Git 状态，适用于准备发布或打标签前的核对。
---

# Release Check

按照项目规范完成发布前检查。

其中 description 不只是给人看的简介，它还会影响 Codex 能不能在合适的任务里自动选中这个 skill。

Codex 怎么发现项目里的 skill

官方当前的规则是：在 Git 仓库中启动 Codex 时，它会扫描从当前工作目录到仓库根目录之间，每一层的 .agents/skills/。

例如：

1
2
3
4
5
6

~/code/shop/                         ← Git 仓库根
├── .agents/skills/release-check/
└── services/
    ├── .agents/skills/api-test/
    └── order/
        └── .agents/skills/order-debug/

如果从 ~/code/shop/services/order/ 启动 Codex，能看到：

• order-debug：来自当前目录
• api-test：来自父目录 services/
• release-check：来自仓库根目录

如果从 ~/code/shop/ 启动，则只能看到仓库根这一层的 release-check，不会向下扫描 services/ 和 order/ 中的 skill。

这套机制允许同一个仓库按目录划分作用域：全仓库通用的 skill 放根目录，某个模块专用的 skill 放模块目录。

同名 skill 会不会覆盖

如果不同位置存在相同 name 的 skill，Codex 不会把它们合并成一个。它们可能同时出现在 skill 选择器里，因此不要依赖“离当前目录更近的自动覆盖更远的”这种假设。

团队维护多层 skill 时，最好直接使用不同且有辨识度的名称，例如 repo-release-check、order-api-test。

skill 被发现后，怎么被调用

目录扫描只解决“Codex 能不能看到它”，不代表每次任务都会加载完整的 SKILL.md。

Codex 有两种调用 skill 的方式：

如果你明确知道这次必须执行某个流程，显式点名最稳定。例如：

1

使用 $release-check 检查这个仓库是否可以发布。

如果希望 Codex 自动判断，就要把 description 写清楚。不要只写“处理发布任务”，而应该写出适用场景、动作和边界：

1

description: 检查版本号、变更记录、测试结果和 Git 状态，适用于准备发布、创建标签或生成发布说明之前。

为什么 Codex 不在一开始读取所有 SKILL.md

Codex 使用的是“渐进式披露”：

1. 初始只把 skill 的 name、description 和文件路径放进上下文。
2. 根据当前任务判断需要使用哪个 skill。
3. 选中后才读取对应的完整 SKILL.md，再按需打开引用文件或运行脚本。

这样可以避免安装几十个 skill 后，所有说明一次性挤占上下文。

官方还给初始 skill 列表设置了预算：最多占模型上下文窗口的 2%；如果无法确定上下文大小，则最多使用 8000 个字符。skill 太多时，Codex 会先缩短 description，数量继续增加时还可能省略部分 skill 并显示警告。

这会带来两个实际结论：

• description 的关键触发词应该尽量前置。
• 用户级目录不要长期堆放大量用途重复、描述模糊的 skill。

实际案例：几个容易踩的边界

案例一：在非 Git 目录启动，子目录才是 Git 仓库

假设目录结构是：

1
2

~/data/work/          ← 不是 Git 仓库，在这里启动 Codex
└── ai/               ← Git 仓库，里面有 .agents/skills/

在 ~/data/work/ 启动时：

• ~/data/work/.agents/skills/ 可以作为当前目录位置被检查。
• ~/data/work/ai/.agents/skills/ 不会被扫描，因为它在当前目录下面。
• 用户级、管理员级和系统级 skill 仍可正常加载。

想使用 ai/ 仓库的 skill，最直接的做法是进入该仓库再启动：

1
2

cd ~/data/work/ai
codex

也可以把需要跨仓库复用的 skill 移到 $HOME/.agents/skills/。

案例二：~/.codex/skills 为什么还能用

官方当前推荐的用户级目录是：

1

~/.agents/skills/

旧版本曾使用 $CODEX_HOME/skills，默认通常就是：

1

~/.codex/skills/

较新版本在迁移后仍可能兼容读取旧路径，所以老 skill 继续生效并不奇怪。但新建 skill 应优先放进 ~/.agents/skills/，避免继续依赖兼容路径。

如果希望把 skill 源文件放在自己维护的 Git 仓库里，也可以使用符号链接。Codex 支持扫描链接到其他位置的 skill 目录。

案例三：skill 存在，却没有自动触发

按下面的顺序排查：

1. 确认当前启动目录到仓库根之间能扫描到该 .agents/skills/。
2. 确认 SKILL.md frontmatter 中存在有效的 name 和 description。
3. 使用 $skill-name 显式调用，验证它是否已经被发现。
4. 如果显式调用正常、隐式调用不稳定，重写 description，补充任务关键词和适用边界。
5. 修改后没有立即出现时，重启 Codex 再检查。

常见问题与解决方案

想让某个 skill 只对一个子项目生效，怎么办

把它放在该子项目的 .agents/skills/ 中，并从该子项目或更深的目录启动 Codex。不要从仓库根启动后，期待 Codex 向下发现子项目 skill。

~/.codex/skills 要不要马上迁移

不需要因为旧路径当前仍能用就紧急迁移，但新建内容建议直接写到 ~/.agents/skills/。迁移时注意不要让新旧目录同时留下同名副本，否则选择器中可能出现两个同名 skill。

为什么我安装的 skill 太多后，有些不容易自动命中

初始 skill 列表有上下文预算。先合并用途重复的 skill，再把关键触发词放到 description 前面；对必须执行的流程，直接使用 $skill-name 显式调用。

skill 和 Subagent 是一回事吗

不是。skill 是可复用的工作流说明，核心文件是 SKILL.md；Subagent 是独立执行任务的代理线程，自定义配置使用 .codex/agents/*.toml。两者可以配合，但目录、生命周期和用途都不同。

总结

记住三件事就够了。

第一，目录位置：项目和用户级 skill 优先使用 .agents/skills/<name>/SKILL.md。

第二，发现方向：Codex 从当前工作目录向上扫描到 Git 仓库根，不会向下钻进子目录仓库或模块。

第三，加载方式：初始只暴露 name、description 和路径，选中后才读取完整说明；想提高隐式调用命中率，就把适用场景和触发词写进 description。

把这三点弄清楚，“skill 放哪、为什么没生效、为什么不自动触发、新旧路径怎么处理”基本就不会再绕。

写在最后

这篇只讨论 Skills。如果你需要的是“让一个独立代理并行探索代码、运行测试或做专项审查”，下一篇 Codex Subagent 配置与使用指南 会继续讲 .codex/agents/*.toml、并发上限、嵌套深度和任务拆分方法。

Codex 仍在快速迭代，本文基于 2026 年 7 月的官方文档整理。涉及旧路径兼容性时，升级 Codex 后仍建议以当前官方文档和本机实际加载结果为准。

参考资料：

• Agent Skills – Codex | OpenAI Developers
• openai/codex 源码：core-skills/src/loader.rs