一个项目里积累多个 Skills 后，最常见的抱怨往往是“模型怎么老用错”“为什么这个 Skill 总抢别人的活”。但大多数所谓冲突，并不是神秘的随机性，而是几个非常具体的问题：名字太像、description 重叠、作用域放错、来源层级没搞清、旧版本没有禁用。只要你把这些层面拆开查，Skill 冲突通常比想象中更容易定位。
核心结论：先分平台，再按名字、描述、作用域、禁用状态排查
这件事最重要的一步，是不要拿 Codex 的规则去猜 Claude Code，也不要反过来。OpenAI 当前 Build skills 文档说明：Codex 里如果两个 Skill 同名，系统不会自动合并，两者都可能出现。Claude Code 官方文档则明确写了层级覆盖关系：企业级覆盖个人级，个人级覆盖项目级，而插件 Skill 带 plugin-name:skill-name 命名空间，用来避免直接冲突。规则不同，排查方法自然也不同。
适用人群与准备条件
这篇文章适合已经在同一仓库、同一团队或同一台机器上积累了多个 Skill 的用户，也适合从个人试验走向团队治理的人。准备条件是：你能定位 Skill 所在目录，知道自己当前是在 Codex 还是 Claude Code，并且愿意先按官方规则查路径和配置，而不是凭印象猜优先级。
先判断属于哪一类冲突
- 触发冲突：两个 Skill 的 description 都覆盖同一类任务。
- 命名冲突：不同目录或不同层级出现同名 Skill。
- 作用域冲突：项目 Skill 放进全局，或个人 Skill 抢了团队 Skill 的活。
- 指令冲突：两个 Skill 没同名，但规则互相矛盾。
只有先分清类型，后面的修复动作才不会绕圈。
实际使用示例一：Codex 排查示例
假设你在仓库根目录和子模块里都放了一个同名 review Skill：
repo/.agents/skills/review/SKILL.md
repo/apps/web/.agents/skills/review/SKILL.md按官方 Build skills 文档，这两个同名 Skill 不会自动合并，都可能出现在可选列表里。此时最稳的排查顺序是：先把名字改得更具体，例如 repo-review 和 web-review；如果暂时不想删旧版本，就在 ~/.codex/config.toml 里先禁用其中一个：
[[skills.config]]
path = "/Users/alex/project/.agents/skills/review/SKILL.md"
enabled = false改完后重启 Codex，再确认是否还会误选。
实际使用示例二：Claude Code 排查示例
Claude Code 需要先查是不是上层目录覆盖了项目目录。例如你同时存在：
~/.claude/skills/review/SKILL.md
project/.claude/skills/review/SKILL.md
plugin-x/skills/review/SKILL.md官方文档说明，个人级会覆盖项目级，而插件 Skill 会变成 plugin-x:review 这种命名空间，不会和普通层级直接冲突。另一个常见误区是把文件访问配置误当成 Skill 发现机制。下面这个 settings.json 片段只会放开目录访问，不会加载其中的 Skills：
{
"permissions": {
"additionalDirectories": ["../shared"]
}
}Claude 官方文档明确写到：permissions.additionalDirectories 只授予文件访问，不会加载 Skills；只有 --add-dir 或 /add-dir 下的 .claude/skills/ 才会自动被发现。如果你以为“目录已经加进来了，为什么 Skill 还没出现”，问题通常就在这里。
可直接照做的排查顺序
- 先确认平台：这是 Codex 还是 Claude Code。
- 列出所有同名或近似 description 的 Skill 目录。
- 查作用域：仓库、用户、企业、插件，分别是谁生效。
- 对 Codex 用
enabled = false临时停用，对 Claude 先确认是否被上层覆盖。 - 修复后再缩窄 description，补上“什么时候不要触发”。
常见错误、限制和避坑
- 给不同流程起几乎一样的名字，自己过一周都分不清。
- description 只有正向触发语，没有反向边界。
- 旧版本既不删除也不禁用，结果新旧并存。
- 把 Claude 的覆盖规则和 Codex 的并存规则想当然混用。
最后建议：先小范围试运行，再放大
无论你现在看到的是概念解释、目录结构、安装方法还是排查思路，真正落地时都建议先选一个低风险、小范围、可回滚的任务试运行。先把输入样本、执行步骤、关键命令、最终结果和失败情况记录下来，再回头看哪些规则是稳定的、哪些描述还太宽、哪些动作应该交给脚本或工具。这样做的好处是，你不会因为第一次就追求完整而把流程做得过重，也不会在边界还没摸清时过早共享给团队。
如果试运行期间仍然需要频繁口头补充，说明这部分知识还没有真正沉淀进正文。等一次小范围试运行已经能稳定复现同样结果，再把它扩展到更多目录、更多同事或更多系统，并补上禁用、回滚、验收和来源更新规则。对 Skill、MCP 和自动化来说，最省时间的路线通常不是一开始就做大，而是先做小、做稳、保留证据，再逐步放权。
相关阅读
总结
多个 Skills 冲突时，不要先怪模型，先按平台规则查名字、description、作用域和禁用状态。把这些边界收紧后，大多数冲突都会从“玄学问题”变成可定位、可修复的配置问题。
