Codex Skills 不显示、不触发？从加载目录到显式调用逐步排查

你已经创建或安装了 Skill，但选择器里找不到，或者 Codex 完成任务时没有使用它。不要先把整个流程重新写一遍：未发现技能、技能被禁用、已发现但未触发，以及调用后的执行失败，是不同问题。

本文以本地 Codex CLI 的 Skill 为例，解决 codex skills not showing、codex skills not working 与技能不触发的排查需求。如何设计流程仍参考 Skills 中文入门，这里只处理已经准备好技能后的发现、选择和验证。

先分清卡在哪一步

现象	先检查	验证目标
/skills 里找不到技能	当前目录、保存位置、文件与元数据	当前环境能发现这个技能
文件存在但技能被禁用	skills.config、客户端或组织限制	确认禁用来源和是否允许启用
显式调用有效，普通描述需求时没调用	description、隐式调用策略、需求是否匹配	典型需求能匹配，边界需求不会被强行套用
选中了技能，但脚本、依赖或工具报错	已选用的文件、资源路径和外部能力	定位执行失败的具体步骤
只在某个项目或客户端找不到	启动目录、主机与安装范围	比较的是同一环境下的同一份技能

在 CLI 的会话输入框中运行 /skills，或输入 $ 使用技能选择入口。IDE 扩展也支持技能选择；桌面应用可在 Skills 页面查看。选择器能找到技能是发现环节的证据，并不保证每条任务都会自动选用它。

1. 检查当前目录与本地技能位置

适用现象：技能文件在磁盘上，但当前项目找不到。

先确认你在哪个环境启动 Codex。macOS/Linux 用 pwd，PowerShell 用 Get-Location；WSL、容器或远程主机各有自己的目录和用户环境。

官方列出的本地发现位置包括：

范围	位置	适合放什么
项目	从当前目录到仓库根目录各层的 .agents/skills	当前项目或子项目的流程
用户	~/.agents/skills	自己跨项目复用的技能
管理员	/etc/codex/skills	管理员提供的共享技能
系统	Codex 内置	随产品提供的技能

一个本地技能通常有这样的目录结构：

your-project/
  .agents/
    skills/
      my-skill/
        SKILL.md
        scripts/
        references/

其中 SKILL.md 必需，其余目录按需要提供。如果从仓库根目录启动，不能假设只放在某个子项目下的 .agents/skills 就会按“从当前目录向上”的发现路径被找到。

操作与验证： 对照保存位置和当前目录，从该技能适用的目录新开 CLI 会话，再查看 /skills。官方支持符号链接目录，但仍要确认链接目标存在且可访问。

本地 Skill 目录与插件分发是不同入口。通过插件安装的技能应检查对应插件是否在当前客户端、账号或工作区可用；不要只看本地独立目录就认定插件安装失败。在 ChatGPT 网页上使用插件，也不能靠把文件放进自己电脑的目录来完成安装。

2. 核对 SKILL.md 的名称、元数据与可读性

适用现象：位置看起来正确，仍未发现或名称与预期不同。

检查文件确实是技能目录里的 SKILL.md，没有误保存成 SKILL.md.txt；文件可读且不是空文件。开头应有 YAML 元数据，并包含 name 和 description。例如：

---
name: repo-review
description: 当用户要求检查当前仓库的变更时使用，输出有文件依据的审查结果。
---

这只是文件开头，实际文件还需包含可执行的技能指令。用 name 核对选择器中的名字；正式文件按官方格式显式填写这两个字段，不靠目录名猜测技能身份。

验证： 修正文件或元数据后，技能出现在当前环境的选择器中，名称与描述符合预期。Codex 会检测技能变动；更新仍未出现时，按官方建议重启 Codex，再检查一次，而不是连续重装。

如果出现多个同名技能，官方说明是不会合并，两份都可能出现在选择器中。确认选中的来源路径，不要根据固定的“四层覆盖优先级”猜测哪份一定生效。自己的本地技能可以使用不同名称帮助区分；不要顺手改写系统或管理员提供的文件。

3. 文件存在，但是否被单独禁用了？

适用现象：以前可用，现在不显示或不可选，且存在禁用设置。

官方支持在用户 config.toml 中用路径禁用某个技能，例如：

[[skills.config]]
path = "/absolute/path/to/my-skill/SKILL.md"
enabled = false

操作： 在实际生效的配置中查找指向目标技能的条目，核对路径与 enabled。这是禁用示例，不需要为了排查而添加它。若是你自己关闭的技能，并确认允许使用，可以仅纠正该条目的启用状态；组织限制或管理员禁用应由相应管理员确认。

验证： 修改用户配置后重启 Codex，再检查技能入口。状态仍没变化时，先定位配置加载问题，参考 config.toml 不生效排查。不要默认删除整个配置文件，也不要把所有技能一并打开。

4. 已发现但不触发：区分显式调用与隐式选择

适用现象：选择器能找到技能，描述需求后却没看到它被使用。

在 CLI 中通过 /skills 选择目标技能，或在会话输入框里用 $技能名 明确调用。不要把这段输入放到 shell 中：

$repo-review 请用这个技能检查当前仓库的变更，只给审查结果，不修改文件。

示例适用于已经存在且允许使用的 repo-review；调用自己的技能时替换为选择器显示的实际名称。

如何判断结果：

• 显式调用也失败：先核对选中的来源、禁用状态与具体执行错误。
• 显式调用成功，隐式描述需求时没调用：检查 description 是否准确匹配需求，以及是否允许隐式选择。
• 已调用，却在脚本或工具阶段失败：继续检查技能内的相对路径、依赖与所需连接，不重复修改触发描述。

agents/openai.yaml 可以配置：

policy:
  allow_implicit_invocation: false

这个设置禁止隐式选用；明确调用仍可使用。若技能本来只允许你手动调用，普通需求没有自动触发就是预期行为。若自己维护的技能需要自动选择，按实际用途调整策略与描述；不要为了一次没调用就扩大到“所有任务必须使用”。

描述应把最重要的使用场景放在前面，写清什么时候用、什么时候不用。隐式选择不是“出现某个关键词就保证调用”；更不能靠在描述里反复重复关键词提高可靠性。

5. 技能很多时，检查初始列表是否被省略

适用现象：路径、元数据与启用状态正确，技能数量很多，或会话中有技能列表预算警告。

官方说明中，Codex 初始会先提供技能的名称、描述和路径，而不是加载全部正文。大量技能可能导致描述被缩短，甚至部分技能从初始列表中省略；可通过 skills.max_context_tokens 配置列表预算，当前文档给出的上限是 10,000 tokens。

操作： 先看是否确有预算警告，再减少不相关技能、缩短冗长描述，或在允许的范围内调整预算。不要在没有此类证据时，把所有不触发都归因于上下文长度。

验证： 新会话中的警告和可发现范围符合预期，再测试典型需求。列表预算只作用于初始元数据；选中技能后仍会读取完整 SKILL.md，因此它与 AGENTS.md 指令截断 不是同一问题。

用只读小例子验证发现与触发

如果原技能会发帖、部署或修改文件，先用不产生这些操作的诊断示例。下面只适用于你有权编辑、已经确认可信的测试项目；也可以直接用现有技能的安全测试入口。

创建 .agents/skills/skill-check/SKILL.md：

---
name: skill-check
description: 当用户要求测试仓库目录核对流程是否可选用时使用，只输出诊断标记。
---

只回复 SKILL_CHECK_OK。
不要读取项目文件、运行命令或修改文件。

然后按顺序验证：

1. 发现： 从测试项目目录新开会话，在 /skills 中找 skill-check。找不到就回查目录、元数据、禁用项与警告。
2. 显式： 在输入框写 $skill-check 请执行这个只读诊断。。预期读取这份技能后输出 SKILL_CHECK_OK，没有项目写入或脚本调用。
3. 隐式： 再开一个新会话，输入“请测试仓库目录核对流程是否可选用，按对应流程输出诊断标记。”。新会话可以避免沿用上一轮已经出现的标记；观察是否选用同一来源的技能。
4. 边界： 用不相关需求，例如“解释 JavaScript 数组是什么”，检查它是否错误地套用目录诊断技能。

不要只靠标记或模型自述认定底层加载完全正确；结合选择器中的名称、来源路径及可观察的读取记录核对。显式通过而隐式失败，优先回查描述与隐式调用策略；诊断技能通过而原技能失败，继续定位原技能的脚本、资源和外部能力。

涉及模型回复的测试会使用相应额度，先用这种不修改项目的任务验证调用，再测试原技能的实际流程。

修复后确认这四件事

目标技能在正确项目和环境中可发现；启用状态与调用策略符合设计；典型任务能选中预期来源并完成；边界任务不会被不相关流程误触发。

仍失败时，准备 CLI 版本、执行环境、启动目录、技能路径、脱敏 name / description、是否显式调用、相关启用策略与具体错误。只提供必要片段，不上传带凭据的脚本、完整配置或工作资料。

如果真正的问题是长期仓库规则没有执行，继续看 AGENTS.md 不生效排查；依赖或命令运行失败则看 Codex 常见故障排查。