create-agent-skill

创建 Agent 技能

边界

• 在对话中回答仅涉及规划的请求：计划、设计、评审、大纲、需求以及技能结构讨论。对于混合请求，先确定计划；实施路径明确后再写入文件。
• 将用户提到的工具、技能、框架和工作流视为规划背景；只有用户明确要求时才开始创建文件。如果用户是否有意写入文件不明确，且编辑可能出乎意料，请先询问。
• 要评审现有技能文件时，请依据本技能的规则进行检查，并在对话中报告发现的问题。
• 用户要求评估、精简或迭代现有技能时，请加载 references/evaluating-skills.md。

工作流

1. 确认范围。

   • 确定要创建或更新的具体产物：技能目录、SKILL.md、参考资料、脚本、资源或清单文档。
   • 确定该技能涵盖的任务、工作流、项目约定或领域。
   • 对于用于打包用户反复输入的指令的快捷方式，跳过步骤 2–5 和 7：按照步骤 3 为其命名，添加供用户调用且带有单行描述的 frontmatter，将指令写入正文，然后执行步骤 6。
   • 收集应触发该技能的提示词、上下文、文件和工作流，以及不应触发它的相邻请求和相似但不适用的情况。

2. 收集并分配材料。

   • 以已完成的任务、用户纠正、项目文档、运行手册、架构、评审意见、问题或补丁为依据。收集需要保留的参考材料。
   • 将经验写成指令前，先检查是否能通过 lint 规则、类型、运行时检查或脚本来强制执行。如果能在技能自身的产物中实现这类强制执行（例如打包的脚本或 hook），就将其放入其中，并省略相应的文字规则；如果应在目标仓库中实现，则提出建议，不要越权修改技能以外的内容。
   • 将判断和审批与机械步骤分开。根据“脚本”部分，将每个机械步骤分配给脚本或直接调用，然后选择配套的参考资料、资源、模板或示例文件。

3. 选择技能名称和位置。

   • 目录名称应与 name 字段一致：由 1–64 个小写字母、数字和单个连字符组成，且必须以字母或数字开头和结尾。

4. 编写 SKILL.md。

   • 以 YAML frontmatter 开头，至少包含 name 和 description。
   • 仅在 license、compatibility、metadata 或 allowed-tools 等可选字段能提供信息时添加它们。
   • 仅当 Agent 必须自行调用该技能，或其他技能必须加载该技能时，才将该技能设为由模型调用。其描述会始终保留在上下文中；请按照 Description pattern 一节的说明编写。否则，设置 disable-model-invocation: true，使用面向用户的一行描述，不列出触发条件，并添加 agents/openai.yaml，将 policy.allow_implicit_invocation 设为不带引号的 false，因为 Codex 会忽略 frontmatter 字段。输入技能名称仍可调用该技能。
   • 当用户调用的技能变得难以记住时，建议创建一个由用户调用的路由技能，列出其他技能并说明各自的使用时机。每当添加、重命名或移除路由技能时，都要更新路由技能。
   • 不要在正文中重复描述。若技能需要描述无法涵盖的激活规则或范围规则，请将其放入 ## Boundaries 一节；如果描述已经足够清楚，则省略该节，并在工作流步骤中规定执行默认设置。
   • 正文重点写流程、默认设置、示例、注意事项、脚本和验证步骤。
   • 明确说明一次完整运行的交付内容；如果工作可能以多种方式结束，请列出所有终止结果。对于审计、评审和维护技能，应将“没有值得修改的内容”作为完整结果，无需填充报告。
   • 用首部词锚定重复出现的概念：选用用户提示和领域中已有的简短术语，并在描述和正文中始终将其作为同一词项重复使用。将拼写展开的枚举和释义归并到该词项。
   • 为工作流步骤设置可检查的完成条件（如有明确条件），并优先使用详尽表述（例如“已审阅每个变更文件”），而非含糊表述（例如“审阅变更”）。对于没有客观标准的判断步骤，不要强行设定人为指标，而应在最终验证步骤中通过具体检查涵盖其结果。
   • 正文每一行都应面向执行技能的 Agent。省略编写理由、请求历史以及对技能结构的解释。
   • 避免依赖时效性信息，除非技能会指导 Agent 如何更新这些信息。
   • 优先编写无需安装其他技能即可使用的技能。如果工作流确实需要其他技能，请在相应步骤中点名并指示 Agent 加载该技能，而不是复制或概述其指导内容。

5. 应用渐进式披露。

   • 将每次运行都需要的内容保留在 SKILL.md 中。仅某些分支需要的材料应移至辅助文件，并通过指明加载该文件的分支来引用。
   • 引用时使用纯路径，例如 references/evaluating-skills.md，并在正文中指明章节名称，例如“Scripts 一节”。Markdown 链接语法会在标签和 URL 中重复目标路径。
   • 将约 100 行非空正文视为提示：内联材料可能应移至引用文件中；这不是硬性限制或目标。完整性和正确性优先于篇幅。
   • 范围狭窄、仅包含指令的技能无需辅助文件：一个 SKILL.md 即可，只需包含覆盖 Agent 可能判断错误的决策的最短工作流，以及仅在能避免常见错误时才加入的注意事项、示例和验证步骤。
   • 将详细文档移至 references/，将可复用模板、图片、示例文件或静态数据移至 assets/；scripts/ 由 Scripts 一节管理。辅助资源应相对于技能目录保持一层深度。

6. 润色指令文本。

   • 加载 refine-it，然后加载 shorten-it，并对每个新建或编辑的指令文件全文依次运行两者。
   • 将润色文本与润色前的版本进行比较，并还原任何会改变触发条件、要求、权限、工作流顺序或其他操作含义的改动。若两轮润色都没有改善措辞，则保持原样。

7. 审核结果。

   • 如果范围不明确，或技能包含特定领域的偏好，请提供草稿。询问它是否涵盖了相关用例、有哪些遗漏或不清楚之处，以及哪些内容应更详细或更简略。
   • 确保 SKILL.md 与辅助文件中的术语保持一致。
   • 对照 Scripts 部分检查每个机械步骤。根据随附脚本核实文档中说明的参数和输出。
   • 对于由模型调用的技能，使用实际的正向提示词和容易混淆的负向提示词检查描述是否合理。修改过于宽泛或过于狭窄的表述。
   • 如果正式评估（例如触发测试或对比运行）会有帮助，可建议用户将其作为下一步；不要在此工作流中手动运行评估。

描述模式

对于由模型调用的技能，描述应少于 1024 个字符，使用第三人称，并遵循以下结构：

description: [What the skill enables]. [Conditions that invoke it: specific user intents, keywords, contexts, or file types].

在第一句说明技能的作用，并优先使用用户实际输入的词汇。在第二句说明调用条件，每个不同分支对应一个触发条件。合并同一分支的同义词，并省略第一句已经涵盖的细节。描述应面向模型调用；用户可以按名称调用任何技能。只有当触发条件会误触发时，才添加排除条件。

建议：

description: Reviews accessibility issues in React interfaces and suggests concrete fixes. Use when the user asks for accessibility review, WCAG checks, keyboard navigation fixes, or ARIA guidance for React components.

避免含糊，也不要在一个分支中堆砌同义词：

description: Helps with accessibility.

description: ... Use when the user asks to review, check, audit, inspect, examine, or assess accessibility.

脚本

• 如果脚本能将多轮工具调用合并为一次、处理排序、精确标志或清理工作，避免 Agent 犯错，将冗长输出压缩为下一步决策所需的信息，或强制执行原本需要在技能说明中用文字表述的规则，则应将机械步骤编写为脚本。
• 如果脚本没有明显收益，则直接调用：如果 Agent 能根据技能文本用一条 shell 命令正确运行该步骤（包括调用现有工具），或者为工作流变体设置标志所带来的成本高于直接调用，则应直接调用。
• 判断和授权应由 Agent 掌握。脚本必须明确报告会影响下一步决策的失败。
• 如果将多个脚本打包，应确保它们独立完整、非交互、可重复运行且具幂等性，并且能从技能根目录使用相对路径运行。
• 为脚本提供简洁的 --help、有用的错误提示、有意义的退出码、安全的默认值，以及仅包含下一步决策所需信息的结构化标准输出。将完整日志写入文件并打印其路径。不要将完整日志输出到标准错误，因为这同样会占用上下文。
• 对于破坏性操作或会更改状态的操作，应提供试运行或明确的确认标志。
• 在每个随附脚本的调用位置，说明 Agent 无需另行查阅帮助即可运行脚本所需的必选和可选参数、默认值、输出及退出行为。确保这些说明与脚本保持一致；实现细节留在代码中。
• 交付前，端到端运行一次所有随附脚本和精确命令。通过试运行、帮助或确认流程，或针对一次性测试数据，验证破坏性操作或会更改状态的操作；绝不能对真实目标执行这些操作。

起始结构

---
name: skill-name
description: Does a specific reusable task. Use when the user asks for concrete intents, contexts, or file types that should trigger this skill.
---

# Skill name

## Workflow

1. Follow the domain-specific procedure.
2. Use the default tool or format; mention alternatives only as escape hatches.
3. Validate output and fix failures before finalizing.

## Gotchas

- State the correct behavior for a case the agent gets wrong by default; name the mistake itself only when the correct form alone won't prevent it.

质量标准

• 技能是一个连贯、可复用的工作单元，而不是通用知识的堆砌。
• 指令涵盖 Agent 在没有该技能时可能会出错的地方。
• 工作流将相互独立的操作合并到一轮工具调用中。在需要判断或用户授权的步骤处停止批处理，并让失败清晰可见。
• 将环境得出的事实留在所属环境中。记录环境无法提供的未成文惯例、原因和注意事项。
• 每条指令都应在某些情况下改变行为。删去 Agent 无法据此采取不同做法的句子，例如“检查你的工具”“自行判断”或“务必仔细”，以及重复陈述环境已有保证的模糊措辞。
• 说清要执行的操作，而不是 Agent 自行完成该操作的步骤：“应用 references/x.md”，而不是“阅读并应用 references/x.md”。只有在 Agent 否则可能跳过或颠倒顺序时，才写明子步骤。
• 每条规则只在适用之处说明一次。删除技能其他位置对规则的重复说明，包括仅仅否定工作流中已有规则的注意事项。
• 将一个概念的定义、规则和注意事项放在同一个标题下。
• 明确默认做法；只有在会影响决策时才列出替代方案。
• 每条禁令都要说明应采取什么替代做法。
• 对容易出错的操作，保留规定性步骤；对于灵活的任务，说明意图即可。
• 纳入示例时，应确保具体且切合实际，并通过验证捕捉常见错误。