技能创建器
创建能为Codex提供有用、非显而易见指导的技能，同时不限制无关工作。
核心原则
假设Codex已经具备能力。 仅包含那些能改变其决策或改进其工作的信息。删除通用建议、重复指令、推测性边缘情况以及不能实质性澄清任务的示例。
保留用户意图和范围。 技能应支持所请求的任务，而不是替换用户选择的产品、扩展任务、修改无关配置或暗示允许额外的外部操作。不要将特定示例、过去的失败或个人偏好变成普遍要求。
批准完成一项任务并不意味着其范围或执行权限得到扩展。对于重试或外部变更的工作流，定义一个与风险成比例的中止条件。
将具体程度与风险匹配。 当多种方法都合理时，给模型留出选择合适方法的空间。只有在正确性、安全性、权限或真正脆弱的工作流需要时，才使用详细步骤、确定性脚本或绝对语言。
对于开放式工作，描述预期结果和相关决策标准。对于有首选形式的工作流，提供有用的示例或可配置脚本。将对固定序列和狭窄参数的保留仅限于那些偏差会造成具体问题的操作。保留非显而易见的操作不变量，区分实际要求与可选建议或本地约定，并避免重复已在其他地方强制执行的策略。
保持发现廉价且精确。 技能名称和描述在技能加载之前可用。描述实际能力及其适用场景，仅在可能防止错误路由时才添加排除项。避免会吸引无关请求的详尽能力列表和万能条款。
保持技能自包含；仅当所请求的工作流确实需要且目标环境中可用时，才引用其他技能或工具。专门的审查、加固或审计工作流应在请求或确实需要时应用，而不是仅仅因为普通工作触及了同一主题。
逐步披露细节。 将共同目的、基本约束和有用路由信息保留在SKILL.md中。将大量的模式特定指导、模式、示例或过程放在支持性引用文件中，并且仅读取与当前任务相关的引用。一个简单的自包含技能不需要路由器或额外文件。
技能的解剖结构
每个技能都是一个文件夹，包含一个必需的SKILL.md文件以及其实际工作流所需的任何可选资源：
skill-name/
|-- SKILL.md 必需技能指令
| |-- YAML 前置元数据 必需的名称和描述
| `-- Markdown 主体 使用技能时加载的指令
|-- agents/ 可选的UI元数据和调用策略
| `-- openai.yaml
|-- scripts/ 可选的可执行辅助脚本
|-- references/ 根据需要加载的可选文档
`-- assets/ 生成输出中使用的可选文件
选择适合实际任务的结构。有些技能简短且自包含；其他技能则在操作模式之间路由或将复杂机制委托给脚本。避免在没有明确用途的情况下创建目录、占位符、示例或辅助文档。
SKILL.md
YAML前置元数据标识技能并决定何时应考虑使用它。包含必需的name和description，并在适当时保留支持的可选字段，如现有的metadata。
Markdown主体仅在技能使用时加载。将目的、基本工作流、真实约束和有用链接放在那里。将详细过程和示例放在支持性引用文件中，当它们仅与特定模式相关时。
技能信息分三个阶段披露：
- 名称和描述： 在技能选择期间可用，因此保持它们简洁且具有区分性。
- SKILL.md主体： 在技能应用时加载，因此保持其指令与任务相关。
- 支持性资源： 仅当当前任务确实需要时才读取或执行。
入口点应在保留重要约束的前提下尽可能简短。大的上界不是目标：将条件性细节移入引用文件中，当这样做能提高清晰度或上下文利用率时，而不是等到文件变得难以管理。
脚本
使用scripts/来存放可执行代码，当相同的逻辑会被重复重写，或者确定性执行能显著提高可靠性时。
- 示例：
scripts/rotate_pdf.py用于PDF操作，否则需要重新创建相同的代码。 - 适用场景： 重复的转换、可靠的API操作、数据处理以及其他具体自动化。
- 验证： 运行新的或更改后的脚本以验证其行为。脚本通常可以在不将其完整实现加载到上下文中的情况下执行，尽管代理可能在修补或适配它们时需要检查它们。
引用
使用references/来存放仅在特定上下文中需要的文档。
- 示例： 数据库表的
references/schema.md、域规则的references/policies.md、API的references/api_docs.md，或针对不同交付物的独立写作指南。 - 适用场景： 模式、API文档、公司政策、格式特定过程、详细工作流以及大量示例。
- 路由： 从
SKILL.md或其他相关资源链接每个引用，并解释何时应读取它。将信息放在一个地方，而不是在入口点和引用之间重复。
保持引用专注于已维护的、任务特定的信息，这些信息会改变代理的决策。避免从权威来源复制的手册、详尽目录和通用教程。在删除现有资源之前，检查它们的调用者和用途。
对于大型引用，包含有用的搜索词或简短的内容部分，当这能使所需材料更容易找到时。
资源文件
使用assets/来存放属于生成输出而不是模型指令中的文件。
- 示例：
assets/logo.png、assets/slides.pptx、assets/font.ttf或assets/frontend-template/。 - 适用场景： 模板、图像、字体、图标、样板项目以及其他被复制或适配到结果中的文件。
- 上下文： 不要将资源文件作为指令加载，除非任务需要检查它们。
UI元数据和调用策略
agents/openai.yaml可以提供面向UI的元数据，如display_name、short_description和default_prompt，以及调用策略。在创建或更新这些设置时，请阅读references/openai_yaml.md并保持值与技能一致。
默认允许自动技能选择。仅当用户明确请求仅显式调用的技能时才更改该默认值：
policy:
allow_implicit_invocation: false
这使得技能在显式调用为$skill-name时可用，而不会自动将其添加到模型上下文中。在更新agents/openai.yaml时，保留不相关的现有UI、策略和依赖字段。
初始化程序会自动创建此文件。对于新的或仅接口的元数据，使用以下命令生成：
scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value
生成器会替换整个文件。如果现有文件包含policy或dependencies，则仅更新其中的预期字段，而不是重新生成。
仅当用户提供或请求时才包含可选的接口字段。
不应包含的内容
包含直接支持技能工作的文件。避免添加README.md、安装指南、变更日志、重复的快速参考或其他辅助文档，除非特定任务或打包要求需要它们。
实践中的渐进式披露
对于具有多个重要模式的技能，将共享指导和模式选择标准保留在SKILL.md中。在每个支持的引用文件变得相关的位置链接它。不要默认加载每个引用，不要将引用内容复制到入口点，也不要添加没有有意义路由的路由层。
例如，部署技能可以将供应商选择保留在SKILL.md中，并将单独的供应商详细信息放在：
cloud-deploy/
|-- SKILL.md
`-- references/
|-- aws.md
|-- gcp.md
`-- azure.md
当用户选择AWS时，读取references/aws.md；不要同时加载GCP和Azure指南。相同的模式可以分离业务领域、交付物类型或其他真正不同的操作模式。
一个简短的技能也可以仅在高级操作需要时才路由到细节：
## 文档
直接处理普通编辑。
- 对于跟踪更改，阅读[references/redlining.md](references/redlining.md)。
- 对于文档内部结构，阅读[references/ooxml.md](references/ooxml.md)。
这些示例说明了选项，而不是必需的结构。选择使技能更易于使用且不加载无关材料的组织方式。
创建或更新技能
使工作适应请求。创建复杂的新技能可能涉及理解实际用例、选择支持资源、初始化文件、编写指令以及验证结果。对现有技能的狭窄更新可能只需要集中编辑和验证。
仅当缺失的信息很重要且无法合理推断时才提出澄清性问题。尊重用户指定的位置；否则在$CODEX_HOME/skills中创建可发现的技能，当CODEX_HOME未设置时使用~/.codex/skills。
保持自动技能选择启用，除非用户明确请求仅显式调用的技能。当预期的调用模式确实不明确且对请求的工作流很重要时，询问用户是想要正常的自动发现还是仅显式调用；否则保留默认值。不要从敏感操作或所需批准推断仅显式调用：保持技能可发现，并在实际变更之前立即要求授权。除非用户要求更改，否则保留现有技能的调用策略。
对于新的或经过重大修订的技能，考虑它应该处理的实际请求，以及哪些可重用资源会改进这些任务：
- 重复的PDF转换可能需要一个
scripts/rotate_pdf.py辅助脚本。 - 应用程序构建工作流可能受益于
assets/frontend-template/启动器。 - 数据分析技能可能需要一个
references/schema.md指南，以避免重新发现表关系。
仅当这些资源的具体好处证明其合理性时才创建它们。如果用户已经清楚解释了任务，继续执行而无需请求额外示例。
命名
- 使用小写字母、数字和连字符。
- 保持名称在64个字符以内，并优先选择简短、面向操作的名称。
- 当能提高可发现性时，按工具或领域命名空间。
- 将技能文件夹命名为与技能相同的名称。
初始化新技能
对于新技能，使用捆绑的初始化程序，当它能一致地帮助创建所需文件时：
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 references
仅请求技能需要的资源目录。仅当具体占位符有帮助时才使用--examples，并在完成前替换或删除它们。不要重新初始化现有技能。
初始化程序会创建技能目录、一个简短的SKILL.md启动文件以及agents/openai.yaml。它仅在请求时创建资源目录和示例文件。在需要时将生成的UI值作为--interface key=value传递。
编写指令
前置元数据的description应简要解释技能的功能及其适用场景。当类似请求不应激活该技能时，包含一个有意义的边界。
例如：
description: 创建或编辑Word文档，当格式化、跟踪更改或注释需要文档特定处理时。
将详细工作流、工具选择、示例和操作模式放在主体或相关引用中，而不是全部列在描述中。在适当时保留支持的可选前置元数据，如现有的metadata。
仅编写另一个Codex实例执行任务所需的确切指令。陈述期望的结果、非显而易见的上下文、真实约束以及相关引用或工具。保留用户的明确选择和现有授权边界。当任务不要求固定结构、过程或步骤数时，避免规定它们。
验证和迭代
使用以下命令验证完成的技能：
scripts/quick_validate.py <path/to/skill-folder>
验证器检查前置元数据、命名和未完成的脚手架占位符；它不证明技能做出了好的决策。还要检查描述是否仍具有区分性、指令是否保留用户意图、引用是否可发现以及任何添加的脚本是否实际工作。
当需要测试时，验证可观察的行为或有意义的不变量。避免仅匹配生成的措辞、标题或正则表达式的测试。
根据实际使用或已证实的失败来改进技能。倾向于狭窄的修正，而不是积累适用于每一个变更的通用规则。