Codex Skills 怎么安装和验证：skill-installer、目录与不生效排查

曲速指南2026-08-28发布 WarpSatomi

Codex Skills 的安装方式不止一种：官方精选或第三方仓库可以交给内置的 $skill-installer；团队随项目维护的 Skill 应放在仓库的 .agents/skills；准备分发给更多用户的组合能力则更适合打包成 Plugin。先把路线分开，再验证“是否可见、能否显式调用、会不会隐式触发”，比把所有文件都复制到同一个目录更可靠。本文依据 2026 年 8 月 28 日的 OpenAI Docs 与当前内置 Skill 定义整理，本轮未实际安装新 Skill。

Codex Skills 安装验证与不生效排查封面 — 先区分安装路线和目录，再按可见、显式调用、隐式触发与预期输出逐层验证。

先选安装方式

你的目标	建议路线	关键边界
安装 OpenAI 精选 Skill	调用 `$skill-installer`	适合个人本地使用与试验；安装后再做四层验证
安装 GitHub 第三方 Skill	让 `$skill-installer` 处理仓库和路径	安装前固定来源版本并做安全审计，不要直接执行陌生脚本
为当前仓库手工创建 Skill	放入当前目录至仓库根之间的 `.agents/skills`	作用域取决于 Codex 的启动目录和仓库层级
为个人手工维护通用 Skill	`$HOME/.agents/skills`	这是现行公共文档的用户级本地创作位置
分发多个 Skills 或同时带连接器	制作 Plugin	直接 Skill 文件夹适合本地创作；跨用户分发优先 Plugin

Codex Skills 从 installer、GitHub 和项目目录进入不同 Skill 路径的安装路线示意图 — 项目级 `.agents/skills`、安装器管理目录与 `config.toml` 扮演不同角色，不代表实际 Codex 界面。

这里最容易出现的误区，是把 .agents/skills、~/.codex/skills 和 ~/.codex/config.toml 当成三个可互换目录。它们扮演的角色不同：OpenAI 公共文档用 .agents/skills 描述手工创作和本地发现；当前内置 skill-installer 管理的是 $CODEX_HOME/skills，默认落在 ~/.codex/skills；~/.codex/config.toml 则用于 Codex 本地配置和按路径禁用 Skill。

用 skill-installer 安装

Codex 内置的 Skill Installer 是一个系统 Skill，不是需要先在终端安装的独立包。在 Codex 中显式提及它即可。OpenAI Docs 给出的精选 Skill 示例是：

$skill-installer linear

安装其他仓库中的 Skill 时，把仓库、引用版本和 Skill 子目录说清楚。例如：

$skill-installer install the skill from
https://github.com/owner/repo/tree/<tag-or-commit>/path/to/skill

这里的 URL 是占位示例，不对应实际推荐项目。第三方仓库尽量使用包含标签或完整提交的地址，不要只跟随会变化的 main。安装器当前默认可从公开 GitHub 仓库直接下载，遇到权限问题可能改用现有 Git 凭据；因此安装前应先查看来源、SKILL.md、脚本和依赖。WarpNav 的第三方 Agent Skill 安装前安全审计可以作为这一步的检查清单。

安装器返回成功后，记录 Skill 名称、来源 URL、引用版本和实际目标目录。当前内置安装器说明新 Skill 会在下一轮可用；OpenAI Docs 同时说明 Codex 会自动检测新安装内容，仍未出现时再重启。不要在成功提示出现后立刻得出“已经能自动触发”的结论。

手工目录放哪里

现行 OpenAI Docs 对 Codex 本地发现给出的路径是 .agents/skills，注意 agents 是复数。把文件放进 .agent/skills、.agents/skill 或直接写成 .agents/skills/name.md 都不是同一结构。每个 Skill 应有自己的目录，并以 SKILL.md 为入口：

.agents/
└─ skills/
   └─ my-skill/
      ├─ SKILL.md
      ├─ scripts/       # 可选
      ├─ references/    # 可选
      ├─ assets/        # 可选
      └─ agents/
         └─ openai.yaml # 可选

SKILL.md 的 frontmatter 至少要有 name 和 description。项目级发现不是只看仓库根：Codex 会从当前工作目录向上扫描每一层的 .agents/skills，直到仓库根。这允许大型仓库把某个模块专用 Skill 放在较近的父目录，也意味着从不同目录启动 Codex 时，可见范围可能不同。

作用域	现行公共文档位置	用途
当前目录	`$CWD/.agents/skills`	只服务当前工作目录或模块
父目录至仓库根	`$CWD/../.agents/skills` 等	供子目录共享，扫描止于仓库根
用户级	`$HOME/.agents/skills`	跨仓库使用的个人手工 Skill
管理员级	`/etc/codex/skills`	机器或容器中的统一管理 Skill
系统级	由 Codex 内置	例如 skill-creator、skill-installer

同名 Skill 不会被合并，选择器中可能同时出现多个同名项。此时不要靠名字猜来源，应看 Codex 初始列表或选择器展示的文件路径。官方文档也说明 Codex 支持符号链接目录并跟随目标；第三方链接目标仍应纳入安装前审计。

四层验证

更实用的验收方法，是把“安装成功”拆成四层：

层级	检查方法	通过标准	失败优先检查
1. 可见	桌面版查看侧栏 Skills；CLI/IDE 运行 `/skills`	名称、描述和来源路径正确	下一轮、重启、目录、作用域、禁用配置
2. 显式调用	输入 `$skill-name` 加一个低风险测试任务	Codex 加载正确的 `SKILL.md`	同名来源、frontmatter、实际名称
3. 隐式触发	新一轮只描述与 `description` 精确匹配的任务	Codex 主动选择目标 Skill	description、列表预算、调用策略
4. 预期输出	使用无写入、无联网或测试数据的最小任务	输出符合 Skill 声明，没有越权副作用	说明与脚本、依赖、权限是否一致

第一层证明 Codex 发现了它，第二层证明可以主动加载，第三层才涉及自动匹配，第四层才证明这个 Skill 在当前环境完成了最小任务。一个 Skill 能出现在列表里，不代表脚本依赖已经齐全；能显式调用，也不代表它应该自动触发。

完全看不到

先换到下一轮：当前内置安装器说明新 Skill 在下一轮可用，不要在安装动作尚未结束的同一轮里误判。
再看列表和路径：桌面版看侧栏 Skills；CLI/IDE 用 /skills。核对显示的文件路径，而不只看名称。
检查目录形状：必须是 <skill-name>/SKILL.md，并包含可解析的 name 与 description。
检查启动目录：仓库 Skill 只从当前工作目录向上扫描到仓库根；放在另一个不相干目录不会自动进入当前范围。
检查禁用配置：~/.codex/config.toml 中可能按精确 SKILL.md 路径把它设为 enabled = false。
最后重启 Codex：官方文档说明改动通常会自动检测；仍未出现时再重启，而不是先反复复制目录。

如果 Skill 数量很多，还要看 Codex 是否显示了列表预算警告。初始 Skill 列表最多约占模型上下文的 2%，在上下文大小未知时上限为 8,000 字符；Codex 会先缩短描述，仍过多时可能省略部分 Skill。这个预算只影响初始列表，Codex 选中 Skill 后仍会读取完整 SKILL.md。

能显式调用，但不会自动触发

这类问题通常不是安装失败。既然 $skill-name 能加载，说明名称、路径和入口至少基本可用。接下来重点看两处：

description：隐式匹配依赖它。把最重要的任务、输入和触发条件放在前面，避免只写“帮助开发”或“提高效率”。Skill 很多时描述可能被缩短，前置信息更重要。
allow_implicit_invocation：agents/openai.yaml 可把它设为 false。此时 Codex 不会根据普通提示自动调用，但显式 $skill-name 仍应工作。

policy:
  allow_implicit_invocation: false

对会部署、提交、发消息或修改外部系统的 Skill，保留显式调用可能是有意的安全设计，不应为了“自动触发成功”就机械打开隐式调用。更合理的测试是：先确认产品目标是否需要自动触发，再用一条和 description 高度匹配、没有副作用的提示验证。

禁用与回滚

本地 Skill 可以在不删除文件的情况下禁用。在 ~/.codex/config.toml 中添加精确入口路径：

[[skills.config]]
path = "/absolute/path/to/skill/SKILL.md"
enabled = false

修改后重启 Codex，再确认目标 Skill 不再出现在可用列表中。回滚时移除或调整这一条配置，并再次重启。编辑配置前保留副本；同名 Skill 存在多份时，必须使用实际路径，避免禁错对象。

如果确实要移除安装器管理的第三方 Skill，先从选择器确认完整来源路径，备份目录和来源记录，再只处理那个精确目录。不要递归清理整个 ~/.codex、~/.agents 或仓库根，也不要手工删除 Codex 的系统 Skill。仓库级 Skill 更适合通过项目版本控制回滚。

什么时候改用 Plugin

Skill 文件夹适合本地创作、个人使用和仓库内工作流。要把一个能力稳定分发给其他人，或同时携带多个 Skills、MCP 连接和展示资产，OpenAI 当前建议打包为 Plugin。换句话说，$skill-installer 适合本地设置和试验，Plugin 才是面向更多用户的分发边界。

想先判断某项工作是否值得做成 Skill，可以查看 WarpNav 的Codex 与 WorkBuddy Skill 工作流判断；Codex 产品入口与使用范围见Codex 详情页。如果目标来自第三方仓库，先完成安装前安全审计，再进入本文的安装和验证流程。

主要官方资料（核验于 2026 年 8 月 28 日）：OpenAI Docs Build skills https://developers.openai.com/codex/skills；OpenAI 官方 Skills 仓库 https://github.com/openai/skills。本文还核对了当前 Codex 内置 skill-installer 定义，用于区分安装器管理路径与公共文档的手工创作路径。Codex Skills、Plugins、目录和调用界面仍在变化，实际操作前应重新核对现行官方文档。