Codex Skill不响应是因配置错误而非技能损坏，需依次检查API密钥、Skill名称拼写、文件结构（SKILL.md frontmatter无BOM且description加引号、skill.yaml合法）、缓存清理及路径冲突。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Codex Skill装完后输入指令没反应、不执行流程、输出还是普通代码，不是技能坏了，而是配置环节卡在某个具体位置。
先确认 Codex 本身是否正常工作
打开终端或 Desktop，直接输入一句简单提问，比如“你好”，看是否能获得回复。如果连基础响应都没有，说明问题不在 Skill，而在 API Key、模型配置或客户端启动状态。【不要跳过这步直接查 Skill】
若无响应，立刻检查 ~/.codex/auth.json 是否只含 {"OPENAI_API_KEY":"sk-xxx"} 一行，且 sk-xxx 是你从 OpenAI 控制台复制的、分组为 codex 的有效密钥。
检查 Skill 名称是否拼写准确
方法一：对照官方清单核对名称
正确名称必须全小写、用短横线连接，例如：gh-fix-ci、security-threat-model、notion-spec-to-implementation。
常见错误：把 playwright 写成 playwrite，把 figma-implement-design 写成 figma implement design 或 figma_implement_design。名称错一个字符，Codex 就完全识别不了。
方法二：用调试命令验证加载状态
在项目根目录下运行：codex --debug --skills-dir ./skills，观察日志中是否出现 loaded skill: gh-fix-ci 这类行。没有出现，说明路径或名称任一环节失败。
验证 Skill 文件结构是否合规
第一步：进入你的 Skill 所在文件夹，比如 ~/.codex/skills/playwright/
通过本地 Codex 或 OpenClaw OAuth 凭证直接调用 ChatGPT/Codex Responses 的 image_generation 工具来生成或编辑光栅图像，然后保存
第二步：确认该目录下存在 SKILL.md，且文件开头的 frontmatter 区块（--- 开头和结尾之间）不含 UTF-8 BOM 头（用 VS Code 或 Sublime Text 以 UTF-8 无 BOM 格式另存一次即可清除）。
第三步：检查 SKILL.md 中的 description 字段——如果里面写了 Triggers: /playwright 这类带冒号的内容，YAML 解析器会把它当成键值对解析失败，导致整个 frontmatter 加载中断。【必须给 description 值加英文双引号包裹，如 description: "Triggers: /playwright"】
第四步：确认 skill.yaml 存在于同一级目录，且内容里有合法的 name 和 triggers 字段，不能缺失或为空。
强制重载 Skill 路径并重启
Windows 用户请关闭所有 Codex 窗口，包括后台进程（任务管理器中结束 codex.exe 及相关子进程）；macOS/Linux 用户执行：killall codex。
删除缓存与索引文件：rm -rf ~/.codex/cache && rm -f ~/.codex/index.json。这一步会让 Codex 下次启动时重建完整插件索引，3–8 秒内勿操作界面。
重新打开 Codex，如果是 CLI 模式，用 codex --skills-dir ~/.codex/skills 启动；如果是 Desktop，确保设置中 Skills 路径指向 ~/.codex/skills（Windows 为 C:\Users\用户名\.codex\skills）。
排查多路径冲突与重复注册
运行 /debug skills，查看输出中是否有同名 Skill 出现在多个路径下，例如 skills/rewrite 和 skills/code-rewrite 同时 active。
若有重复，进入 ~/.codex/skills/ 目录，用 ls -la 列出所有子文件夹，临时将疑似冗余的文件夹重命名为 xxx.disabled，再重启 Codex 测试。
特别注意：Codex Desktop 和 CLI 默认读取路径可能不同。Desktop 有时会优先读取 ~/.agents/skills/，而 CLI 读 ~/.codex/skills/，两个目录都存在同名 Skill 时必然冲突。
