OpenAI官方Codex_Skill案例拆解与使用思路

这篇文章对OpenAI Codex内置的两大官方Skill——skill-creator和imagegen，进行了详细解读。首先，明确了它们在/skills/built-in/下的物理路径；接着，解析了SKILL.md中的description，它是触发的关键，同时还涉及到openai.yaml的依赖声明；然后，特别说明了imagegen若要实现透明背景，需要显式的prompt指令或--alpha=true参数；最后，为大家提供了如何安全地将其复制改造成custom Skill的指导。

你是否想复用OpenAI官方Codex Skill，却不知从何下手？比如，不知道该从哪个文件开始，metadata该如何编写才能容易被触发，SKILL.md里的哪些字段真正会影响运行结果。别担心，这篇文章将直接带你深入剖析skill-creator和imagegen这两个真实的内置Skill，逐步还原它们在Harness Runtime中的激活路径和执行逻辑。

定位官方 Skill 的物理存放位置

进入 Codex 安装目录下的

子目录，这里存放所有 OpenAI 官方预置 Skill。不要手动修改该目录下任何文件，否则下次更新会覆盖。

skill-creator 和 imagegen 分别位于 /skills/built-in/skill-creator/ 和 /skills/built-in/imagegen/。每个目录都是一个完整 Skill 包，含 SKILL.md、openai.yaml、Scripts/、References/ 等标准结构。

注意：Codex 启动时只读取各 Skill 目录根层的 SKILL.md 前段 YAML 元数据（name/description/path），全文本内容仅在任务匹配后加载——这是渐进式披露（progressive disclosure）机制的关键前提。

解析 skill-creator 的元数据与触发逻辑

打开 /skills/built-in/skill-creator/SKILL.md，先看顶部 YAML frontmatter：

name: "skill-creator"
description: "Create, modify, or validate a new Codex Skill directory structure and required files."
path: "./"

这个 description 不是功能罗列，而是**触发条件本身**。当用户说“帮我新建一个叫 api-tester 的 Skill”或“校验当前 skill 目录是否符合规范”，Codex 就会匹配到该 description 并加载完整技能。

description 中必须包含动词+宾语结构（如 create/modify/validate + Skill directory），且宾语要和实际用途强相关。写成“辅助开发”或“提升效率”这类模糊表述会导致匹配失败。

该 Skill 的 openai.yaml 中声明了 tool_dependencies: [file_system, shell]，说明它依赖本地文件系统操作权限——若你在受限沙箱环境运行 Codex，此 Skill 将无法执行，不会报错，而是静默跳过。

imagegen Skill 的透明背景实现路径

方法一：通过 prompt 指令控制
在调用 $imagegen 时，必须显式写出 “transparent background” 或 “PNG with alpha channel”，模型不会默认启用抠图。这是因为 imagegen 的 Instructions 明确限定：仅当 prompt 中间出现 transparent / alpha / cutout 等关键词时，才启用 post-processing 抠图流程。

方法二：强制指定输出格式
在 prompt 末尾追加 “--format=png --alpha=true”，这会绕过自然语言理解，直接触发脚本层的 convert-to-png-with-alpha.sh 脚本。该脚本调用 ImageMagick 执行通道分离→蒙版生成→合成，整个过程不经过模型推理。

抠图能力仅对纯色背景（#FFFFFF / #000000 / 单一 RGB 值）有效；对渐变、纹理、多物体遮挡场景，脚本会自动降级为普通 PNG 输出，并在结果元信息中添加 warning 字段。

将官方 Skill 改造成你自己的版本

第一步：复制整个 skill-creator 目录到 /skills/custom/
第二步：重命名目录为 my-skill-builder
第三步：修改 my-skill-builder/SKILL.md 中的 name 字段为 "my-skill-builder"，description 改为 "Create validated Skill directories with pre-filled AGENTS.md template and MCP config stub."
第四步：编辑 Scripts/init-skill.sh，在生成标准文件后，自动向 AGENTS.md 插入三行项目级上下文：
- This is a production-ready Skill for internal API integration.
- All scripts must log to /var/log/codex/my-skill-builder/
- Never write outside /home/codex/skills/my-skill-builder/

第五步：在 Codex CLI 中执行 /skills → reload，新 Skill 即刻可用。无需重启进程，reload 命令仅刷新 registry 缓存。