知道 Codex Skills 有用之后，很多人接下来卡住的不是“值不值得做”，而是“装在哪里、怎么让它生效、怎么停用、团队怎么共享”。这件事如果只记住一个原则，就是先分清作用域，再决定安装方式。OpenAI 当前 Build skills 文档把 Codex 的 Skill 管理拆成扫描位置、启停配置和插件分发三层；把这三层混在一起，是新手最常见的错误。
核心结论：先选作用域，再安装，最后用配置做治理
Codex 会从仓库、用户、管理员和系统位置扫描 Skills。项目专用流程适合放仓库，个人长期习惯适合放用户目录，共享机器适合管理员目录，而需要跨团队安装和分发时才该考虑插件。官方文档还给出了两条重要规则：一是可以用 $skill-installer 安装精选 Skill；二是可以在 ~/.codex/config.toml 里用 [[skills.config]] 和 enabled = false 临时禁用某个 Skill，而不用删文件。
适用人群与准备条件
这篇文章适合正在本地使用 Codex 的开发者、团队维护者，以及需要把项目内 Skill 交给同事共享的人。准备条件有三个：知道自己的仓库根目录在哪里，知道当前系统的用户主目录在哪里，并且能修改本机的 ~/.codex/config.toml。下面示例按 2026 年 7 月 12 日可见的官方 Build skills 文档核对，适用于当前 Codex 本地 Skill 机制。
官方扫描位置先记住这 4 类
按官方文档，仓库级会从你当前工作目录向上扫描到仓库根目录里的 .agents/skills；用户级在 $HOME/.agents/skills；管理员级在 /etc/codex/skills；系统级则由产品自带。这里最重要的不是路径本身，而是影响范围：你想让谁看到它，就把它放在对应层级。
实际使用示例：从仓库安装到临时禁用
下面这个例子适合项目内共享。先在仓库根目录创建 Skill：
repo/
.agents/
skills/
release-check/
SKILL.md
references/checklist.md
scripts/verify.ps1如果你只是想安装官方精选 Skill，可以直接运行：
$skill-installer linear官方文档说明，Codex 会自动检测新安装的 Skill；如果没有出现，先重启 Codex。若你要临时禁用某个 Skill，而不是删除它，可把下面配置写进 ~/.codex/config.toml：
[[skills.config]]
path = "/Users/alex/.agents/skills/release-check/SKILL.md"
enabled = falseWindows 机器只需要把 path 换成自己的绝对路径，例如 C:/Users/alex/.agents/skills/release-check/SKILL.md。改完配置后，官方要求重启 Codex 让禁用状态生效。
可直接照做的排查顺序
- 确认你是从正确仓库目录启动 Codex，因为仓库 Skill 按当前工作目录向上扫描。
- 确认 Skill 目录里真的有
SKILL.md，而不是只放了脚本或模板。 - 检查是否存在同名 Skill；官方说明同名 Skill 不会自动合并，可能都会出现。
- 如果刚用
$skill-installer装完或刚改了config.toml仍未生效，先重启 Codex。 - 如果这个 Skill 已经变成跨团队标准流程，别再靠复制目录同步，改用插件分发更稳。
常见错误、限制和避坑
- 把个人 Skill 放进仓库，结果影响所有同事。
- 把项目 Skill 放到全局目录，导致它在别的仓库里乱入。
- 把本地文件安装和插件分发混成一件事。
- 手工复制多份目录，最后不知道哪一份才是最新版本。
最后建议：先小范围试运行，再放大
无论你现在看到的是概念解释、目录结构、安装方法还是排查思路，真正落地时都建议先选一个低风险、小范围、可回滚的任务试运行。先把输入样本、执行步骤、关键命令、最终结果和失败情况记录下来，再回头看哪些规则是稳定的、哪些描述还太宽、哪些动作应该交给脚本或工具。这样做的好处是，你不会因为第一次就追求完整而把流程做得过重，也不会在边界还没摸清时过早共享给团队。
如果试运行期间仍然需要频繁口头补充，说明这部分知识还没有真正沉淀进正文。等一次小范围试运行已经能稳定复现同样结果，再把它扩展到更多目录、更多同事或更多系统，并补上禁用、回滚、验收和来源更新规则。对 Skill、MCP 和自动化来说，最省时间的路线通常不是一开始就做大，而是先做小、做稳、保留证据，再逐步放权。
相关阅读
总结
安装 Codex Skills 的重点不是“丢进哪个文件夹”这么简单，而是先选对作用域，再用正确路径或安装器落地，最后用配置做启停治理。这样 Skill 才会成为资产，而不是越来越乱的本地小技巧集合。
