Codex Skill 结构拆解：看到一个 Skill 先读这 6 层

看到一个 Skill，不要先问“能不能装”。先问：它由哪些文件组成，每个文件会让 Codex 做什么。

下面这 6 层是只读拆解顺序。

第 1 层：目录名

目录名通常就是 Skill 的短名称，例如：

• skill-creator
• openai-docs
• playwright
• gh-fix-ci
• cloudflare-deploy
• security-threat-model

先判断名字是否表达任务。如果名字像 helper、agent、toolbox 这种很泛，要更谨慎，因为它可能触发场景不清。

第 2 层：SKILL.md frontmatter

重点看：

---
name: skill-name
description: When and why this skill should be used
---

新手要问 4 个问题：

1. name 是否和目录一致。
2. description 是否说明“什么时候用”。
3. description 是否太宽，导致什么任务都想触发。
4. description 是否包含高风险动作，例如部署、删除、授权、提交代码。

description 写得越清楚，Codex 越不容易乱用 Skill。

第 3 层：SKILL.md 正文

正文不是说明书摘要，而是 Codex 被触发后要执行的工作流。

合格正文通常包含：

• 使用前提：需要用户提供什么。
• 执行步骤：先读什么、再做什么。
• 输出格式：最后应该输出什么。
• 停止条件：遇到权限、费用、删除、生产数据时怎么停。
• 验证方式：如何证明任务完成。

空泛正文长这样：

帮助用户完成部署，并提供最佳实践。

有用正文长这样：

先确认框架、构建命令、输出目录、账号状态、环境变量和预览/生产目标。
未确认前不要部署。
部署后返回 URL、构建日志摘要、回滚方式和剩余风险。

第 4 层：scripts/

这是最需要警惕的目录。脚本可能：

• 读写本地文件。
• 安装依赖。
• 运行 shell 命令。
• 调用浏览器。
• 访问 GitHub 或云服务。
• 上传文件或生成新文件。

只读审查脚本时，让 Codex 输出这个表：

脚本	会读什么	会写什么	会联网吗	需要凭证吗	能否空仓库测试

不要让它直接运行脚本。

第 5 层：references/ 和 assets/

references/ 通常放长资料、规则、模板说明。它的风险是：资料可能过时，或者来自社区而不是官方。

assets/ 可能放模板、图片、示例文件、设计资源。它的风险是：版权、品牌、隐私或不可公开复用。

新手要问：

• 这些资料是官方事实、作者经验，还是项目内部规则？
• 有没有访问日期或版本？
• 能不能公开复用？
• 是否包含真实客户、账号、截图、密钥或隐私信息？

第 6 层：agents/ 配置

Agent Skills 标准允许一个 Skill 通过 agents/ 放不同平台的适配配置，例如 OpenAI 或 Claude 使用不同字段。

看到 agents/openai.yaml 这类文件时，先只读判断：

• 它是否只是适配元数据。
• 它是否改变触发描述。
• 它是否声明额外工具、MCP 或权限。
• 它是否和 SKILL.md 描述一致。

如果配置和正文矛盾，先不要安装。

一次完整只读拆解

请按 6 层只读拆解这个 Codex Skill。不要安装，不要运行命令。

Skill 链接或本地路径：{URL 或路径}
访问日期：2026-06-17

请输出：
1. 目录名是否清楚
2. SKILL.md frontmatter 的 name 和 description
3. description 的触发场景是否过宽或过窄
4. 正文是否包含前提、步骤、输出、停止条件、验证方式
5. scripts/ 是否存在；如果存在，逐个说明读写、联网、凭证、风险
6. references/ 和 assets/ 是否存在；它们是什么资料，是否可能过时或涉及版权
7. agents/ 配置是否存在；是否和 SKILL.md 一致
8. 结论：只读学习 / 空仓库测试 / 暂不安装 / 不要安装

练习：拆 cloudflare-deploy

只读时你应该得到类似结论：

• 目录名清楚：部署到 Cloudflare。
• description 触发场景清楚：用户要求部署、托管、发布。
• 风险高：可能涉及账号、项目配置、环境变量、公开 URL、费用。
• 新手结论：只读学习；如果测试，只能空项目预览部署。

成功标志

你不需要把 Skill 看成神秘插件。你只要能回答：

• 它什么时候触发？
• 它让 Codex 按什么步骤做？
• 它有没有脚本？
• 它会不会碰账号、云服务、GitHub、浏览器或真实文件？
• 它完成后如何验证？

这 5 个问题答不上来，就不要安装。

来源与日期

• 来源：Codex Agent Skills、openai/skills、Agent Skills open standard。
• 访问日期：2026-06-17。