skill-creator

技能创建器

创建技能，为 Codex 提供有用且不显而易见的指导，同时不限制无关工作。

核心原则

假定 Codex 已具备相应能力。 只包含会改变其决策或提升其工作质量的信息。删去通用建议、重复指令、推测性的边缘情况，以及无法实质性澄清任务的示例。

保留用户意图和范围。 技能应支持用户请求的任务，而不是替换用户选择的产品、扩大任务范围、修改无关配置，或暗示获得了执行额外外部操作的许可。不要将某个特定示例、过往失败或个人偏好变成通用要求。

获准完成一项任务，并不意味着任务范围或执行权限随之扩大。对于重试或会产生外部变更的工作流，应根据风险设定适当的停止条件。

让具体程度与风险相匹配。 当存在多种合理方案时，应给模型留出选择合适方案的空间。只有在正确性、安全性、权限或确实脆弱的工作流要求时，才使用详细步骤、确定性脚本或绝对措辞。

对于开放式工作，描述预期结果和相关决策标准。对于有首选形式的工作流，提供有用示例或可配置脚本。只有在偏离会导致具体问题的操作中，才规定固定顺序和严格参数。保留不显而易见的操作不变量，区分实际要求与可选建议或本地惯例，并避免重复陈述其他地方已强制执行的策略。

让发现过程简洁且精准。 技能名称和描述会在技能加载前提供。说明其实际能力和适用场景；只有在能防止可能的错误路由时，才补充排除情况。避免详尽罗列能力或使用会吸引无关请求的兜底描述。

保持技能自包含；只有在请求的工作流确实需要，且目标环境中存在相应技能或工具时，才引用它们。仅仅因为常规工作涉及相同主题，不代表应启用专门的审查、加固或审计工作流；只有在用户请求或确有需要时才应用这些工作流。

逐步披露细节。 在 SKILL.md 中保留共同目标、必要约束和有用的路由信息。将大量特定模式的指导、架构、示例或流程放入辅助参考文件，并且只读取与当前任务相关的参考文件。简单且自包含的技能不需要路由器或额外文件。

技能的组成

每项技能都包含一个文件夹，其中有必需的 SKILL.md 文件，以及其实际工作流所需的可选资源：

skill-name/
|-- SKILL.md                 Required skill instructions
|   |-- YAML frontmatter     Required name and description
|   `-- Markdown body        Instructions loaded when the skill is used
|-- agents/                  Optional UI metadata and invocation policy
|   `-- openai.yaml
|-- scripts/                 Optional executable helpers
|-- references/              Optional documentation loaded as needed
`-- assets/                  Optional files used in generated output

选择适合实际任务的结构。有些技能简短且自包含；另一些则会在不同操作模式间进行路由，或通过脚本处理复杂机制。不要在没有明确用途的情况下创建目录、占位文件、示例或辅助文档。

SKILL.md

YAML frontmatter 用于标识技能，并决定何时应考虑使用它。请包含必需的 name 和 description，并在适当时保留现有的 metadata 等受支持的可选字段。

只有在使用技能时，才会加载 Markdown 正文。请在正文中说明用途、核心工作流、实际约束和有用链接。仅在特定模式下才相关的详细流程和示例，应放在配套参考资料中。

技能信息分三个阶段披露：

1. 名称和描述： 在选择技能时可见，因此应简洁且具有区分度。
2. SKILL.md 正文： 在技能适用时加载，因此其中的说明应与该任务相关。
3. 配套资源： 仅在当前任务确实需要时读取或执行。

入口文件应在保留重要约束的前提下尽可能简短。较大的上限不代表目标：如果将有条件的详细内容移至参考资料能提升清晰度或节省上下文，就应这样做，而不是等到文件变得难以管理时才处理。

脚本

如果同一逻辑原本需要反复重写，或通过确定性执行能显著提高可靠性，请使用 scripts/ 存放可执行代码。

• 示例： 对于需要反复实现相同代码的 PDF 操作，可使用 scripts/rotate_pdf.py。
• 适用场景： 重复转换、可靠的 API 操作、数据处理及其他具体的自动化任务。
• 验证： 运行新建或修改过的脚本，验证其行为。通常无需将脚本的完整实现加载到上下文中即可执行，不过在修补或调整脚本时，Agent 可能需要检查其内容。

参考资料

对于仅在特定情境下才需要的文档，请使用 references/。

• 示例： 数据库表可放在 references/schema.md，领域规则可放在 references/policies.md，API 文档可放在 references/api_docs.md，不同交付物的写作指南也可分别存放。
• 适用场景： 架构、API 文档、公司政策、特定格式的流程、详细工作流和大量示例。
• 引用方式： 从 SKILL.md 或其他相关资源中链接每份参考资料，并说明何时应阅读。请将信息集中存放，避免在入口文件和参考资料中重复。

参考资料应聚焦于经过维护且与任务相关、会影响 Agent 决策的信息。避免复制手册、罗列详尽目录，以及重复权威来源中已有的通用教程。删除现有资源前，请先检查其调用方和用途。

对于较大的参考资料，如果提供有用的搜索词或简短目录能让所需内容更容易查找，请添加这些内容。

资源文件

对于应包含在生成结果中的文件，请使用 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 指南。同样的模式也适用于区分业务领域、交付物类型或其他真正不同的操作模式。

对于简短的技能，也可以仅在需要执行高级操作时，才引导用户查看详细信息：

## Documents

Handle ordinary edits directly.

- For tracked changes, read [references/redlining.md](references/redlining.md).
- For document internals, read [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 传入。

编写说明

frontmatter 中的 description 应简要说明技能的用途及适用场景。如果类似请求不应触发该技能，还应明确适用边界。

例如：

description: Create or edit Word documents when formatting, tracked changes, or comments require document-specific handling.

将详细工作流、工具选择、示例和操作模式放在正文或相关参考资料中，而不是全部罗列在描述里。适当时保留受支持的可选 frontmatter，例如现有的 metadata。

仅编写其他 Codex 实例高效完成任务所需的说明。说明预期结果、不明显的背景信息、实际约束，以及相关参考资料或工具。保留用户明确提出的选择和现有授权边界。当任务不需要固定结构、流程或步骤数量时，不要强行规定。

验证并迭代

使用以下命令验证已完成的技能：

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

验证器会检查 frontmatter、命名和未完成的脚手架占位符；但它无法证明技能能否做出良好的决策。还要检查描述是否仍能区分不同技能、指令是否保留了用户意图、参考资料是否易于查找，以及新增脚本是否确实可运行。

需要测试时，请验证可观察到的行为或有意义的不变量。避免仅匹配生成措辞、标题或正则表达式模式的测试。

根据实际使用情况或已证实的问题改进技能。优先进行范围明确的修正，而不是针对每个已观察到的示例不断增加通用规则。

独立前向测试

当技能足够复杂或风险较高，且真实行为验证能够显著提升信心时，如果可以委派且已获授权，请使用独立的子 Agent 进行评估。常规创建或小幅编辑并不自动要求使用子 Agent。

向评估 Agent 提供真实的用户请求、技能以及完成任务所需的最少原始材料。不要提供预期答案、怀疑存在的问题、建议的修复方案或先前结论，除非评估确实需要这些信息。

例如：

Use $skill-name at /path/to/skill-name to complete this realistic request.

评估范围应限于获准使用的资源和副作用。生成的材料应放在隔离的临时工作区中，避免进入工作树或污染后续评估。如果拟议的评估需要额外授权、会影响生产环境，或会耗费大量时间或成本，请先征求批准。检查实际结果和产物，然后仅根据观察到的行为进行修改。