Codex Skills 安装后不触发？检查目录与描述

Codex Skills 已安装却不触发，先检查它是否位于扫描目录、SKILL.md 是否有完整的 name 和 description，再用显式调用验证。多数问题是“技能没有被发现”或“描述没有匹配任务”。

目录必须放对，文件名不能变

仓库专用技能放在：

$REPO_ROOT/.agents/skills/skill-name/SKILL.md

所有项目通用的个人技能放在：

~/.agents/skills/skill-name/SKILL.md

Codex 从当前目录向仓库根目录扫描 .agents/skills。技能放在仓库外的相邻目录，或缺少独立技能文件夹，都可能无法发现。

description 决定何时触发

最小可用文件应包含 YAML 头信息：

---
name: release-checker
description: Use when checking whether a web project is ready to release, including build, tests and rollback verification.
---

Follow the project release checklist and report every failed check.

name 要稳定且不要重名；description 要写清用户目标、触发条件和边界。只写“一个很好用的发布技能”没有可匹配的任务信号，关键场景应放在描述前部。

显式调用可分清两类问题

在 CLI 或 IDE 扩展中输入 /skills 查看列表，也可以键入 $ 选择技能。若 $release-checker 能被选中并执行，说明安装正常，需要优化的是 description；若列表里没有它，就检查目录、文件名和 YAML 格式。

技能更新通常会自动发现；没有刷新时重启 Codex。技能过多时，初始列表受上下文预算限制，描述可能被缩短，部分技能会被省略并出现提示。此时应停用无关技能或显式调用所需技能。

相同 name 的技能不会自动合并。先在 /skills 中确认路径，保留正确版本再测试。