authoring-verifiable-skills

编写可验证的技能

核心原则。 无法激活的技能毫无作用，而从未亲眼见过其失败的技能，也无法证明任何事。根据证据改进现有技能，属于 optimising-skills。

• 这两种失败都悄无声息。 它们看起来与正常工作的技能毫无区别。
• 关键在于激活面和门槛。 此后的所有工作，都是在改进已经触达的技能。
• 你是在一件事进行到一半时打开本文的。 本文介绍如何开展这项工作，而不是要取代它。开始前，先明确你原本在做什么；完成后，再回去继续。

阅读与你眼前信号对应的规则

这张表是门槛，不是检查清单。 根据你即将编写或修复的内容，匹配左栏。

• 每行一条规则。 从匹配的行开始。
• 如果某个维度没有相应信号，就标记为不适用，并说明什么信号会触发它。
• 如果工作匹配两行，就读两行。 阅读是成本较低的那一半。
• 默认要求“全部阅读”的索引，只不过是多绕几步的目录。
• 读完每一行后，再按匹配结果采取行动，并优先处理最难撤销的事项。 阅读一行毫无成本；被跳过的那一行，恰恰是覆盖不到的地方。

如果你看到……	阅读
新技能，或从未触发、对所有内容都触发，或总被相邻技能抢先触发的技能	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
工具返回数字而非判定结果，或即将将数字写入报告或用于决策	rules/prove-a-measure.md
文件按作者思考内容的顺序排列，或每行都标为 MUST	rules/order-and-strength.md
让人想不起来的名称，或与已安装技能重名的名称	rules/name-and-scope.md
工作分为多个阶段却没有标明当前阶段的方式；或规则告诉读者对原本会立即采取的行动说 not yet	rules/states-carry-licenses.md
指令文字中写入了路径、URL、供应商或包管理器	rules/portable-by-default.md

区分要点。

• 激活与名称。 激活决定技能能否被触达；名称决定技能被触达后是否容易区分。
• 门槛与单规则。 门槛决定打开哪个文件；单规则决定文件中包含什么。
• 可读性与顺序。 可读性决定一行的表达形式；顺序决定哪一行排在前面。

默认立场。

• 先修复激活面。 从未触发的技能毫无作用，而且这种失败悄无声息。
• 根据 Agent 在工作中能看到的内容进行路由，绝不要依据它必须预先了解的概念进行路由。
• 在亲眼看到检查因其自身原因失败之前，绝不要称它为好检查。

每个技能由什么构成

• SKILL.md 包含 frontmatter、核心原则和门槛。
• rules/<name>.md 各自包含一项决策，分为五个部分。
  • Decision: 要选择什么，用一句话说明。
  • Use when: 使用条件，以可观察到的情况表述。
  • Do: 要做出的选择。
  • Avoid: 要防止的失败。
  • Verify: 可能得出否定结果的检查。
• evals/*.scenarios.mjs 包含激活场景，涵盖正向和负向情况。

三种结构都合规，检查器也都能识别。

• 路由式。 一个入口文件加上 rules/，每条门槛对应一条规则。这是默认结构。
• 扁平式。 只有一个入口文件，适用于只有一个主题、无需路由的技能。
• 多主题式。 一个入口文件路由到多个主题目录，每个目录再进行路由。只有在这种情况下，单独的 INDEX.md 才值得增加这次跳转。

所有预算均强制执行。

• 规则。 正文少于 450 个单词，全文少于 600 个单词，正文为 24 至 70 行。
• 入口文件。 正文少于 160 行，且门槛行数至少与规则数量相同。
• 描述。 接近 500 个字符，最多不超过 700 个字符。

先验证，再相信

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

• 在一个有缺陷的技能未因正确原因而导致测试失败之前，测试套件全绿毫无证明力。
• 缺少场景测试套件时，应报告为 UNPROVEN，绝不能算作通过。
• 先读输出，再相信数字。 为评估重写而编写的指标，会被这次重写钻空子。

以下情况也不要跳过

• 技能很小。 描述有缺陷的小技能同样会被忽视，与大型技能无异。
• 你只是在重命名它。 名称是激活范围的一半。
• 措辞已经没问题。 出问题的从来不是措辞，而是结构和路由。
• 你正在复制现有技能。 缺陷就是这样再次出现的。

路由

• 上表用于选择规则。 完整阅读，并用一行说明你打开了哪条规则。
• 用户的直接指示优先于此处的任何内容。
• 任务是否需要技能并不在此处决定。 一旦确定需要编写技能，此技能就负责撰写。
• 已存在但表现不佳的技能应交由 optimising-skills 处理。 此处负责在阅读时修复结构；在那里则要先写下预测，再通过实验改变行为。