Back to Details

authoring-verifiable-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Authoring Verifiable Skills

编写可验证的技能

Core principle. A skill that does not activate does nothing, and a skill nobody has watched fail proves nothing.
  • Those two failures are silent. Both look exactly like a skill that works.
  • The weight sits in the activation surface and the gate. Everything after them improves a skill that is already being reached.
  • You opened this in the middle of something. This is how to do that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.
核心原则：无法激活的技能毫无作用，无人关注其失败情况的技能无法证明自身有效性。
  • 这两类故障都是隐性的：从表面看，它们与正常工作的技能毫无区别。
  • 关键在于激活面和路由门：后续所有工作都是在优化已能被正常触发的技能。
  • 你是在中途打开这份文档：本文档是指导你完成相关工作的方法，而非替代原有工作。开始前明确你正在进行的任务，完成后回归原任务。

Read the rule whose signal is in front of you

解读当前你面对的规则信号

This table is a gate, not a checklist. Match the left column against what you are about to write or repair.
  • One rule per row. Enter at the matched row.
  • An axis whose signal is absent is reported as not-applicable, naming the signal that would have triggered it.
  • Read both rows where the work matches two. Reading is the cheap half.
  • An index whose default is "read them all" is a table of contents with extra steps.
If you see...Read
a new skill, or one that never fires, fires on everything, or loses to a neighbour
rules/activation-surface.md
an index routing concepts rather than what an agent can see, or a skill with no gate at all
rules/gate-not-checklist.md
a rule carrying two decisions, missing a mandated block, or restating another rule
rules/one-rule-one-decision.md
a wall of prose, a paragraph that is really a list, or a file that cannot be skimmed
rules/readable-in-one-pass.md
a check suite that has never been watched fail, or a skill with no scenarios
rules/prove-it-with-checks.md
a file ordered by the sequence the author thought of things, or every line marked MUST
rules/order-and-strength.md
a name that will not come, or one colliding with skills already installed
rules/name-and-scope.md
a path, a URL, a vendor, or a package manager written into instruction prose
rules/portable-by-default.md
Discriminators.
  • Activation against name. Activation owns whether the skill is reached. Name owns whether it is distinguishable once it is.
  • Gate against one-rule. The gate owns which file opens. One-rule owns what is inside it.
  • Readable against order. Readable owns the shape of a line. Order owns which line comes first.
Default stance.
  • Fix the activation surface first. A skill that never fires does nothing, and that failure is silent.
  • Route on what an agent can see in the work, never on a concept it would need to already know.
  • Never call a check good until you have watched it fail for its own reason.
下表是路由门，而非检查清单。将左列内容与你即将编写或修复的内容匹配。
  • 一行对应一条规则：从匹配的行进入对应的文档。
  • 若某一维度无对应信号，则标记为不适用，并说明本应触发该维度的信号。
  • 若工作内容匹配两行，则需阅读这两行对应的文档：阅读的成本很低。
  • 默认设置为“全部读取”的索引，本质上是多了额外步骤的目录。
若你遇到...阅读文档
新技能，或完全不触发、触发条件过于宽泛、被其他同类技能覆盖的技能
rules/activation-surface.md
索引基于概念而非Agent可见内容进行路由，或技能完全没有路由门
rules/gate-not-checklist.md
规则包含双重决策、缺失强制模块，或重复表述其他规则
rules/one-rule-one-decision.md
大段连续文本、实为列表的段落，或无法快速浏览的文件
rules/readable-in-one-pass.md
从未有人关注其失败情况的检查套件，或没有场景案例的技能
rules/prove-it-with-checks.md
文件内容按作者思考顺序排列，或每行都标记为MUST
rules/order-and-strength.md
难以命名，或名称与已安装技能冲突
rules/name-and-scope.md
指令文本中包含路径、URL、供应商或包管理器信息
rules/portable-by-default.md
区分要点：
  • 激活与命名：激活决定技能是否能被触发，命名决定技能触发后是否可被区分。
  • 路由门与单一规则：路由门决定打开哪个文件，单一规则决定文件内的内容。
  • 可读性与排序：可读性决定每行的格式，排序决定行的先后顺序。
默认处理原则：
  • 优先修复激活面：无法触发的技能毫无作用，且这类故障是隐性的。
  • 基于Agent在工作中可见的内容进行路由，绝不要依赖Agent本应知晓的概念。
  • 除非亲眼看到检查因自身原因失败，否则不要判定检查合格。

What every skill is made of

技能的组成结构

  • SKILL.md
     carries the frontmatter, the core principle, and the gate.
  • rules/<name>.md
     carries one decision each, in five blocks. 
    • Decision:
      what to choose, in one sentence.
    • Use when:
      the conditions, stated as things you can see.
    • Do:
      the choice.
    • Avoid:
      the failure it prevents.
    • Verify:
      the check that can come back negative.
  • evals/*.scenarios.mjs
     carries the activation scenarios, positive and negative.
Three shapes are legal, and the checker knows all three.
  • Routed. An entry file plus 
    rules/
    , one rule per gate row. The default.
  • Flat. An entry file alone, for a skill with a single topic and no routing to do.
  • Multi-topic. An entry routing to topic directories, each of them routed. The one case where a separate 
    INDEX.md
    earns its hop.
The budgets, all enforced.
  • A rule. Under 450 words of prose, under 600 read, 24 to 70 prose lines.
  • An entry. Under 160 prose lines, and at least as many gate rows as it has rules.
  • A description. Near 500 characters, 700 at the ceiling.
  • SKILL.md
    ：包含前置信息、核心原则和路由门。
  • rules/<name>.md
    ：每个文件对应一项决策，分为五个模块。 
    • Decision:
      一句话说明要做出的选择。
    • Use when:
      列出触发条件，表述为可观察到的事实。
    • Do:
      具体执行的操作。
    • Avoid:
      该操作要避免的故障。
    • Verify:
      可返回负面结果的检查项。
  • evals/*.scenarios.mjs
    ：包含激活场景的正向和负向案例。
三种合法的结构形式，检查工具均支持：
  • 路由式：一个入口文件加
    rules/
    目录，每个路由门条目对应一条规则。这是默认形式。
  • 扁平式：仅一个入口文件，适用于单主题且无需路由的技能。
  • 多主题式：入口文件路由至多个主题目录，每个目录采用路由式结构。这是唯一需要单独
    INDEX.md
    文件的场景。
所有预算均已强制执行：
  • 单条规则： prose内容不超过450词，总阅读量不超过600词，prose行数在24至70行之间。
  • 入口文件：prose内容不超过160行，路由门条目数量至少与规则数量一致。
  • 描述文本：约500字符，最多不超过700字符。

Prove it before you believe it

先验证再信任

bash
node tools/verify-skill.mjs skills/<name>      # structural invariants
node tools/mutate-skill.mjs skills/<name>      # each check fires for its own reason
node tools/readability.mjs --skill skills/<name>
node tools/check-yaml-parity.mjs               # frontmatter against a real YAML parser
  • A green suite proves nothing until a broken skill fails it for the right reason.
  • A missing scenario suite is reported as UNPROVEN, never as passing.
  • Read the output before believing the number. A metric written to score a rewrite gets gamed by that rewrite.
bash
node tools/verify-skill.mjs skills/<name>      # 结构不变量检查
node tools/mutate-skill.mjs skills/<name>      # 验证每个检查项因自身原因触发
node tools/readability.mjs --skill skills/<name>
node tools/check-yaml-parity.mjs               # 验证前置信息与标准YAML解析器的兼容性
  • 检查套件全绿无法证明任何问题，除非已看到故障技能因正确原因导致检查失败。
  • 若缺失场景案例套件，将标记为UNPROVEN（未验证），而非通过。
  • 先查看输出内容再相信结果数值：为评估重写效果而设定的指标，会被重写行为刻意优化。

Do not skip this when

以下情况请勿跳过此流程

  • The skill is small. A small skill with a broken description is invisible, same as a large one.
  • You are only renaming it. The name is half the activation surface.
  • The wording is already fine. Wording was never the thing that failed; shape and routing were.
  • You are copying an existing skill. That is how a defect gets a second home.
  • 技能规模小：描述存在问题的小型技能与大型技能一样，都会被忽略。
  • 仅重命名技能：名称是激活面的重要组成部分。
  • 措辞已无问题：措辞并非故障根源，结构和路由才是。
  • 复制现有技能：这会让缺陷扩散到新的技能中。

Routing

路由规则

  • The table above selects the rule. Read it in full, and say which one you opened, in one line.
  • A direct instruction from the user outranks anything here.
  • Whether a task needs a skill at all is not decided here. This skill owns writing one once that is settled.
  • 根据上表选择对应的规则：完整阅读对应的文档，并用一句话说明你打开了哪份文档。
  • 用户的直接指令优先级高于本文档的所有规则。
  • 本文档不负责判断某项任务是否需要技能：仅在确定需要技能后，负责指导技能的编写工作。