Claude Code和Codex装Skill为何选错工具？-TKMiss Notes

Agent 如果在安装 Skill 后更容易选错工具，先把问题分成三层：Skill 是否真正进入当前客户端的清单，清单是否因预算被截断，完整清单下是否仍存在描述冲突或 MCP 工具竞争。不要一上来就改描述或重装插件。Claude Code 侧优先查看 /context 和 /skill-doctor，再做去重、停用闲置 Skill 和描述调整；Skill 完全没有出现时，转去检查插件加载链。相关命令、最低版本和 skillOverrides 设置都应以当前版本官方文档为准。

掘金热榜上的《装了太多 Skill 后 AI 开始「装瞎」？实测 Claude Code 与 Codex 的技能清单预算机制》描述了一个很容易误判的问题：Skill 装得越多，Agent 反而越容易选错工具。 Codex 的症状是技能 metadata 列表过长后被截断，后半部分 Skill 无法参与选择；Claude Code 则可能仍显示 Skill 名称，但描述里的触发关键词已经被裁掉，导致 Agent 知道“有这么个技能”，却不知道什么时候该用。

先分清没加载和选错

“磁盘上有 SKILL.md”不等于“当前客户端已经加载了它”。比较可靠的排查方式，是先看客户端实际呈现的 Skill 清单，再把清单与磁盘目录对应起来。Claude Code、Codex 和 VSCode 的技能目录及发现规则并不完全相同，不能拿另一个平台的路径推断加载结果。

观察到的现象	更可能的问题层	下一步
Skill 完全不在清单里	发现范围或插件加载	查插件市场源、安装与启用状态
清单尾部缺失，诊断提示 metadata 截断	技能目录预算	缩短描述、归档低频 Skill 后复测
Skill 名称和描述完整，但选错 Skill	路由冲突	检查职责重叠、模糊触发词
Skill 已正确触发，但目标工具不存在	MCP 或工具注册	检查 server、工具清单与权限

这里最容易混淆的是最后两种情况。Skill 解决的是“怎么做”，MCP 解决的是“能连接和调用什么”；如果 Skill 已经触发，随后却调用了错误的数据库或 API 工具，继续压缩 Skill 描述通常不会解决问题。

盘点实际加载的 Skill

先盘点当前客户端能够识别到的技能根目录。下面的命令适用于 Linux，/path/to/skills 需要替换成实际目录：

find /path/to/skills -type f -name SKILL.md -print
find /path/to/skills -type f -name SKILL.md -exec sha256sum {} + | sort

macOS 可将 sha256sum 换成 shasum -a 256：

find /path/to/skills -type f -name SKILL.md -exec shasum -a 256 {} + | sort

相同哈希只能证明文件内容完全一致，名称不同但职责相同的 Skill 仍然需要人工检查。为每个 Skill 记录下面这些信息：

Skill	描述字符数	触发条件	是否调用过	来源	处理方式
`database-query`	待填写	查询已有记录	是/否/未知	仓库或插件	保留、改写或归档

“是否调用过”以真实日志或诊断结果为准，取不到就标成未知，不要凭印象填写。热点文章汇总的案例中，磁盘上曾有 570 个 SKILL.md，去重后仍有 402 个，仅名称和描述就占 92,006 个字符，约合 45,634 token。这个数字只能说明目录膨胀的量级，不能当作每次请求的固定成本。

看真实上下文预算

在 Claude Code 交互会话中，先运行：

/context
/skill-doctor

据热点文章对 Claude Code 文档的转述，/context 中的 Skills 一行可以反映预算生效后的实际占用；/skill-doctor 用于找出从未调用过的技能，文中标注其最低版本为 v2.1.252。这两个命令和行为可能随版本调整，当前终端不支持时，应先查现版官方文档，不要照搬旧截图或旧教程中的配置。

Claude Code 与 Codex 的异常表现并不完全相同。同一份资料称，Claude Code 的技能目录存在与模型上下文窗口相关的字符预算，溢出后可能优先裁掉低频 Skill 的描述，于是名称还在，但用于判断触发条件的关键词消失；Codex 则可能在 metadata 列表过长时直接截断。这些是资料对文档的转述，不能当作永久不变的内部实现。

还要区分“目录常驻”和“正文常驻”。按资料对 Claude Code 和 Codex 的描述，两者通常先把 Skill 的名称和描述放进可见目录，正文再按需读取；不能据此推断它们当前版本都会把所有 Skill 正文常驻提示词。 Codex 侧也应以当前诊断输出中的 metadata 列表为准，现有资料没有提供可跨版本复制的统一清单命令。

如果清单里的 Skill 数量明显少于磁盘扫描结果，优先怀疑发现范围、插件启用状态或列表预算，而不是描述写得不够好。

找出互相抢路由的描述

Skill 清单完整，只说明候选都进入了模型视野，并不代表模型能准确区分它们。数量增加后出现的误选，更常见的解释是无关描述挤占决策空间、多个 Skill 职责重叠，以及触发条件没有写出边界，而不是模型能力突然下降。

例如，下面三个描述几乎会互相竞争：

处理数据库问题
查询数据库并返回结果
根据用户需求访问数据库

更清楚的拆法是：

只读查询：仅在用户明确要求查询已有数据库记录时使用；不用于修改表结构或写入数据。
结构迁移：用于设计并执行数据库 schema 变更；普通只读查询不使用。
导出报表：将已有查询结果整理为 CSV 或报表，不负责连接其他外部数据源。

改写时至少说清三件事：这个 Skill 负责什么动作，什么请求应该触发它，什么场景明确不应触发它。描述不必塞入全部操作步骤，但路由边界必须能在不读取正文的情况下被判断。

如果两个 Skill 分别承担“调用接口”和“整理接口文档”，还要检查是否在描述中混写了相同动词，例如大量使用“调用”“处理”“执行”。这种重叠比单纯增加 Skill 数量更容易造成误选。

先降级闲置 Skill

先用 /skill-doctor 找出长期没有调用记录的项目，再按“停用或归档、缩短描述、只保留名称”的顺序降低目录负担。根据资料转述，Claude Code 设置中的 skillOverrides 可以把低频 Skill 降为 name-only，减少完整描述在目录中的长期占用。

完整配置结构和可选值需要以当前版本文档为准。现有资料没有提供稳定的配置 schema，因此不应从旧文章复制 JSON。使用 name-only 也有代价：名称能保留，但触发辨识度可能下降，原本很少触发的 Skill 尤其需要回归验证。

处理闲置 Skill 时，可按下面的方式权衡：

处理方式	优点	需要承担的副作用
停用或移出发现目录	降载最明显	罕见任务可能失去能力，需要时再恢复
缩短描述	保留主要路由信息	边界仍要靠复测确认
降为 `name-only`	保留名称索引	触发词变少，更容易漏选
删除文件	目录最干净	缺少回滚路径，不适合作为第一步

Codex 侧应优先使用当前版本公开的禁用或忽略机制。如果所用版本没有相应开关，可以在完整备份后，临时把文件移出实际发现目录再验证；不要直接删除，也不要假定 Claude Code 的 skillOverrides 对 Codex 同样有效。

MCP 工具另行排查

如果 Skill 已经稳定触发，Agent 却在多个数据库、API 或部署工具之间选错，问题已经越过 Skill 路由层，进入了工具选择层。Skill 可以规定查询流程，却不能代替 MCP server 注册连接能力；外部数据库和第三方 API 如果只写进 Skill 描述，最终调用仍需要可用的工具入口。

检查当前 MCP server 暴露了哪些工具，以及它们的名称和描述是否重叠。热点文章转述的社区经验是，单个 server 暴露约 20 至 40 个工具时，可能出现明显的可靠性问题；达到约 60 至 80 个时风险更高。这只能作为排查线索，不是适用于所有模型的通用阈值。

如果同一 server 混合了数据库查询、文件管理、消息发送和部署操作，可以按业务边界拆分，并删除重复或职责不清的工具描述。反过来，如果 Skill 被禁用后目标工具立即消失，应查 MCP 配置和 server 启动状态，而不是继续修改 Skill 正文。

清单缺项查插件链

Skill 完全不出现在清单中时，应当转入插件加载排查。插件、Skill 与承载它们的运行框架属于不同层次：把 SKILL.md 放到磁盘上，并不等于对应插件已经安装、启用并完成加载。

一份插件排障资料描述的完整链路包括添加市场源、拉取仓库、安装或启用插件，以及重启后加载。错误中出现 harness failed to load plugins 或 entries did not activate 时，应检查插件目录、市场源配置和启用状态；仓库中的 .claude-plugin/marketplace.json 可以作为市场源入口之一进行核验。

这条链路中断时，缩短 Skill 描述不会让缺失项重新出现。排查时还要区分用户级、项目级和插件级来源，避免在错误的安装范围内反复复制文件。