@ssheleg/make-skill 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## v0.21.0 — a gate's self-test runs in both directions
+
+*"A validator that can't fail is decoration"* has been the rule here since the standard was
+written. It is **half** the rule, and the missing half is the expensive one.
+
+The planted defect proves a gate CAN fire. Nothing in it proves the gate fires only where it
+should — and a gate that flags correct code is switched off within a day, taking the real check
+with it. **A false positive does not arrive as a bug report. It arrives as an argument about
+your gate**, from someone whose code was fine.
+
+`references/authoring.md` gains *A gate's self-test runs in both directions*: the two kinds of
+case, what each one's absence costs, and the point that counter-shapes **decide** a gate's
+design rather than merely verifying it — a pattern that finds five hits and is wrong about all
+five is a parser you have not written yet.
+
+Two recurring shapes are named because both have shipped:
+
+- **The input that cannot be resolved** must fail loudly, never skip — *a check that cannot run
+  is not a check that passed*. A slug resolver anchored on `github.com` returned nothing for
+  npm's `github:owner/repo` shorthand, so its check printed `skip` and reported success for work
+  it never did.
+- **The word inside another word** — `lease` in *please*, `аудит` in *аудитория*, `seo` in
+  *Seoul*. Found by running the gate over a real corpus, never by reading it.
+
+And: **count the cases, do not restate the count.** A summary saying *"5 cases"* while thirteen
+run is the defect the gate exists to prevent, in the gate's own output.
+
+**The doctrine went to the reference rather than the body, and the body's own gate decided
+that.** `SKILL.md` measured 4738 of a 4750 working limit — twelve tokens of headroom — so every
+draft that stated the rule inline failed the budget check. `authoring.md` is linked from
+`SKILL.md` twice, so the rule is reachable without spending a body it does not have. Closes #5.
+
 ## v0.20.0 — the checker said 180 where the file said 1392
 
 **Both checkers dropped the continuation lines of a plain multi-line YAML

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way — conformance to the Agent Skills open standard AND Anthropic's platform rules (front-matter limits, disclosure budgets, per-surface runtime limits, the Skills API, evals) plus the Claude Code plugin reference (manifest schemas, component layout, claude plugin validate --strict), marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, the review checklist for third-party skills, and MCP / A2A rules for protocol-connected skills. This package is the installer CLI.",
   "keywords": [
     "skill",

package/plugins/make-skill/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "make-skill",
   "displayName": "Make Skill",
   "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way: conformance to the Agent Skills open standard, Anthropic's platform rules (surfaces, Skills API, evals) and the Claude Code plugin reference, marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, end-to-end first publish, the review checklist for third-party skills, plus MCP / A2A references for protocol-connected skills.",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/make-skill/skills/make-skill/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Authoring works on any agent. The bundled scripts/ need python3. Publishing steps need git, gh, node and npm; the plugin gates need the claude CLI. Not usable on the Claude API surface, which has no network and no runtime package install.
 metadata:
   author: ssheleg
-  version: "0.20.0"
+  version: "0.21.0"
   homepage: https://github.com/ssheleg/make-skill
 ---
 

package/plugins/make-skill/skills/make-skill/references/authoring.md

@@ -20,6 +20,7 @@ and [agentskills.io](https://agentskills.io/skill-creation/best-practices).
 - Workflows and feedback loops
 - Content guidelines (terminology, time, paths, table of contents)
 - Scripts — the rules that separate a script from a liability
+- A gate's self-test runs in both directions
 - Evaluation and iteration — evals before prose
 - Quality checklist
 
@@ -187,6 +188,43 @@ run flagged a false positive on the very document that teaches the anti-pattern
 which is why it now ignores quoted spans. Hooks, subagents and commands that wrap
 it, plus the fallbacks they owe, are in `references/host-capabilities.md`.
 
+## A gate's self-test runs in both directions
+
+*"A validator that can't fail is decoration"* is half the rule. The planted defect
+proves the gate **can** fire. Nothing in it proves the gate fires only where it
+should — and a gate that flags correct code is switched off within a day, taking
+the real check with it. **A false positive does not arrive as a bug report. It
+arrives as an argument about your gate**, from someone whose code was fine.
+
+So a self-test carries two kinds of case:
+
+| Direction | The case | What its absence costs |
+|---|---|---|
+| **Must catch** | the planted defect, watched failing | a check that cannot fail, green forever |
+| **Must NOT flag** | the legal spelling, the empty input, the near-miss that only resembles the defect | a check that is correct and unusable, removed by the first person it wrongly blocks |
+
+**The counter-shapes are also where a gate's design gets decided, not just
+verified.** A pattern that reads *"no key may start with a mounted namespace"*
+finds five hits and all five are correct — they pass absolute keys to a translator
+that prefixes nothing. Written as a pattern the gate is wrong; written as a parser
+that binds each translator variable to its namespace, it is right. The counter-case
+is what tells the two apart, and only running it reveals which one you built.
+
+Two shapes recur and both belong in every gate's fixtures:
+
+- **The input that cannot be resolved.** A resolver returning nothing must be a
+  loud failure, never a silent skip — *a check that cannot run is not a check that
+  passed*. A slug resolver anchored on `github.com` returned nothing for npm's
+  `github:owner/repo` shorthand, so the check printed `skip` and reported success
+  for work it never did.
+- **The word inside another word.** Any matcher over prose needs the near-miss:
+  `lease` inside *please*, `аудит` inside *аудитория*, `seo` inside *Seoul*. These
+  are found by running the gate over a real corpus, not by reading it.
+
+**Count the cases, do not restate the count.** A summary line saying *"5 cases"*
+while thirteen run is the same class of defect the gate exists to prevent, in the
+gate's own output.
+
 ## Evaluation and iteration — evals before prose
 
 **Build the evaluations before writing extensive documentation.** Otherwise the