Skill 是 Codex 的工作流层，它将指令、资源和可选脚本打包成一个可复用的单元。
- 原理与结构：一个 Skill 本质是一个文件夹，其核心是一个
SKILL.md文件，包含name和description等元数据及具体操作指令。此外，还可选包含scripts/（脚本）、references/（参考资料）、assets/（资源）等目录。 - 激活机制：Codex 采用渐进式加载（Progressive Disclosure）策略。初始只加载所有技能的
name和description到上下文，当用户请求与某个技能的描述匹配时，才会加载该技能的完整SKILL.md。这意味着description需要精准概括技能用途和触发条件，即必须包含做什么和何时触发两个要素。
目录结构
一个标准技能目录如下：
my-skill/
├── SKILL.md # 必需：主说明文件
│ ├── YAML frontmatter # 必需：name + description
│ └── Markdown body # 必需：具体指令
├── agents/ # 推荐
│ └── openai.yaml # UI 元数据（图标、品牌色、隐式调用策略）
├── scripts/ # 可选：可执行代码（Python/Bash）
├── references/ # 可选：按需加载的参考资料
└── assets/ # 可选：输出用文件（模板、图标等）
作用域
| 作用域 | 路径 | 用途 |
|---|---|---|
| REPO | $CWD/.agents/skills、父目录及 $REPO_ROOT/.agents/skills | 仓库级团队技能 |
| USER | ~/.agents/skills | 跨仓库个人技能 |
| ADMIN | /etc/codex/skills | 机器/容器级默认 |
| SYSTEM | OpenAI 内置（skill-creator、skill-installer） | 自动安装到 $CODEX_HOME/skills/.system/ |
关于 .codex/skills 的重要说明：.codex/skills（即 $CODEX_HOME/skills）是 Codex 当前实际渲染使用的目录。~/.agents/skills 是行业标准化路径（agentskills.io 开放标准），Codex 的工具链会同时向两个位置安装以确保兼容性。如果你的技能放在 .codex/skills 下但未被识别，检查技能是否在 ~/.agents/skills 下也有对应副本，或升级到最新 CLI 版本。 |
创建与激活技能
创建方式：使用内置的 $skill-creator，它会依次询问技能做什么、何时触发、是否包含脚本。
显式激活：在 prompt 中提及技能名，或输入 /skills 或 $ 触发技能选择器。
禁用技能（在 ~/.codex/config.toml 中，需重启）：
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
