### [多个Skills冲突时如何排查和调整](https://alyyhw.com/article/2081)

**Published:** 2026-07-13T04:44:58

**Author:** AI菜鸟网

**Excerpt:** 多个 Skill 同时存在时，问题通常不在“模型不听话”，而在命名、描述、优先级、作用域或禁用策略没有提前收好边界。

一个项目里积累多个 Skills 后，最常见的抱怨往往是“模型怎么老用错”“为什么这个 Skill 总抢别人的活”。但大多数所谓冲突，并不是神秘的随机性，而是几个非常具体的问题：名字太像、description 重叠、作用域放错、来源层级没搞清、旧版本没有禁用。只要你把这些层面拆开查，Skill 冲突通常比想象中更容易定位。

## 核心结论：先分平台，再按名字、描述、作用域、禁用状态排查

这件事最重要的一步，是不要拿 Codex 的规则去猜 Claude Code，也不要反过来。OpenAI 当前 Build skills 文档说明：Codex 里如果两个 Skill 同名，系统不会自动合并，两者都可能出现。Claude Code 官方文档则明确写了层级覆盖关系：企业级覆盖个人级，个人级覆盖项目级，而插件 Skill 带 `plugin-name:skill-name` 命名空间，用来避免直接冲突。规则不同，排查方法自然也不同。

## 适用人群与准备条件

这篇文章适合已经在同一仓库、同一团队或同一台机器上积累了多个 Skill 的用户，也适合从个人试验走向团队治理的人。准备条件是：你能定位 Skill 所在目录，知道自己当前是在 Codex 还是 Claude Code，并且愿意先按官方规则查路径和配置，而不是凭印象猜优先级。

## 先判断属于哪一类冲突

1.  触发冲突：两个 Skill 的 description 都覆盖同一类任务。
2.  命名冲突：不同目录或不同层级出现同名 Skill。
3.  作用域冲突：项目 Skill 放进全局，或个人 Skill 抢了团队 Skill 的活。
4.  指令冲突：两个 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 还没出现”，问题通常就在这里。

## 可直接照做的排查顺序

1.  先确认平台：这是 Codex 还是 Claude Code。
2.  列出所有同名或近似 description 的 Skill 目录。
3.  查作用域：仓库、用户、企业、插件，分别是谁生效。
4.  对 Codex 用 `enabled = false` 临时停用，对 Claude 先确认是否被上层覆盖。
5.  修复后再缩窄 description，补上“什么时候不要触发”。

## 常见错误、限制和避坑

-   给不同流程起几乎一样的名字，自己过一周都分不清。
-   description 只有正向触发语，没有反向边界。
-   旧版本既不删除也不禁用，结果新旧并存。
-   把 Claude 的覆盖规则和 Codex 的并存规则想当然混用。

## 最后建议：先小范围试运行，再放大

无论你现在看到的是概念解释、目录结构、安装方法还是排查思路，真正落地时都建议先选一个低风险、小范围、可回滚的任务试运行。先把输入样本、执行步骤、关键命令、最终结果和失败情况记录下来，再回头看哪些规则是稳定的、哪些描述还太宽、哪些动作应该交给脚本或工具。这样做的好处是，你不会因为第一次就追求完整而把流程做得过重，也不会在边界还没摸清时过早共享给团队。

如果试运行期间仍然需要频繁口头补充，说明这部分知识还没有真正沉淀进正文。等一次小范围试运行已经能稳定复现同样结果，再把它扩展到更多目录、更多同事或更多系统，并补上禁用、回滚、验收和来源更新规则。对 Skill、MCP 和自动化来说，最省时间的路线通常不是一开始就做大，而是先做小、做稳、保留证据，再逐步放权。

## 相关阅读

-   [一个高质量Skill应该包含哪些文件和说明](/skills-automation-02/)
-   [如何安装和管理Codex Skills](/skills-automation-03/)
-   [如何测试一个Skill是否真的可靠](/skills-automation-09/)

## 总结

多个 Skills 冲突时，不要先怪模型，先按平台规则查名字、description、作用域和禁用状态。把这些边界收紧后，大多数冲突都会从“玄学问题”变成可定位、可修复的配置问题。

**Tags:** Skills冲突, 优先级, 作用域, 自动化治理

**Categories:** AI编程, Skills与自动化

---