团队仓库根目录的 .agents/skills 里提交了一个叫 deploy 的 skill，自己 $HOME/.agents/skills 里也躺着一个早先写的 deploy，内容不一样。这种情况下敲 $deploy，Codex 会挑哪一份？下面的说法来自 OpenAI 的 Build skills 页面（这个链接会跳到 learn.chatgpt.com），对照的是 10 月的文档版本。
先跟站里另外两篇划个界：AGENTS.md 那篇讲的是每次启动都会读进去的规则文件，记忆那篇讲的是 Codex 从历史会话里攒下来的东西，skill 则是按需加载的一套工作流，平时只露个名字和描述，用到才读全文。三样东西在 Codex 里各走各的。
会去哪些目录找
文档里有张表，按范围分四类：
- 仓库级（REPO）：从启动 Codex 的当前目录开始，一直往上到仓库根，每一层的
.agents/skills都会扫。表里列了$CWD/.agents/skills、$CWD/../.agents/skills和$REPO_ROOT/.agents/skills三种位置，意思是某个子模块专用的放在子目录，全仓库通用的放在根目录。 - 用户级（USER）：
$HOME/.agents/skills，换到哪个仓库都能用。注意它在~/.agents下面，跟放config.toml的~/.codex不是同一个目录。 - 管理员级（ADMIN）：
/etc/codex/skills，适合机器或容器上统一给每个用户预装。 - 系统级（SYSTEM）：Codex 自带的，比如 skill-creator。
仓库级是从当前目录往上找，所以在哪个目录启动 Codex 会影响能看到哪些 skill。照这个说法，在仓库根目录启动时，某个子目录里的 .agents/skills 不在扫描路径上，要进到那个子目录再启动才会出现。碰到「同事说有这个 skill、我的列表里没有」，先看看两人是不是在不同目录下开的 Codex。
skill 目录用软链接也可以，扫描时会跟到链接目标。每个 skill 就是一个带 SKILL.md 的文件夹，SKILL.md 里必须有 name 和 description，后面说的同名指的就是这个 name 字段。
同名了怎么算
文档的意思是，两个 skill 的 name 一样时，Codex 不合并，两个都可能出现在 skill 选择列表里。
哪个优先，文档没写。没说离当前目录近的赢，也没说仓库级压过用户级。这一点跟 AGENTS.md 不一样，AGENTS.md 的文档明确写了从仓库根往下拼接，越靠近当前目录的越靠后、越算数。别把那套规则套到 skill 上。
既然没有覆盖规则，稳妥的办法就是别让它们同名：
- 把个人那份的
name改掉，比如加个后缀，调用时一眼能分清。 - 不想删文件的话，在
~/.codex/config.toml里加一段[[skills.config]]，path指向那份SKILL.md，写enabled = false，改完重启 Codex。 - 在 CLI 或 IDE 插件里敲
/skills看一下列表，确认现在实际能选到的是哪几个。
装多了描述会被截
Codex 一开始只把每个 skill 的名字、描述和文件路径放进上下文。这份初始列表默认最多占模型上下文窗口的 2%，拿不到窗口大小时按 8,000 字符算。skill 装多了，Codex 先缩短描述；再多，可能有一部分直接不进初始列表，同时给出警告。
想调大可以在 config 里设 skills.max_context_tokens，配置参考写的是正整数，上限 10000 token。这个预算只管初始列表，真选中某个 skill 时照样读完整的 SKILL.md。
所以 description 最好把触发场景和关键词写在最前面，被截短了也还能匹配上。
不想让它自己跳出来
隐式调用靠的是 description 匹配。有些 skill 只想手动用，可以在 skill 目录里加 agents/openai.yaml：
policy:
allow_implicit_invocation: false
这样 Codex 不会根据提示词自动选它，$skill名 显式调用还能用。
装官方整理的 skill 用 $skill-installer，比如 $skill-installer linear。新装或改过的 skill 一般会自动识别，没出来就重启一次。
和 plugin 的关系
文档的分法是：skill 是写工作流的格式，上面这些目录是给本地编写、本地发现用的；要给别人装、要把几个 skill 打包、或者要带上 MCP 连接器一起发，就做成 plugin。团队内部一个仓库用用，提交到 .agents/skills 就够了。
你们是把 skill 提交进仓库统一管，还是各自放 ~/.agents 里自己维护？同名的情况碰到过没有？