Codex Skill 怎么安装：目录结构、GitHub 下载与不生效排查

Skill 的核心不是“下载一个文件”，而是让 Codex 在正确作用域读到完整的 SKILL.md 和配套资源。

搜索“Codex Skill 怎么安装”的用户，通常已经找到一个 GitHub 仓库，却卡在“clone 到哪里、为什么不显示、可不可以直接执行安装脚本”。这篇只解决这条安装链路。

开始之前先确认一点：Codex 目前主要通过新版 ChatGPT 桌面应用使用，网页版入口已经取消。如果你还在找入口，可以先看 Codex 网页版下线了吗：2026 最新入口与使用方法。

先选个人级还是项目级

个人级适合你在多个项目都要用的能力，例如写作、图片处理、代码审查。常见位置是 ~/.codex/skills/技能名/SKILL.md。

项目级适合只服务于某个仓库的流程，例如公司发布规范、项目测试约定。它应放在项目约定的 Skills 目录中，并随代码库维护。不同 Codex 客户端、IDE 集成和版本对项目级目录的约定可能不同，因此应以当前产品文档或项目已有约定为准，不要为了照搬教程随意改项目结构。

优先选择项目已有的写法；没有约定时，再安装个人级 Skill 做低风险验证。

从 GitHub 下载的正确姿势

1. 打开仓库，定位含有 SKILL.md 的文件夹。
2. 复制整个技能文件夹，而不是只复制 SKILL.md。有些 Skill 还依赖 references、模板或脚本。
3. 放入 ~/.codex/skills/ 后，检查最终路径是否形如 ~/.codex/skills/技能名/SKILL.md。
4. 新建 Codex 会话，提出一个明确匹配该 Skill 的小任务进行验证。

如果使用 Git 克隆，目标目录应直接是技能名目录。后续升级可在该目录内拉取更新；不要把不同版本混到同一个目录。

不生效时按这个顺序检查

先看路径：最常见问题是出现了两层目录，例如 ~/.codex/skills/仓库名/技能名/SKILL.md。

再看文件：文件必须叫 SKILL.md，且内容要有清晰的名称、用途和触发说明。

然后排同名：个人级与项目级、旧版本与新版本若同名，可能造成加载结果不确定。先改名或保留一个版本。

最后看依赖：Skill 需要的命令、运行环境或访问凭证不存在时，即使被加载也无法完成任务。不要把缺失密钥直接写进 Skill 文件。

更新时最容易忽略的事

更新并不只是执行 pull。先看变更内容：新增的脚本会不会写文件、访问外网、上传资料；说明是否改变了原来的边界；依赖版本是否产生兼容问题。

对稳定生产流程，建议固定已验证版本，不要因为“有新版”立刻更新。更新后至少用一个历史样例复测输出和权限行为。