@ssheleg/make-skill 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## v0.22.0 — the gate left 47 MB in $TMPDIR and never said what it left
+
+**Two suites copied the tree to plant defects into it and never removed the copy.** The
+conformance audit named one; the sweep found the other, and it was the larger half by two
+orders of magnitude. Measured on this machine at the time of the fix: **1904 abandoned
+mkdtemp roots, 47.3 MB** — 60 planted skill dirs and 36 repo copytrees unambiguously this
+repository's, and 1808 plant-guard trees ambiguous, because four family repos ship the
+byte-identical fixture at the same line and nothing in the content distinguishes them.
+
+### `test/residue.py`
+
+A shared ledger in this repo's `plant_guard.py` idiom: `workspace()` hands out a
+`make-skill-test-` prefixed mkdtemp, `open_case` / `close_case` bind each tree to a case,
+and `report()` — wired to `atexit`, so no exit path skips it — removes what may go, keeps
+what a failure needs, and **prints one line either way**. A clean run says
+`residue: this run left nothing — N temp tree(s) created, N removed`, because the
+requirement is that completion *records* residue, not merely that there is none. A leak is
+then visible the first time the line changes.
+
+**The failure path keeps its tree, by decision and stated in three places.** A planted
+defect here is debugged by reading the copy the plant landed in, and a cleanup that runs
+only on the pass path removes the evidence exactly when you want it. The report names the
+kept path, its owning case, and the `rm -rf` that ends it — a kept tree with no stated
+remedy is a leak with better manners. A tree that refuses to delete is counted as **kept**,
+never as removed: the report does not claim a teardown it did not achieve.
+
+`test/residue_test.py` joins the gate with 8 cases, including the one that matters — stash
+the two fixes and it exits 1 naming both suites, then prints
+`residue: 2 of 2 temp tree(s) KEPT` with both paths. The failure path demonstrating itself.
+
+### Not swept
+
+The 1904 pre-existing directories were **left in place** and reported. Ownership of 1808
+of them cannot be established from their contents, and deleting state you cannot prove is
+yours is the one thing this kind of cleanup must not do.
+
+## 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/README.md

@@ -261,10 +261,13 @@ plugins/make-skill/
 cursor/rules/make-skill.mdc           # self-contained Cursor rule
 bin/make-skill.js + package.json      # zero-dep npx installer
 test/validate.py                      # structural validator
+test/{plant_guard,checker_parity,residue}_test.py   # the gate's three suites
+test/{plant_guard,residue}.py         # did the plant land · what did the run leave
 test/evals/                           # trigger set + behavioral scenarios (data)
 .github/workflows/{validate,release}.yml
 install.sh  README.md  CHANGELOG.md  CONTRIBUTING.md  SECURITY.md  SKILL-CARD.md  LICENSE
 docs/evidence/{specs,plans}/       # historical design records
+docs/evidence/{backlog,verification}.md   # what is owed · what confirmed what
 ```
 
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.20.0",
+  "version": "0.22.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",
@@ -45,6 +45,6 @@
     "node": ">=16"
   },
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && python3 test/checker_parity_test.py"
+    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && python3 test/checker_parity_test.py && python3 test/residue_test.py"
   }
 }

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.22.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.22.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