skill-creator

技能创建器

此技能提供创建高效技能的指导。

关于技能

技能是模块化、独立的文件夹，通过提供专业知识、工作流和工具来扩展 Codex 的能力。可以把它们看作针对特定领域或任务的“入门指南”——它们能将 Codex 从通用 Agent 转变为具备流程性知识的专业 Agent，而这些知识是任何模型都无法完全掌握的。

技能提供的内容

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专业知识——公司特定知识、架构和业务逻辑
4. 捆绑资源——用于复杂且重复任务的脚本、参考资料和素材

核心原则

简洁至关重要

上下文窗口是一项公共资源。技能需要与 Codex 所需的其他所有内容共享上下文窗口：系统提示词、对话历史、其他技能的元数据，以及实际的用户请求。

默认假设：Codex 已经非常聪明。 只添加 Codex 尚不具备的上下文。逐条审视信息：“Codex 真的需要这项说明吗？”以及“这段内容值得消耗这些 token 吗？”

与其冗长解释，不如优先使用简洁示例。

设置适当的自由度

根据任务的脆弱程度和可变性，调整具体程度：

高自由度（基于文本的说明）：适用于存在多种有效方法、决策取决于上下文，或需要通过启发式方法指导操作的情况。

中等自由度（带参数的伪代码或脚本）：适用于存在首选模式、允许一定变化，或配置会影响行为的情况。

低自由度（具体脚本、少量参数）：适用于操作脆弱且容易出错、一致性至关重要，或必须遵循特定顺序的情况。

把 Codex 想象成在探索一条路径：悬崖边的狭窄桥梁需要明确的护栏（低自由度），而开阔地带则允许多种路线（高自由度）。

保护验证的完整性

在迭代过程中，可以使用子 Agent 验证技能在真实任务中是否有效，或确认怀疑的问题是否确实存在。如果可以启动新的子 Agent，这种做法在修改后独立检查技能的行为、输出或故障模式时最有用。只有在能够启动新子 Agent 时才这样做。

使用子 Agent 进行验证时，应将其视为一种评估手段。目标是了解技能能否泛化，而不是让另一个 Agent 根据泄露的上下文重构答案。

优先使用提示词、输出、差异、日志或跟踪记录等原始材料。只提供完成验证所需的最少任务上下文。避免提供预期答案、怀疑存在的错误、预期修复方案或你先前的结论，除非验证明确要求这些信息。

技能的组成

每项技能都包含一个必需的 SKILL.md 文件，以及可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
├── agents/ (recommended)
│   └── openai.yaml - UI metadata for skill lists and chips
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

每个 SKILL.md 都包含：

• Frontmatter（YAML）：包含 name 和 description 字段。这是 Codex 用来判断何时使用技能的唯一字段，因此必须清楚、全面地说明技能的内容以及适用时机。
• 正文（Markdown）：使用技能的说明和指导。仅在技能触发后才会加载（如果触发的话）。

Agents 元数据（推荐）

• 面向 UI 的元数据，用于技能列表和标签
• 生成值前，请阅读 references/openai_yaml.md，并遵循其中的说明和约束
• 阅读技能内容，创建面向用户的 display_name、short_description 和 default_prompt
• 通过将这些值作为 --interface key=value 传递给 scripts/generate_openai_yaml.py 或 scripts/init_skill.py，以确定性方式生成
• 更新时：验证 agents/openai.yaml 是否仍与 SKILL.md 一致；如果已过时，请重新生成
• 仅在明确提供时才包含其他可选界面字段（图标、品牌颜色）
• 有关字段定义和示例，请参阅 references/openai_yaml.md

捆绑资源（可选）

脚本（scripts/）

用于需要确定性可靠性或经常重写的任务的可执行代码（Python/Bash 等）。

• 适用情况：反复重写相同代码，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省令牌、结果确定，且无需加载到上下文即可执行
• 注意：Codex 仍可能需要读取脚本，以便进行修补或适应特定环境

参考资料（references/）

按需加载到上下文中，用于指导 Codex 流程和思考的文档及参考材料。

• 适用情况：Codex 工作时需要查阅文档
• 示例：财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 用途：数据库架构、API 文档、领域知识、公司政策、详细工作流指南
• 优点：保持 SKILL.md 简洁，仅在 Codex 判断需要时加载
• 最佳实践：如果文件较大（>10k 个词），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或 references 文件中，不能两处都有。除非信息确实是技能的核心内容，否则详细信息应优先放入 references 文件；这样既能保持 SKILL.md 简洁，又便于查找信息，且不会占用过多上下文窗口。SKILL.md 中仅保留必要的操作说明和工作流指南；将详细参考资料、架构和示例移至 references 文件。

资源文件（assets/）

不打算加载到上下文中，而是供 Codex 在生成输出时使用的文件。

• 适用情况：技能需要在最终输出中使用这些文件
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板 assets/frontend-template/、字体排版用的 assets/font.ttf
• 用途：模板、图像、图标、样板代码、字体、可复制或修改的示例文档
• 优点：将输出资源与文档分开，让 Codex 能使用这些文件，而无需加载到上下文中

技能中不应包含的内容

技能应仅包含直接支持其功能所必需的文件。不要创建多余的文档或辅助文件，包括：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等等

技能应仅包含 AI Agent 完成当前任务所需的信息。不要包含关于创建流程的辅助背景信息、设置和测试流程、面向用户的文档等。创建额外的文档文件只会增加杂乱和混淆。

渐进式披露设计原则

技能采用三级加载系统，以高效管理上下文：

1. 元数据（名称 + 描述） - 始终处于上下文中（约 100 个词）
2. SKILL.md 正文 - 技能触发时加载（<5k 个词）
3. 捆绑资源 - Codex 按需加载（无限制，因为脚本可以执行，而无需读入上下文窗口）

渐进式披露模式

将 SKILL.md 正文精简至必要内容，并控制在 500 行以内，以尽量减少上下文膨胀。接近此限制时，请将内容拆分到单独的文件中。将内容拆分到其他文件时，务必在 SKILL.md 中引用这些文件，并清楚说明何时阅读它们，确保技能的读者知道这些文件的存在及其用途。

核心原则： 当技能支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流和选择指南。将特定变体的详细信息（模式、示例、配置）移至单独的参考文件。

模式 1：高层指南与参考文件

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Codex 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

对于涉及多个领域的技能，按领域组织内容，避免加载无关上下文：

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

当用户询问销售指标时，Codex 只读取 sales.md。

同样，对于支持多个框架或变体的技能，也应按变体组织：

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

当用户选择 AWS 时，Codex 只读取 aws.md。

模式 3：有条件地提供详细信息

展示基础内容，并链接到进阶内容：

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

只有当用户需要这些功能时，Codex 才会读取 REDLINING.md 或 OOXML.md。

重要指南：

• 避免引用层级过深 — 引用文件应与 SKILL.md 保持一层的层级。所有参考文件都应直接从 SKILL.md 链接。
• 为较长的参考文件添加结构 — 对于超过 100 行的文件，请在顶部添加目录，以便 Codex 预览时了解其完整范围。

技能创建流程

创建技能包括以下步骤：

1. 通过具体示例了解技能
2. 规划可复用的技能内容（脚本、参考文件、资源）
3. 初始化技能（运行 init_skill.py）
4. 编辑技能（实现资源并编写 SKILL.md）
5. 验证技能（运行 quick_validate.py）
6. 根据实际使用情况迭代，并对复杂技能进行前向测试。

请按顺序执行这些步骤；只有在有明确理由认为某一步不适用时，才跳过该步骤。

技能命名

• 仅使用小写字母、数字和连字符；将用户提供的标题规范化为连字符形式（例如，“Plan Mode” -> plan-mode）。
• 生成名称时，应控制在 64 个字符以内（字母、数字、连字符）。
• 优先使用简短、以动词开头且能描述操作的短语。
• 在有助于提升清晰度或触发效果时，使用工具名称作为命名空间（例如，gh-address-comments、linear-address-issue）。
• 技能文件夹的名称必须与技能名称完全一致。

步骤 1：通过具体示例了解技能

只有在已充分了解技能的使用模式时，才跳过此步骤。即使是在处理现有技能时，此步骤仍然很有价值。

要创建有效的技能，必须清楚了解该技能的具体使用方式。这些信息可以来自用户直接提供的示例，也可以来自经过用户反馈验证的生成示例。

例如，构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应支持哪些功能？编辑、旋转，还是其他功能？”
• “你能提供一些该技能的使用示例吗？”
• “我可以想象用户会提出诸如‘去掉这张图片中的红眼’或‘旋转这张图片’之类的请求。你还设想过其他使用方式吗？”
• “用户说什么时应该触发此技能？”
• “应该在哪里创建此技能？如果你没有偏好，我会将其放在 $CODEX_HOME/skills（如果未设置 CODEX_HOME，则放在 ~/.codex/skills），以便 Codex 自动发现它。”

为避免让用户应接不暇，不要在一条消息中提出太多问题。先提出最重要的问题，并根据需要继续提问，以获得更好的效果。

当清楚了解该技能应支持的功能后，即可结束此步骤。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请通过以下方式分析每个示例：

1. 思考如何从头开始完成示例中的任务
2. 找出重复执行这些工作流时会用到哪些脚本、参考资料和资源

示例：创建用于处理“帮我旋转这个 PDF”这类请求的 pdf-editor 技能时，分析发现：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存放在技能中会很有帮助

示例：设计用于处理“帮我制作一个待办应用”或“帮我制作一个跟踪步数的仪表板”这类请求的 frontend-webapp-builder 技能时，分析发现：

1. 每次编写前端 Web 应用都需要重复编写相同的 HTML/React 样板代码
2. 将包含样板 HTML/React 项目文件的 assets/hello-world/ 模板存放在技能中会很有帮助

示例：创建用于处理“今天有多少用户登录了？”这类请求的 big-query 技能时，分析发现：

1. 每次查询 BigQuery 都需要重新查找表架构和关系
2. 将用于记录表架构的 references/schema.md 文件存放在技能中会很有帮助

要确定技能的内容，请分析每个具体示例，并列出要包含的可复用资源：脚本、参考资料和资源。

步骤 3：初始化技能

此时，就可以实际创建技能了。

仅当正在开发的技能已存在时，才跳过此步骤。此时，请继续下一步。

运行 init_skill.py 之前，请询问用户希望将技能创建在哪里。如果用户未指定位置，默认使用 $CODEX_HOME/skills；如果未设置 CODEX_HOME，则回退到 ~/.codex/skills，以便自动发现该技能。

从头创建新技能时，始终运行 init_skill.py 脚本。该脚本可以方便地生成新的技能模板目录，并自动包含技能所需的所有内容，让技能创建过程更加高效可靠。

用法：

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

示例：

scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources scripts,references
scripts/init_skill.py my-skill --path ~/work/skills --resources scripts --examples

该脚本会：

• 在指定路径创建技能目录
• 生成包含正确 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 使用通过 --interface key=value 传入的、由 Agent 生成的 display_name、short_description 和 default_prompt 创建 agents/openai.yaml
• 根据 --resources 可选创建资源目录
• 设置 --examples 时可选添加示例文件

初始化后，自定义 SKILL.md，并根据需要添加资源。如果使用了 --examples，请替换或删除占位文件。

阅读技能后生成 display_name、short_description 和 default_prompt，然后将它们作为 --interface key=value 传给 init_skill.py，或使用以下命令重新生成：

scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value

仅当用户明确提供其他可选接口字段时，才将其包含在内。有关字段的完整说明和示例，请参阅 references/openai_yaml.md。

步骤 4：编辑技能

编辑（新生成或已有的）技能时，请记住，这个技能是为另一个 Codex 实例使用而创建的。请包含对 Codex 有益且不明显的信息。思考哪些流程知识、领域专属细节或可复用资源能帮助另一个 Codex 实例更有效地完成这些任务。

完成大量修改后，或者技能特别棘手时，应使用子 Agent 在真实任务或制品上对技能进行前向测试。进行测试时，传入待验证的制品，而不是你对问题所在的诊断；提示词应足够通用，使成功取决于可迁移的推理能力，而非隐藏的标准答案。

从可复用的技能内容开始

开始实现时，先使用上文确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户输入。例如，实现 brand-guidelines 技能时，用户可能需要提供品牌素材或模板，存放在 assets/ 中；也可能需要提供文档，存放在 references/ 中。

必须实际运行新增的脚本并进行测试，确保没有错误且输出符合预期。如果有许多相似的脚本，只需测试有代表性的样本，以确信它们都能正常工作，同时兼顾完成所需的时间。

如果使用了 --examples，请删除技能不需要的占位文件。只创建实际需要的资源目录。

更新 SKILL.md

**写作指南：**始终使用祈使或不定式形式。

Frontmatter

使用 name 和 description 编写 YAML frontmatter：

• name：技能名称
• description：这是技能的主要触发机制，有助于 Codex 理解何时使用该技能。
  • 同时说明技能的功能，以及使用它的具体触发条件或场景。
  • 将所有“何时使用”信息都写在这里，而不是正文中。正文只会在触发后加载，因此在正文中添加“何时使用此技能”部分对 Codex 没有帮助。
  • docx 技能的描述示例：“全面支持文档创建、编辑和分析，包括修订跟踪、批注、格式保留和文本提取。Codex 需要处理专业文档（.docx 文件）时使用，例如：(1) 创建新文档，(2) 修改或编辑内容，(3) 处理修订跟踪，(4) 添加批注，或执行任何其他文档任务”

不要在 YAML frontmatter 中包含其他字段。

正文

编写使用技能及其捆绑资源的说明。

第 5 步：验证技能

技能开发完成后，验证技能文件夹，尽早发现基本问题：

scripts/quick_validate.py <path/to/skill-folder>

验证脚本会检查 YAML frontmatter 格式、必填字段和命名规则。如果验证失败，请修复报告的问题，然后再次运行命令。

第 6 步：迭代

测试技能后，你可能会发现该技能足够复杂，需要进行前向测试；用户也可能会要求改进。

用户测试通常会在使用技能后立即进行，此时用户对技能的表现还记忆犹新。

前向测试与迭代工作流：

1. 在实际任务中使用技能
2. 留意遇到的困难或低效之处
3. 确定应如何更新 SKILL.md 或捆绑资源
4. 实施更改并再次测试
5. 在合理且适当时进行前向测试

前向测试

要进行前向测试，可启动子 Agent，在尽可能少的上下文下对技能进行压力测试。 子 Agent 不应知道自己是在测试技能。应将其视为接到用户任务的 Agent。 发给子 Agent 的提示词应类似于： Use $skill-x at /path/to/skill-x to solve problem y 而不是： Review the skill at /path/to/skill-x; pretend a user asks you to...

前向测试的决策规则：

• 倾向于进行前向测试
• 如果你认为前向测试可能会：
  • 耗时较长，
  • 需要用户额外批准，或
  • 修改在线生产系统， 请先征求批准

在这些情况下，向用户展示你拟定的提示词，并请求用户：(1) 作出是或否的决定；(2) 提出任何修改建议。

前向测试时的注意事项：

• 独立测试应使用全新的会话线程
• 以类似用户请求的方式提供技能和请求
• 提供原始材料，而非你的结论
• 不要透露预期答案或计划的修复方案
• 每次迭代后，根据源材料重建上下文
• 检查子 Agent 的输出、推理和生成的材料
• 避免在各轮测试之间留下 Agent 能在磁盘上找到的材料； 清理子 Agent 生成的材料，避免造成额外干扰。

如果前向测试只有在子 Agent 接触到泄露的上下文时才能成功，那么在信任测试结果之前，应完善技能或前向测试设置。