如何设计一个优秀的 Skill V2优秀的 Skill本质上是把某个领域的专家经验、工作流、工具使用方式和质量标准工程化沉淀变成一套 AI agent 可以稳定执行、按需扩展、失败可控、结果可验证的能力包。相比普通 PromptSkill 不是一次性的表达技巧而是可复用的标准作业程序。它要让 Codex 在同类任务上少摸索、少犯错、少浪费上下文并在关键时刻知道何时继续、何时追问、何时停止。一个优秀 Skill 至少要回答七个问题什么时候应该触发这个 Skill这个 Skill 负责什么不负责什么Codex 应该按什么流程执行缺少信息时应该怎样向用户提问失败、部分成功或高风险操作时如何处理哪些资源、脚本、参考资料应按需加载如何验证这个 Skill 的输出质量一、Skill 的核心定位Skill 解决的是“怎么做更稳”的问题。Tool 解决“能不能做”例如搜索网页、读取文件、调用 API、操作浏览器。Prompt 解决“这一次怎么表达”适合临场、轻量、一次性任务。Skill 解决“同类任务以后怎么稳定做”适合高频、复杂、有专家差距、有验证要求的任务。好的 Skill 不是把所有知识塞进一个长文档而是把最关键的执行策略、路由规则、边界条件和验证标准放在 Codex 能够及时使用的位置。二、Skill 的标准结构一个标准 Skill 通常是一个文件夹至少包含一个SKILL.md文件skill-name/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── scripts/ ├── references/ └── assets/只有SKILL.md是必需的其余目录按需添加。1.SKILL.mdSKILL.md是 Skill 的入口由 YAML frontmatter 和 Markdown 正文组成--- name: skill-name description: Clear description of what this skill does and when to use it. --- # Skill Title Instructions for Codex...frontmatter 中只应包含必要字段nameSkill 的唯一标识使用小写字母、数字和连字符。descriptionCodex 判断是否触发 Skill 的主要依据。description必须同时说明能做什么。何时使用。适用的文件、工具、任务或业务场景。关键排除场景。不要把“什么时候使用这个 Skill”只写在正文里因为正文只有在 Skill 已经触发后才会被读取。2.agents/openai.yaml推荐添加用于 UI 展示 Skill 信息。常见字段display_name用户可读名称。short_description一句话说明。default_prompt用户可直接使用的默认请求。这些字段应和SKILL.md保持一致。更新 Skill 后要检查 UI 元数据是否已经过期。3.scripts/用于存放可执行脚本。适合以下场景操作需要确定性和可重复性。每次让 Codex 手写代码容易出错。任务涉及格式转换、批处理、渲染、校验、迁移、打包等机械流程。脚本必须经过代表性测试。进入 Skill 的脚本应被视为长期可复用组件而不是临时草稿。4.references/用于存放按需读取的详细资料。适合放置API 文档。数据库 schema。公司政策。领域知识。复杂流程说明。不同平台、框架、供应商的专门指南。SKILL.md应当只保留路由规则和核心流程详细内容放入references/。每个引用文件都应在SKILL.md中被明确提到并说明何时读取。5.assets/用于存放产出中会使用的资源而不是给 Codex 阅读的资料。例如模板文件。Logo。字体。图片。示例项目。可复制的工程骨架。三、什么任务适合做成 Skill并非所有任务都值得封装为 Skill。适合做成 Skill 的任务通常有以下特征高频重复经常发生值得维护一套固定流程。专家差距大熟手和新手产出差异明显。流程复杂需要多步判断单次 Prompt 难以稳定完成。输入输出清晰能描述需要什么材料、交付什么结果。风险较高出错会造成返工、数据问题、格式损坏或业务风险。需要验证不能只生成结果还要检查结果是否正确。需要工具协同需要脚本、API、浏览器、文档渲染或文件处理。不适合做成 Skill 的任务一次性闲聊。没有稳定流程的开放式探索。过于宽泛的“帮我提高效率”。Codex 默认能力已经足够、且没有额外约束的简单任务。四、设计 Skill 的七步流程第一步收集真实任务先找 3 到 5 个真实案例覆盖成功、失败、信息不足、边界情况。不要只问专家“你的方法论是什么”而要追问具体动作你拿到材料先看哪里什么信号会让你停下来追问哪些错误是新人经常犯的遇到例外情况你怎么处理做完后你怎么验收目标是提炼可执行流程而不是写经验散文。第二步用 IPO 模型定义任务像设计函数一样设计 Skill。输入 Input用户必须提供什么Codex 可以主动读取什么哪些信息缺失时不能开始哪些假设可以默认哪些必须确认处理 Process标准执行顺序是什么哪些地方需要分支判断哪些步骤必须严格执行哪些步骤允许自由发挥输出 Output最终交付物是什么输出格式是什么文件保存在哪里是否需要报告、日志、摘要或验证结果边界 Boundary哪些情况不属于这个 Skill哪些情况必须暂停并询问用户哪些情况应该交给另一个 Skill 或工具第三步设计信息搜集协议优秀 Skill 不能只规定“做什么”还要规定“信息不够时怎么问”。提问策略应区分三类场景。一次性追问适合缺少多个独立信息。适合用户容易一次性补齐的配置项。适合减少往返轮次。示例Before starting, ask for: target environment, input file path, desired output format, and whether existing files may be overwritten.逐步澄清适合需求本身还模糊。适合用户可能不知道专业选项。适合需要先根据第一轮回答决定后续问题。示例If the users goal is ambiguous, ask one clarifying question first. After the answer, choose the workflow branch.选项式提问尽量提供 2 到 4 个明确选项。每个选项说明影响。避免让用户面对完全开放的问题。示例Ask the user to choose: strict format preservation, content-only conversion, or visual redesign.关键假设确认覆盖、删除、迁移、发布、生产环境操作前必须确认。高成本或不可逆操作前必须复述即将执行的动作。示例Before overwriting files, restate the target paths and ask for explicit confirmation.第四步规划资源和渐进式披露渐进式披露的目标是让 Codex 只加载当前任务真正需要的信息。推荐三层结构元数据name和description始终在上下文中。SKILL.md正文触发后加载只放核心流程和路由。资源文件按需读取或执行。SKILL.md应尽量短建议控制在 500 行以内。能放进references/的细节不要塞进正文。特别大的引用文件应有目录或摘要。资源路由要写成强指令而不是弱建议。弱路由For AWS details, see references/aws.md.强路由If the user mentions AWS deployment, load references/aws.md before choosing commands.对于大引用文件在SKILL.md中加入短摘要帮助 Codex 判断是否需要读取- references/aws.md: AWS deploy paths, IAM assumptions, rollback rules, and CloudWatch verification.避免深层引用。所有关键 reference 最好都从SKILL.md直接链接不要让 Codex 需要层层寻找。第五步设置自由度根据任务风险决定 Skill 的约束强度。高自由度适合文案、头脑风暴、方案比较。给原则和启发式规则即可。中自由度适合有推荐流程但允许调整的任务。可提供伪代码、参数表、分支规则。低自由度适合文件格式脆弱、生产系统、批量迁移、合规流程。应提供脚本、固定命令、校验步骤、回滚策略。原则越脆弱、越高风险、越需要一致性就越应该降低自由度。第六步设计失败处理和回退机制复杂任务中失败和部分成功是常态。优秀 Skill 必须定义状态、检查点和升级条件。建议在 Skill 中区分四种状态Not started尚未执行会先检查输入和权限。In progress正在执行应记录关键中间状态。Partial success部分完成必须说明完成了什么、未完成什么。Failed safely失败但保留现场不掩盖错误不继续猜测。长链条任务应设计检查点每完成一个阶段确认产物或状态。对批量操作记录已处理项和未处理项。对文件修改保留可比较的 diff 或输出路径。对迁移、发布、覆盖类任务说明回退方式。幂等性设计脚本重复运行不应造成重复写入、重复发布或重复删除。如果无法保证幂等必须在 Skill 中写明运行前检查和人工确认条件。升级条件遇到 references 未覆盖的例外。置信度不足。输入和用户目标冲突。验证失败且无法定位原因。继续执行可能造成数据丢失、覆盖、发布或权限风险。这些情况应暂停并询问用户而不是自行猜测。第七步设计验证和评测Skill 不应只规定如何产出还要规定如何证明产出可靠。单次任务验证运行测试。执行校验脚本。渲染并目视检查。比较 schema 或格式。检查命令退出码。检查目标文件是否存在。报告验证命令和结果。Skill 开发期评测建议维护一个开发用 eval suite。eval suite 可以放在 Skill 包外部避免污染正式 Skill。选择 10 到 20 个典型请求覆盖正常、缺参、边界、失败场景。可量化指标任务成功率。首轮正确率。关键步骤遗漏率。平均交互轮次。验证通过率。失败后是否正确暂停或升级。对于确定性强的 Skill可以维护 golden checklist必须执行的步骤。必须读取的资源。必须生成的文件。必须报告的验证结果。不允许发生的行为。五、优秀 Skill 的核心特征1. 触发精准description应清楚说明能力、对象、场景和排除条件。不推荐description:Helps with documents.推荐description:Create,edit,inspect,render,and verify professional .docx documents,including formatting,comments,tracked changes,templates,and visual QA. Use when Codex needs to work with Word documents or Google Docs-targeted document artifacts. Do not use for PDFs or live Google Docs editing.2. 职责单一每个 Skill 最好只做一类事情。职责越清晰触发越稳定维护越容易。如果一个 Skill 必须覆盖多个分支应让SKILL.md做路由把分支细节拆到references/。3. 工作流明确优秀 Skill 应提供清晰的行动顺序## Workflow 1. Inspect the request and inputs. 2. Identify the task branch. 3. Load the required reference. 4. Execute the smallest sufficient change. 5. Validate the output. 6. Report output path, validation result, and unresolved risks.4. 输入输出明确Skill 应像函数一样定义输入和输出。输入用户提供什么Codex 自动读取什么缺什么必须问。输出交付物、格式、路径、日志、验证结果。验收什么条件下可以宣称完成。5. 交互策略明确优秀 Skill 应告诉 Codex 怎样和用户协作何时一次性追问。何时逐步澄清。何时提供选项。何时复述关键假设并等待确认。6. 失败可控Skill 应规定失败后的动作重试。回滚。保存中间产物。报告部分成功。暂停并询问用户。交给更合适的 Skill 或工具。7. 验证闭环完整凡是会生成文件、修改代码、转换格式、查询数据、部署系统的 Skill都应包含验证步骤。验证不是附加项而是完成条件的一部分。8. 上下文经济Skill 应尊重上下文窗口SKILL.md放核心流程和路由。大段知识放references/。稳定操作放scripts/。输出素材放assets/。不创建 README、CHANGELOG、安装手册等无关文件。9. 可组合但不混乱复杂任务可能触发多个 Skill。优秀 Skill 应说明和其他 Skill 的边界。可以在正文中写If the task requires PDF rendering after document generation, use the PDF skill only for rendering and visual inspection. Keep this skill responsible for DOCX authoring decisions.当多个 Skill 冲突时Codex 应先识别主任务再决定主 Skill如果无法判断应向用户确认。10. 可评测、可迭代优秀 Skill 应能被真实任务检验。每次失败都应反向更新触发描述。工作流。资源路由。验证标准。失败处理。示例和评测用例。六、多 Skill 协同与冲突仲裁复杂任务经常需要多个 Skill 接力。设计 Skill 时应避免让它成为孤岛。1. 明确主 Skill当用户请求跨多个能力域时先判断主目标。示例“把 DOCX 转成 PDF 并检查排版”主 Skill 是文档处理PDF Skill 用于渲染验证。“审查代码并生成变更说明”主 Skill 是代码审查文档生成只是输出格式。“生成数据报告并制作 PPT”主 Skill 取决于用户更重视数据分析还是演示产物。2. 声明边界Skill 可以写明何时把子任务交给另一个 Skill。自己只负责哪部分决策。冲突时以哪个 Skill 为准。3. 冲突检测当两个 Skill 的指令冲突时应按以下顺序处理用户明确要求优先。安全和数据保护优先。主任务 Skill 优先。更具体的 Skill 优先。仍无法判断时询问用户。七、资源设计原则1.SKILL.md只放必要内容应放核心工作流。资源路由。关键约束。交互策略。失败处理。验证要求。不应放长篇背景。大量示例。全量 API 文档。变更日志。人类教程。2.references/放详细知识适合拆分方式references/ ├── aws.md ├── gcp.md ├── azure.md ├── schema.md └── edge-cases.md每个 reference 应只覆盖一个主题。超过 100 行的 reference 建议在开头加入目录。3.scripts/放确定性操作适合脚本化的任务文件转换。批处理。结构校验。渲染检查。API 调用封装。重复生成固定格式产物。脚本应提供参数说明。清晰错误信息。非零退出码。可重复运行策略。4.assets/放输出素材适合放模板。图片。字体。示例工程。可复制的 boilerplate。这些资源一般不需要被完整读入上下文。八、优秀SKILL.md模板--- name: example-skill description: Do X, Y, and Z for [domain/tool/file type]. Use when Codex needs to [specific task], [specific task], or [specific task]. Do not use for [excluded scenario]. --- # Example Skill ## Workflow 1. Inspect the user request and available inputs. 2. Identify the task branch and risk level. 3. If required information is missing, follow the clarification protocol. 4. Load only the reference files required by the selected branch. 5. Use bundled scripts for deterministic or fragile operations. 6. Validate the result before reporting completion. 7. Report outputs, validation results, assumptions, and unresolved risks. ## Clarification Protocol - Ask one question at a time when the users goal is ambiguous. - Ask a grouped checklist when several independent configuration values are missing. - Prefer concrete options over open-ended questions. - Before destructive or irreversible actions, restate the target action and wait for confirmation. ## Resource Routing - If task A is requested, load references/a.md. - If task B is requested, load references/b.md. - If deterministic conversion is required, run scripts/convert.py. - If an output template is required, use assets/templates/. ## Failure Handling - If validation fails, inspect the error, fix the issue, and rerun validation. - If the operation partially succeeds, report completed and incomplete items separately. - If continuing may cause data loss or production impact, pause and ask the user. - Preserve intermediate artifacts when they help diagnosis. ## Validation Before completion, confirm: - The output exists. - Required commands or scripts exited successfully. - Format, schema, or visual checks passed when relevant. - Any assumptions or skipped steps are reported.九、常见反模式1.description太泛“Helps with documents” 这种描述无法稳定触发。应写清楚任务、对象、场景和排除条件。2. 把正文写成百科Skill 不是知识库全文。SKILL.md应是路由和操作手册详细知识放到references/。3. 只写成功路径真实任务经常缺信息、失败或部分成功。Skill 必须包含失败处理和升级条件。4. 缺少交互策略只写“缺信息时询问用户”不够。应说明什么时候问、怎么问、问几个问题、是否提供选项。5. 没有验证闭环没有验证步骤的 Skill 容易让 Codex 过早宣布完成。验证应是完成条件。6. 脚本没有测试脚本进入 Skill 后会被反复使用。至少应通过代表性输入测试并输出清晰错误信息。7. 多 Skill 边界不清如果 Skill 不说明边界复杂任务中容易出现多个 Skill 抢主导、指令冲突、上下文浪费。8. 上下文浪费把长篇说明、重复示例、全量文档都放进SKILL.md会降低 Codex 处理真实任务的空间。十、优秀 Skill 检查清单设计完成后用下面的清单自查SKILL.md是否存在frontmatter 是否只包含name和descriptionname是否短小、合法、和文件夹名一致description是否明确说明能力、触发场景和排除场景正文是否以工作流为主是否定义输入、处理、输出和边界是否包含信息搜集和澄清协议是否包含高风险操作确认规则是否使用渐进式披露大段资料是否移动到references/是否说明何时读取哪个 reference稳定重复操作是否做成scripts/脚本是否经过代表性测试输出资源是否放在assets/是否包含失败、部分成功和升级处理是否包含验证步骤和完成标准是否说明多 Skill 协同时的边界是否避免 README、CHANGELOG、安装手册等无关文件是否避免重复内容是否面向 Codex 编写而不是面向人类教程是否有真实任务或 eval suite 进行验证十一、判断一个 Skill 是否优秀的标准一个优秀 Skill 应该让 Codex 在同类任务上表现出触发更准知道什么时候用什么时候不用。行动更稳按明确流程执行而不是临场猜测。交互更少但更有效缺信息时问得具体、及时、低负担。失败更可控部分成功、失败、回退、升级都有规则。上下文更省只加载当前任务需要的信息。输出更可靠验证是完成条件的一部分。组合更清晰知道自己和其他 Skill 的边界。迭代更容易有评测用例和质量指标支撑改进。最终标准很简单如果没有这个 SkillCodex 需要重新摸索有了这个 SkillCodex 可以稳定、快速、可验证、可回退地完成同类任务。这就是一个优秀 Skill。