用途：创建或更新 Codex skill，让技能给出有用且非显而易见的指导，同时不约束无关工作。资料强调只为改变模型决策或改善结果的信息编写指令，去掉通用建议、重复指令、推测性边缘情况和没有实质澄清作用的示例。
核心原则：默认 Codex 已有能力；保留用户意图与范围，技能应支持请求的任务而非替换用户选择、扩大任务、修改无关配置或暗示额外外部操作权限；完成任务不等于扩大范围或执行权限；重试或外部变更工作流要设定与风险相称的停止条件；按风险匹配具体程度；开放式工作描述结果与决策标准，固定流程只用于偏差会造成具体问题的操作；保留非显而易见的操作不变量，区分真实要求与可选建议；技能名称与描述在加载前可见，应简洁且具区分度；技能保持自包含，仅在确实需要且环境可用时引用其他技能或工具；渐进披露，常驻内容放 SKILL.md，模式专属细节放参考文件，只读当前任务相关的参考。
结构：每个技能是包含必需 SKILL.md 的文件夹，可选 agents/、scripts/、references/、assets/。SKILL.md 含 YAML frontmatter（必需 name 与 description）与 Markdown 正文。信息分三阶段披露：名称与描述用于选择；SKILL.md 正文在技能适用时加载；支撑资源仅在任务需要时读取或执行。scripts/ 用于重复逻辑或需要确定性执行的代码，新增或修改后应运行验证；references/ 用于特定上下文文档，需从 SKILL.md 链接并说明何时阅读；assets/ 用于生成输出中的文件，不应作为指令加载。
UI 元数据与调用策略：agents/openai.yaml 可提供 display_name、short_description、default_prompt 与调用策略；自动选择默认允许，仅当用户明确要求 explicit-only 时设 policy: allow_implicit_invocation: false；更新时保留无关字段。新建或仅界面元数据可用 scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value 生成，但该生成器会替换整个文件。
创建与更新：适应请求调整工作量；仅在缺失信息重要且无法合理推断时提问；尊重用户指定位置，否则创建到 $CODEX_HOME/skills，未设置时用 ~/.codex/skills。命名用 lowercase 字母、数字、连字符，少于 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"。frontmatter 描述简述用途与适用时机，必要时给边界。完成后用 scripts/quick_validate.py <path/to/skill-folder> 验证 frontmatter、命名与未完成占位符，但不保证决策质量。复杂或有风险时可在授权下用独立子代理前向测试，给出真实用户请求、技能与最少必要工件，不提供预期答案或修复建议，使用隔离临时工作区。
限制：不要添加 README、安装指南、变更日志或重复速查等辅助文档，除非具体任务或打包要求需要；不要无明确用途地创建目录、占位符、示例或附属文档；不要为每个案例累积通用规则；不要默认加载所有参考文件或复制参考内容；不要从敏感操作或需审批推断 explicit-only 调用。