Codex技能UI不显示需按路径、格式、签名、缓存四层顺序排查:确认skills目录下子目录名全小写+短横线且SKILL.md位于根层;清除SKILL.md的UTF-8 BOM;Mac用户须先清除quarantine属性再重签名Codex.app;最后执行codexctl cache clear与reload并重启客户端。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

Codex技能安装后在UI中不显示、执行时提示“未找到可用技能”或命令面板搜不到对应指令,需按路径、格式、签名、缓存四层顺序排查,跳过任一环节都可能白忙一场。
确认Skill是否被正确识别到路径
第一步:打开终端,进入你当前使用的项目根目录(不是~/.codex,也不是随便一个空文件夹)。
第二步:执行 dir skills(Windows)或 ls -la skills(Mac/Linux),确认输出中存在子目录,且每个子目录名全为小写英文+短横线,例如 playwright、gh-fix-ci。
第三步:进入任一Skill子目录,检查是否存在 SKILL.md 文件,且该文件必须位于目录第一层——不能放在 skills/playwright/docs/SKILL.md,只能是 skills/playwright/SKILL.md。
【文件夹名含中文、空格或大写字母,Codex会直接跳过整个目录】
检查SKILL.md文件头是否带BOM
用VS Code或Notepad++打开SKILL.md,点击右下角编码格式,若显示“UTF-8 with BOM”,立刻另存为“UTF-8 without BOM”。
这一步极隐蔽:肉眼完全看不出异常,但Codex加载器读取字节流时,第一个字符必须是 -(YAML分隔符),而BOM(EF BB BF)会把它顶到第二位,导致frontmatter解析失败,整个Skill被静默丢弃。
保存后,用命令行验证:codexctl validate ./skills/playwright。若返回 Skill is valid!,说明BOM已清除。
修复Mac签名与隔离属性(仅Mac用户)
方法一:清除隔离属性(必须先做)
打开Terminal,执行:sudo xattr -rd com.apple.quarantine /Applications/Codex.app
方法二:强制重新签名
执行:sudo codesign --force --deep --sign - /Applications/Codex.app,输入开机密码(无光标反馈,输完直接回车)。
验证签名是否生效:codesign -dv /Applications/Codex.app,输出中出现 designated => ... 即成功。
不执行方法一,方法二无效;不重签,Codex无法加载本地修改的Skill资源。
清理CLI缓存并重启服务
执行:codexctl cache clear,等待提示“Cache cleared successfully”。
接着执行:codexctl reload,该命令会强制重建插件索引和superpowers模块映射关系。
最后关闭所有Codex Desktop窗口,再双击图标启动——不要用旧窗口热重载,否则仍走旧缓存路径。
【Mac更新后插件灰显、补全失效,90%由这一步残留缓存引发】











