Authoring Verifiable Skills
Core principle. A skill that does not activate does nothing, and a skill nobody has watched fail proves nothing. Changing one that already exists, against evidence that it underperforms, belongs to optimising-skills.
- 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.
- Read every row, then act on the matches, hardest to undo first. Reading a row costs nothing; the row you skipped is where the coverage went.
| 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 tool returning a number rather than a verdict, or a number about to enter a report or a decision |
rules/prove-a-measure.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 skill whose work has phases and no way to say which one it is in; a rule saying not yet to something a reader would otherwise do now |
rules/states-carry-licenses.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.
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.
Prove it before you believe it
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.
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.
- A skill that exists and underperforms belongs to
optimising-skills. Structure is repaired here on reading; behaviour is changed there, as an experiment with a prediction written first.
1---2name: authoring-verifiable-skills3description: Write, split, rename, or repair an agent skill so it activates when it should and can be proved rather than believed: a new skill, a description that never fires or fires on everything, a rule that has grown two decisions, an index that routes nothing an agent can see, a file too dense to read in one pass, or a check suite nobody has watched fail. Covers the activation surface, the routing gate, rule anatomy, page shape, naming, portability, and the invariant and mutation scripts. Use when the user says "write a skill", "this skill never triggers", "split this skill", "standardise these skills", or "how do I check this skill". Not for authoring product documentation, and not for deciding whether a task needs a skill at all.4---56# Authoring Verifiable Skills78**Core principle.** A skill that does not activate does nothing, and a skill nobody has watched fail proves nothing. Changing one that already exists, against evidence that it underperforms, belongs to `optimising-skills`.910- **Those two failures are silent.** Both look exactly like a skill that works.11- **The weight sits in *the activation surface* and *the gate*.** Everything after them improves a skill that is already being reached.12- **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.1314## Read the rule whose signal is in front of you1516**This table is a gate, not a checklist.** Match the left column against what you are about to write or repair.1718- **One rule per row.** Enter at the matched row.19- **An axis whose signal is absent is reported as not-applicable**, naming the signal that would have triggered it.20- **Read both rows where the work matches two.** Reading is the cheap half.21- **An index whose default is "read them all" is a table of contents with extra steps.**22- **Read every row, then act on the matches, hardest to undo first.** Reading a row costs nothing; the row you skipped is where the coverage went.2324| If you see... | Read |25| --- | --- |26| a new skill, or one that never fires, fires on everything, or loses to a neighbour | `rules/activation-surface.md` |27| an index routing concepts rather than what an agent can see, or a skill with no gate at all | `rules/gate-not-checklist.md` |28| a rule carrying two decisions, missing a mandated block, or restating another rule | `rules/one-rule-one-decision.md` |29| a wall of prose, a paragraph that is really a list, or a file that cannot be skimmed | `rules/readable-in-one-pass.md` |30| a check suite that has never been watched fail, or a skill with no scenarios | `rules/prove-it-with-checks.md` |31| a tool returning a number rather than a verdict, or a number about to enter a report or a decision | `rules/prove-a-measure.md` |32| a file ordered by the sequence the author thought of things, or every line marked MUST | `rules/order-and-strength.md` |33| a name that will not come, or one colliding with skills already installed | `rules/name-and-scope.md` |34| a skill whose work has phases and no way to say which one it is in; a rule saying `not yet` to something a reader would otherwise do now | `rules/states-carry-licenses.md` |35| a path, a URL, a vendor, or a package manager written into instruction prose | `rules/portable-by-default.md` |3637**Discriminators.**3839- **Activation against name.** Activation owns whether the skill is reached. Name owns whether it is distinguishable once it is.40- **Gate against one-rule.** The gate owns which file opens. One-rule owns what is inside it.41- **Readable against order.** Readable owns the shape of a line. Order owns which line comes first.4243**Default stance.**4445- **Fix the activation surface first.** A skill that never fires does nothing, and that failure is silent.46- **Route on what an agent can see in the work**, never on a concept it would need to already know.47- **Never call a check good until you have watched it fail** for its own reason.4849## What every skill is made of5051- **`SKILL.md`** carries the frontmatter, the core principle, and the gate.52- **`rules/<name>.md`** carries one decision each, in five blocks.53 - `Decision:` what to choose, in one sentence.54 - `Use when:` the conditions, stated as things you can see.55 - `Do:` the choice.56 - `Avoid:` the failure it prevents.57 - `Verify:` the check that can come back negative.58- **`evals/*.scenarios.mjs`** carries the activation scenarios, positive and negative.5960**Three shapes are legal, and the checker knows all three.**6162- **Routed.** An entry file plus `rules/`, one rule per gate row. The default.63- **Flat.** An entry file alone, for a skill with a single topic and no routing to do.64- **Multi-topic.** An entry routing to topic directories, each of them routed. The one case where a separate `INDEX.md` earns its hop.6566**The budgets, all enforced.**6768- **A rule.** Under 450 words of prose, under 600 read, 24 to 70 prose lines.69- **An entry.** Under 160 prose lines, and at least as many gate rows as it has rules.70- **A description.** Near 500 characters, 700 at the ceiling.7172## Prove it before you believe it7374```bash75node tools/verify-skill.mjs skills/<name> # structural invariants76node tools/mutate-skill.mjs skills/<name> # each check fires for its own reason77node tools/readability.mjs --skill skills/<name>78node tools/check-yaml-parity.mjs # frontmatter against a real YAML parser79```8081- **A green suite proves nothing until a broken skill fails it for the right reason.**82- **A missing scenario suite is reported as UNPROVEN, never as passing.**83- **Read the output before believing the number.** A metric written to score a rewrite gets gamed by that rewrite.8485## Do not skip this when8687- **The skill is small.** A small skill with a broken description is invisible, same as a large one.88- **You are only renaming it.** The name is half the activation surface.89- **The wording is already fine.** Wording was never the thing that failed; shape and routing were.90- **You are copying an existing skill.** That is how a defect gets a second home.9192## Routing9394- **The table above selects the rule.** Read it in full, and say which one you opened, in one line.95- **A direct instruction from the user outranks anything here.**96- **Whether a task needs a skill at all is not decided here.** This skill owns writing one once that is settled.97- **A skill that exists and underperforms belongs to `optimising-skills`.** Structure is repaired here on reading; behaviour is changed there, as an experiment with a prediction written first.
gabrielmoreira