Codex 安装 Skills 最稳妥的做法是：本地试用用内置 $skill-installer，仓库共享放 .agents/skills，对外分发改走 plugins。下面按官方 Build skills 文档，把结构、路径、安装、禁用和报错一次讲清。
Skills 是什么，和 plugins 有何区别
Skill 是可复用的工作流封装：目录里放指令、可选脚本和参考资料。官方区分很清楚：
- Skills：写工作流本身，适合本机创作和仓库内共享；
- Plugins：把 Skills（及可选 connectors / MCP）打包给别人安装。
本机试用用 $skill-installer；对外分发做成 plugin。旧仓库 openai/skills 已 deprecated，官方指向 plugins。
Skill 目录结构（必须含 SKILL.md）
一个 Skill 就是一个文件夹，至少要有 SKILL.md。front matter 必须含 name 和 description：
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
Skill instructions for ChatGPT or Codex to follow. 可选：scripts/、references/、assets/、agents/openai.yaml。Codex 先读 name / description（及路径），选用后再加载完整指令。初始列表默认最多约上下文的 2%，或约 8000 字符；可用 skills.max_context_tokens 调整（上限 10000 tokens）。
怎么调用 Skills
- 显式调用 ：Codex CLI / IDE 用
/skills或$提及；ChatGPT 用@。 - 隐式匹配 ：任务对上
description时自动选用。
description 要短而准，触发词靠前。斜杠命令详见 Codex CLI 斜杠命令大全（含 /skills）。
创建 Skill
在 Codex 里调用内置创建器：
$skill-creator 它会询问做什么、何时触发、要不要脚本（默认纯指令）。也可手动在可扫描路径下建目录并写 SKILL.md。Codex 一般会自动检测变更；看不到就重启。
写 description 时把「何时该用 / 何时不该用」说清楚，并前置触发关键词，这样隐式匹配更稳；需要 UI 展示名、图标或关闭隐式调用时，再补 agents/openai.yaml。
Codex 从哪些路径加载 Skills
| 范围 | 路径 | 适用场景 |
|---|---|---|
| REPO | $CWD/.agents/skills |
当前目录 / 微服务级技能 |
| REPO | 上级 .agents/skills |
嵌套仓库时的父级共享 |
| REPO | $REPO_ROOT/.agents/skills |
整仓通用技能 |
| USER | $HOME/.agents/skills |
个人全局、跨仓库 |
| ADMIN | /etc/codex/skills |
机器 / 容器默认技能 |
| SYSTEM | Codex 内置 | 含 skill-creator、skill-installer |
同名不会合并；支持符号链接。本机创作用这些路径，对外分发再走 plugins。
仓库技能适合和代码一起评审、一起发版；个人技能适合放常用个人流程。两边都要写好 description，避免同名技能在选择器里堆太多、互相抢隐式匹配。
用 $skill-installer 安装精选 Skills
例如安装 Linear 技能：
$skill-installer linear也可让 installer 从其他 GitHub 仓库下载。装完通常自动检测；没有就重启 Codex。定位记住：本地试用用 installer；自己技能要给别人用，做成 plugins。MCP 相关可看 Codex 配置 MCP 教程 。
进阶注意（来自 skill-installer SKILL.md 示例）
$skill-installer install https://github.com/<owner>/<repo>/tree/main/<skill-folder>安装目标由 skill-installer 写入 Codex 可扫描的目录。SYSTEM 内置技能无需再装。
禁用 Skills（不删文件）
在 ~/.codex/config.toml：
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false 每条只用一个选择器（绝对 path 或 name）；多条命中以最后一条为准。关掉项目内全部内置技能，在受信任项目的 .codex/config.toml 写：
[skills.bundled]
enabled = false改完重启。配置不生效见 Codex 配置不生效排查 。
分步骤：从零装一个 Skill
- 确认 Codex 已能启动（内置已有 skill-creator / skill-installer）。
- 输入
$skill-installer linear，或让它从其他仓库下载。 - 用
/skills或$确认列表；没有则重启。 - 显式调用，或写一条能匹配 description 的任务验证隐式触发。
- 团队技能提交到仓库
.agents/skills；个人全局放$HOME/.agents/skills。 - 对外分发改用 plugins，不要依赖已 deprecated 的 openai/skills。
常见报错与解决
装完在 /skills 里找不到
确认安装无报错后重启 Codex；并核对是否落在 USER / REPO 等可扫描路径。
隐式调用从不触发
检查 description 触发词；看 agents/openai.yaml 是否设了 allow_implicit_invocation: false。也可改用 $ 技能名 显式调用。
技能太多，列表被截断或警告
属上下文预算行为。可调高 skills.max_context_tokens（上限 10000），或禁用暂时不用的技能。
禁用配置无效
确认改的是 Codex 正在读的 config，改后重启，并用 path / name 精确匹配。
还想从 openai/skills 装公开技能
该仓库已 deprecated。本地继续用 $skill-installer；对外改 plugins。
FAQ
问：SYSTEM 自带技能还要再装吗？
答：不用。skill-installer / skill-creator 默认启用。
问：REPO 和 USER 技能怎么选？
答：同名不会合并。团队共享放仓库 .agents/skills，个人习惯放 $HOME/.agents/skills。
问：Skills 和 MCP 一样吗？
答：不一样。Skills 是工作流指令包；MCP 是外部工具连接。plugins 可把两者一起分发。
问：手写 SKILL.md 最少要什么？
答：front matter 的 name、description，加上正文指令；其余目录可选。
