Skill 发现、配置与排障

Skill 已经写好却没有出现在选择器时，先检查它位于哪个发现范围，再检查元数据和调用策略。基本编写格式见Skills。

本地加载位置

Codex 从当前工作目录向仓库根逐级检查 .agents/skills。因此模块目录、父目录和仓库根都能提供当前项目的 Skill。

支持链接到其他目录的符号链接 Skill 文件夹。两个 Skill 的 name 相同时不会合并，选择器中可能同时出现。要区分它们，应核查来源路径，而不是认为后一份覆盖前一份。

禁用但保留文件

在用户 ~/.codex/config.toml 中配置：

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

把路径替换成实际文件，并在改配置后重启 Codex。普通 Skill 文件变更通常会自动检测；更新仍未出现时再重启。

显式与隐式调用

CLI 和 IDE 可通过 /skills 或 $skill-name 显式调用。隐式匹配依赖 description，所以应把核心任务和触发边界放在描述前面。

可在 Skill 的 agents/openai.yaml 中关闭隐式调用：

policy:
  allow_implicit_invocation: false

默认 true。false 不会禁止显式调用；用户仍可明确选择这个 Skill。该文件也支持 interface 展示元数据以及 dependencies.tools 中的 MCP 依赖声明。

按症状排查

• 找不到 Skill：检查目录、SKILL.md 中必填的 name/description，以及是否被 skills.config 禁用。
• 不自动调用：检查 description 是否与任务匹配，以及 allow_implicit_invocation 是否关闭。
• 安装很多 Skill 后部分不出现在初始上下文：初始列表有上下文预算；Codex 会先缩短描述，大量 Skill 时可能省略条目并提示。
• 团队想统一安装：本地发现目录用于创作和仓库工作流，跨仓库分发可用插件。