SuperAPI AI 工具集

skill-conventions

编程与开发

查看项目

更新于 11-06 16:28

技能介绍

skill-conventions 是 whhe/codex-workbench 仓库中的一项技能包编写规范,用于创建、编辑或审查技能包(skill package),目标是让技能触发清晰、内容自包含、说明可移植、结构轻量。它本身不是业务功能工具,而是一套编写与审查约定。

用途 适用于对完整技能包进行创建、编辑或评审。工作流要求先明确请求的能力、目标包、获授权的改动和未决选择;保留既有的受支持元数据以及调用/授权行为;选择最小可用的包结构;撰写有区分度的 description、必要约束和条件式引用指针;最后验证包的有效性、被引用的资源、真实任务行为以及任何被改动的可执行辅助脚本。

主要能力与规则

  1. 核心约束:每个技能必须显式声明自身职责;任何技能依赖都必须有声明式单向契约,并定义缺失依赖时的结果。每个技能必须在 frontmatter 之后、任何标题之前声明核心约束(Iron Law),回答“模型使用该技能时最可能犯的那个错误是什么”。
  2. Frontmatter:新仓库技能默认仅使用 name 与 description 两个键,值用引号字符串,不使用块标量(>-, |, |+)和多余键。更新既有技能时,保留受支持的元数据及 agents/openai.yaml 的 UI、策略与依赖配置(包括 explicit-only 调用),不得仅为匹配新包默认值而删除或重新生成;格式或调用方式迁移需有明确任务需求并已确定范围,不确定预期行为时应先询问。
  3. description:是技能触发的唯一输入,须以自然语句说明能力与问题空间,包含代表性场景与动作动词,使模型按语义和意图匹配,而非扫描字面词元;禁止写成裸关键词列表或多语言词堆。
  4. 结构:默认仅有 SKILL.md(≤500 行);需要可执行脚本或单文件容纳不下的领域知识时才扩展为多文件。标准目录含 assets/(输出用静态文件,不加载进上下文)、references/(按需加载的领域知识,最多一层嵌套)、scripts/(执行而非加载,扁平文件、无子包)和 SKILL.md。不得创建不需要的目录,不添加技能 README.md;SKILL.md 溢出知识移入 references/,并为每个引用文件给出加载时机表。
  5. 工作流结构:复杂技能应在铁律之后或 ## Workflow 标题下放置可跟踪清单,使用 ⚠️ REQUIRED、⛔ BLOCKING、(conditional) 标记。执行门禁区分实现授权与发布授权及委派审查;创建 MR/PR 前确认最终内容与目标;声明为只读的审查者保持不修改;破坏性或高成本操作需明确任务需求、确切目标、归因与安全检查,范围不安全或模糊时应停止并报告;尊重用户显式限制与更高优先级策略。
  6. 不确定性与渐进式加载:入口负责路由并声明共享的授权/不确定性规则;任务专用流程移入带精确加载条件的具名引用,只读选中的路径,不预加载无关引用,不给每个子代理整个工作流。缺失事实或意图时先查权威上下文;可安全推迟的问题显式挂起,独立工作继续;若当前动作或正确性判断依赖该答案,则先询问用户;审查子代理将问题返回其父级;不得以猜测、沉默或时间流逝替代确认。
  7. 写作:除用户明确要求其他语言外使用英文;只为模型未知的内容付出 token;使用祈使句;用问题代替指令;列出反模式(模型应避免的懒惰默认行为);复杂技能以具体可验证的交付前自检清单结尾。
  8. 可移植性:不含密钥或内部 URL;不含机器特定内容(绝对路径、机器特定环境变量),使用占位符;与平台无关,不假设特定工具、MCP 服务器或 IDE 功能,不可避免时以条件语句表述;仅用 CommonMark(标题、列表、代码块、表格、链接),不用 HTML、嵌入图片或图表语法。技能依赖需声明具体阶段需求、必需/可选状态、输入、输出与缺失依赖行为,仅在到达该阶段时加载,并保留调用策略与用户权限;职责自包含,优先按能力选择专家而非固定技能名依赖,声明触发、基于目录的解析、输入输出、变更限制及无匹配专家时的行为;禁止循环编排,审查者报告发现而非回派执行者;目录内文件引用可用,其余引用须为 Web URL;技能依赖按目录名解析而非同级文件系统路径。
  9. 交付检查:确认 description 能与相邻技能区分;既有受支持元数据、调用策略与授权保持完整(除非请求变更);每个保留引用有有效的包内目标与精确加载条件,不引入无条件批量加载;新目录与资源有实际调用方,不引入技能 README 或未使用脚手架;实质问题已解决或显式推迟,依赖动作不靠猜测;验证覆盖被改契约,脚本变动时验证可执行行为,并报告未验证的限制。

使用方式 按上述约定和检查项编写或审查技能包,例如:

Good


name: "my-skill" description: "What it does and when to use it."

适用场景与限制 适用于仓库内技能包的编写、更新与评审,尤其关注触发描述、职责边界、依赖契约和结构最小化。限制包括:文中约定为编写规范而非某具体运行平台的功能说明;文档为英文,除非用户要求其他语言;部分配置(如 agents/openai.yaml)属于既有包内容,更新时需保留而非重建;文中未说明安装命令、收费、价格或运行平台等信息。