SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场creating-skills

creating-skills

智能体与模型

查看项目

更新于 10-16 04:09

技能介绍

用途

creating-skills 是一个用于创建新智能体技能并迭代改进它们的技能，合并自 Anthropic 的 skill-creator 与 OpenAI 的 Codex skill-creator。它同时面向 Codex 和 Claude Code，运行时专属的额外内容放在 references/ 目录中。

创建循环

该技能把技能编写定义为一个循环：决定技能应该做什么并给出具体示例；规划可复用内容（脚本、参考文档、资源）；起草 SKILL.md；用带技能的子智能体（以及在有子智能体时用基线）运行测试提示；进行定性加定量审查、修改并重复；验证，然后可选地优化描述。使用时应先判断用户处在这个循环的哪一步，然后从那里介入。如果用户表示不需要评测只想随意打磨，就按此进行；如果用户直接给出草稿，则直接进入评测与迭代。

核心原则

  • 简洁是关键：上下文窗口是公共资源，Codex/Claude 本身已经足够聪明，只应补充模型尚不具备的上下文。每一段都应自问是否值得其消耗的 token，优先使用简短示例而非冗长解释。
  • 设置合适的自由度：让具体程度与任务的脆弱性匹配。高自由度（散文）适用于多种方法皆可、决策依赖语境的情况；中等自由度（伪代码、参数化脚本）适用于有偏好模式但允许合理变化的情况；低自由度（具体脚本、固定顺序）适用于操作脆弱或易错、需要一致性的情况。
  • 解释原因：当散文足以说明时避免使用大量 MUST 和僵化模板。若要用大写写 ALWAYS 或 NEVER，这是一个警示信号，应解释规则为何存在，使模型能够泛化。
  • 每个主要章节先以一句话回答“为什么这重要”，再列出模式，便于浏览者先了解利害。

技能结构

一个技能目录包含：SKILL.md（必需）、agents/（可选，Codex 专属 UI 元数据，如 openai.yaml）、scripts/（可执行代码，用于确定性或重复性工作）、references/（按需加载的文档）、assets/（输出中使用的文件，如模板、字体、图标）。

SKILL.md 的 frontmatter 有两个必需字段：name（kebab-case、不超过 64 字符、与父目录一致）和 description（能力句 + 触发句，两个运行时都依据它匹配，为可移植性应保持在 1024 字符以内）。触发条件可以写得稍微主动一些，因为模型往往触发不足，应描述技能即使未被明确点名也应触发的相邻语境。不要概括工作流，否则会形成模型只读描述而跳过正文的捷径。

渐进式披露

分三个加载层级：元数据（name + description）始终在上下文中；SKILL.md 正文在技能触发时加载（少于 500 行、约 5k 词）；捆绑资源仅在技能指向它们时加载。如果 SKILL.md 接近 500 行，应拆分到 references/ 并告诉正文何时加载每个文件。参考文件保持一层深度，超过 100 行的文件应包含目录。多变体技能可按变体组织 references（如 cloud-deploy 下分 aws.md、gcp.md、azure.md）。

应省略的内容

技能只应包含直接支持其功能的文件，不要添加 README.md、INSTALLATION.md、QUICK_REFERENCE.md、CHANGELOG.md 或任何关于技能如何构建的元文档。

创建流程

  1. 用具体示例捕获意图：从对话中提取，并询问技能应让智能体做什么、何时触发、预期输出是什么、是否建立评测。不要一次抛出六个问题。
  2. 规划可复用内容：对每个示例自问“每次都要从零写什么”作为脚本或资源候选，“每次都要重新发现什么知识”作为 references 候选。
  3. 初始化：scripts/init_skill.py <skill-name> --path <output-dir> [--resources scripts,references,assets] [--examples]，创建目录、SKILL.md 模板以及（对 Codex）agents/openai.yaml。若目标运行时不提供该脚本，则按结构手工创建。
  4. 编写 SKILL.md：使用祈使语气，frontmatter 在前，正文在后。正文可包含：操作理念/为什么重要（必需，1-2 句）、何时使用（仅当描述无法承载线索时）、模式/实现、决策表、诊断顺序、验证、常见反模式及修复、参考文件指引。同包文件引用使用相对路径且不带 @ 前缀。
  5. 运行测试用例：区分两类评测。触发判别评测只让子智能体读取 frontmatter 描述，对每条提示回答 TRIGGER/NO_TRIGGER，适用于技能较小、描述即全部表面的情况；行为评测让子智能体加载完整 SKILL.md 正文与相关参考、接收真实提示并执行至少前几个关键步骤、捕获产出物，适用于工作流形态的技能。工作流形态技能应同时运行两类评测。把 2-3 条真实提示保存到 evals/evals.json。
  6. 评分与审查：运行评分器生成 grading.json；用 python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name> 聚合出 benchmark.json 与 benchmark.md；用 python <creating-skills-path>/eval-viewer/generate_review.py <workspace>/iteration-N --skill-name "<name>" --benchmark <workspace>/iteration-N/benchmark.json 启动审查页面，无头环境可加 --static <out>.html。
  7. 改进：阅读转录而非仅看输出，从反馈中泛化，保持提示精简，把重复工作打包进 scripts/，将操作法则与出处、示例分开维护。
  8. 验证：scripts/quick_validate.py <path/to/skill-folder> 检查 YAML frontmatter、必需字段与命名规则，修到干净为止。此步骤仅涉及打包形态，不能替代前面的测试、评分与迭代。
  9. 按该技能自身规则做自审：包括描述为能力加触发而非工作流概括、描述少于 1024 字符、正文不超过 500 行、参考按需加载、包内无元文档、章节以原因开头、非常规决策点使用 dot 图、同包链接使用相对路径、触发判别评测覆盖 8-12 条提示、工作流技能运行行为评测、技能引用的工具与流水线实际可运行、子智能体写的参考文件已被打开检查、反模式章节至少列出 3 个带修复的反模式、工作流已端到端跑通、正文中无作者引用或元评论。任何一条为 N 都是阻塞项，关键行中的 N 尤其需要实际补做后重新评分。

描述优化（可选）

描述是整个触发界面。在技能其他部分稳定后，可生成约 20 条真实评测查询（8-10 条应触发、8-10 条不应触发，负面案例必须是共享关键词的近似案例），通过 assets/eval_review.html 与用户确认评测集后，运行：

python -m scripts.run_loop \
  --eval-set <path-to-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id> \
  --max-iterations 5 --verbose

该循环按 60/40 划分训练与测试集，每轮对每条查询评估 3 次，提出新描述并按测试分数（而非训练分数）选择最佳以避免过拟合，最后把 best_description 应用到 SKILL.md。

图表：非常规决策点使用 graphviz dot

仅当技能存在智能体可能出错的决策点（何时用 A 而非 B、可能提前终止的过程循环）时，使用小型内联 dot digraph。参考材料（表格）、代码（围栏代码块）与线性指令（编号列表）不使用 dot。dot 渲染为 SVG 清晰、源码可 grep 且便于 diff，标签具有语义。约定见 references/graphviz-conventions.dot。

适用场景与限制

适用场景包括：编写新技能、重构已有技能、为技能建立评测集、优化技能描述的触发效果，以及在 Codex 或 Claude Code 中运行技能评测。

限制方面：有子智能体时才能运行带技能与基线的对比评测；无子智能体时只能由作者自行按 SKILL.md 执行测试提示，严谨性较低。步骤 8 的验证只覆盖打包形态，不代表技能内容已完成。自审清单为只读性质，不会自我强制执行。此外，简单的一步式查询（如“读这个 PDF”）可能不会参考任何技能，无论描述质量如何，因此评测查询应足够实质，使查阅技能确实有帮助。