一个反复执行、步骤稳定、验收明确的任务，很适合做成 Skill。Skill 是一个目录，必需文件是 SKILL.md。Codex 启动时先读取每个 Skill 的名称和描述，任务匹配以后再读取完整指令，这种渐进加载能减少无关上下文。
本文内容核对到 2026 年 8 月。Skill 目录、创建入口和加载规则可能变化，制作前应再看当前官方说明。
初始 Skill 列表有上下文预算。官方说明会先缩短过长描述，数量很多时还可能省略部分 Skill 并给出警告。触发信息要在描述前半段说清，背景和长例子留到 SKILL.md 或引用文件。这样即使描述被缩短，任务仍有机会匹配到正确能力。
先定范围和触发条件
动手前写清它解决哪类任务，哪些相似任务不该触发，以及最终要交付什么。描述字段会参与隐式匹配，应把用途和关键词放在前面。范围太宽时，Skill 会在不相关的任务里频繁出现，指令也容易塞进互相冲突的流程。
你可以在 Codex 中调用内置创建器。
$skill-creator
它会询问用途、触发时机，以及是否需要脚本。流程已经能通过界面完整演示时，也可以在功能可用时使用 Record & Replay 生成初稿，再人工检查事实和安全边界。该功能需要 Computer Use 可用并启用，实际可用性以当前客户端和工作区设置为准。
建立最小目录
手工创建时，先用下面的结构。
my-skill/
├── SKILL.md
├── references/
└── scripts/
references 和 scripts 都是可选目录。模板、图片或其他资源可以放进 assets，外观与依赖元数据可以放进 agents/openai.yaml。第一版只有明确指令时，保留一个 SKILL.md 已经够用。
---
name: release-check
description: 检查功能分支的测试、提交和发布阶段。仅用于交付核验，不执行部署。
---
读取项目规则和 Git 状态。运行仓库已有检查，随后报告分支、提交、测试与发布阶段。
name 和 description 是必填元数据。正文按依赖顺序写动作、停止条件和验收方式。大段背景资料放进 references，确定性很强的重复处理放进脚本，主文件只保留选择流程。
引用文件要写清何时读取。一个 Skill 同时服务 macOS 和 Windows，可以在主文件里先判断系统，再分别读取对应参考。脚本负责可重复的机械动作，运行前仍应检查输入路径和副作用。会删除、发布或向外部系统写入的脚本，应把批准条件写在调用步骤附近。
仓库中出现同名 Skill 时，Codex 不会把它们合并，两份都可能出现在选择器里。团队给 Skill 命名时加上明确对象，例如 frontend-release-check，比使用宽泛的 review 更容易区分。目录名也与 name 保持一致，排错时能快速找到来源。
放到合适位置并验证
仓库级 Skill 放在当前目录到仓库根目录沿途的 .agents/skills 中，团队可以随代码提交。个人 Skill 放在 $HOME/.agents/skills，只服务当前用户。管理员目录是 /etc/codex/skills，系统 Skill 由 OpenAI 随产品提供。
新开一个会话，先用 $release-check 显式调用，检查它是否读到正确文件并守住停止条件。随后用不点名的自然请求测试隐式匹配。误触发时收窄 description，漏触发时补上读者会使用的任务词。
验证不能只看它有没有被调用。准备一个正常输入、一个缺少前提的输入，再给一个明确超出范围的请求。正常输入应完成既定步骤，缺少前提时应停下来说明缺口，超范围请求应交回普通任务流程。Skill 带脚本时，再单独测试错误路径和重复运行。
仓库级 Skill 可以随 Pull Request 审查。评审者应看触发描述、外部来源、脚本写入范围和交付标准。修改 Skill 后开新会话复测，旧会话可能仍持有之前加载的指令。
需要暂停某个本地 Skill 时，可以在 ~/.codex/config.toml 添加 [[skills.config]]，写入其 SKILL.md 路径并设置 enabled = false。改完以后重启 Codex。删除目录会让引用和排错线索一起消失，临时停用更容易恢复。
