@ssheleg/make-skill 0.19.1 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # 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
+description**, so a description whose real length was **1392 characters was
+measured at 180** and passed the 1024 spec cap, the 970 working limit and every
+`/skill-audit` this family issues. The standard-keeper handed a clean bill to a
+skill the Skills API rejects on upload, and `make-skill`'s own gate could not
+catch it either. A plain scalar may continue on indented lines and YAML folds
+them into one value with a space; `parse_frontmatter` discarded them, in both
+`scripts/audit_skill.py` and `test/validate.py`, byte for byte the same defect.
+
+**`allowed-tools: [Read, Write]` was read as the string `"[Read, Write]"`.**
+`TOOLS_TYPE` asks whether the value is a `str` and got yes, so the check written
+for exactly that form never fired — on the most common way authors write a tool
+list, and the one portability defect that costs a skill its tool grant on every
+host but Claude Code. A flow sequence now parses to a list, and the check fires.
+
+**The scalar is kept raw and finished at the end**, because a quoted scalar
+spanning lines carries its closing quote on the last one: unquoting the first
+line strips nothing and buries the quote in the middle of the folded value.
+
+**`--house` now applies the body's half of the 5% rule.** The canon states the
+headroom as one sentence for both fields, and this script applied it to the
+description only — so a body at 4999 tokens got `0 GAP` here and was refused by
+this repo's own validator. Two verdicts on one rule, and the permissive one was
+the one users got. `BODY_HEADROOM` is the new gap id; the `--house` help text
+and the module docstring said neither this nor `DESC_HEADROOM`, and now say both.
+
+**The guard against the two checkers drifting compared one of twelve rules.**
+It now compares all nine shared numeric limits by name plus both front-matter key
+sets, and a constant that exists on one side only is a failure rather than a
+silently skipped row — which is exactly how the missing 4750 shipped for four
+releases underneath it. Three limits that were literals at their use sites
+(`NAME_MAX`, `DESC_MAX`, `COMPAT_MAX`) are named, because a number with no name
+has no single home and cannot be compared against a second implementation.
+
+**`test/checker_parity_test.py`, 14 cases, joins `npm test`** — locally, not only
+in CI, since the checker it guards runs locally. Watched failing against the
+pre-fix code: **9 of 14 red**. It plants each defect and requires the checker to
+say so, rather than asserting that a correct file passes: a false negative in a
+checker is worse than no checker, because it is a green that gets quoted.
+
+**No shipped skill changes verdict.** All 24 in the family re-audited before and
+after: identical, and the one apparent difference was a `__pycache__` this run
+had just created.
+
+Found by the nine-repository audit of 2026-08-16 (umbrella `B-63`).
+
 ## v0.19.1 — 2026-08-16
 
 **This gate can now see an invariant it breaks one repository away.** The family umbrella

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.19.1",
-  "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way \u2014 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.",
+  "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",
     "plugin",
@@ -45,6 +45,6 @@
     "node": ">=16"
   },
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/plant_guard_test.py"
+    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && python3 test/checker_parity_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.19.1",
+  "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.19.1"
+  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

package/plugins/make-skill/skills/make-skill/scripts/audit_skill.py

@@ -14,8 +14,12 @@ spends its context on the half that needs judgement.
   core      the Agent Skills open standard (agentskills.io/specification) plus the
             rules Anthropic's platform enforces on upload (reserved words, XML
             tags) and its authoring guidance (third person, tables of contents)
-  --house   adds the ssheleg canon: description starts "Use when …" and carries
-            English AND Russian trigger phrases
+  --house   adds the ssheleg canon: description starts "Use when …", carries
+            English AND Russian trigger phrases, and holds the 5% working
+            headroom on BOTH budgets — 970 of 1024 chars, 4750 of 5000 tokens.
+            The canon states the headroom as one rule for both fields; applying
+            it to one of them is how a body at 4999 tokens got a clean bill here
+            and was refused by the repo's own validator.
 
 Python 3.9+, standard library only: it has to run wherever the skill landed.
 """
@@ -37,6 +41,12 @@ DESC_TARGET = 970
 COMPAT_MAX = 500        # spec: compatibility is 1-500 characters
 BODY_MAX_LINES = 500    # spec + Anthropic: keep the body under 500 lines
 BODY_MAX_TOKENS = 5000  # spec + Anthropic: level-2 budget
+# House working limit, the body's half of the same 5% rule DESC_TARGET states.
+# The canon writes both as one sentence — "hold 5% headroom" — and for four
+# releases this script applied only the description half, so a body at 4999
+# tokens got 0 GAP here and was refused by the repo's own validator. Two
+# verdicts on one rule, and the permissive one was the one users got.
+BODY_TARGET_TOKENS = 4750
 # No tokenizer in the stdlib. 3.9 chars/token is measured, not assumed: tokenizing
 # this skill's own bundle gives 3.78-4.47. `claude plugin details` is far more
 # pessimistic (~2.8) and will always show a bigger number than this estimate.
@@ -95,8 +105,15 @@ def parse_frontmatter(text):
     Returns (data, line_of_key). A full YAML parser is not in the stdlib and a
     skill's frontmatter is a flat map by specification, so this is enough — and
     it keeps the script dependency-free, which is the point of shipping it.
+
+    A plain scalar may continue on indented lines and YAML folds them into one
+    value with a space. Dropping those lines is how a description whose real
+    length was 1392 characters got measured at 180 and passed both the 1024 cap
+    and the 970 working limit — a clean bill from the family's standard-keeper
+    for a skill the Skills API rejects on upload (2026-08-16, B-63).
     """
     data, lines, key, mode = {}, {}, None, None
+    scalars = set()
     for i, raw in enumerate(text.split("\n"), start=2):  # +2: the opening '---'
         if not raw.strip():
             continue
@@ -112,16 +129,41 @@ def parse_frontmatter(text):
             elif val == "":
                 data[key], mode = {}, "map"
             else:
-                data[key], mode = _unquote(val), None
+                # Kept RAW here and finished at the end: a quoted scalar that
+                # spans lines carries its closing quote on the last one, so
+                # unquoting the first line strips nothing and leaves the quote
+                # buried in the middle of the folded value.
+                data[key], mode = val, "scalar"
+                scalars.add(key)
         elif mode == "block":
             data[key] = (data[key] + " " + raw.strip()).strip()
+        elif mode == "scalar":
+            data[key] = (data[key] + " " + raw.strip()).strip()
         elif mode == "map":
             m = re.match(r"^\s+([A-Za-z0-9_-]+):\s*(.*)$", raw)
             if m:
                 data[key][m.group(1)] = _unquote(m.group(2).strip())
+    for k in scalars:
+        data[k] = _finish_scalar(data[k])
     return data, lines
 
 
+def _finish_scalar(v):
+    """A flow sequence is a LIST, not a string that happens to look like one.
+
+    `allowed-tools: [Read, Write]` read as the string "[Read, Write]" is why
+    TOOLS_TYPE never fired: it asks whether the value is a `str`, and the answer
+    was yes. The inline sequence is the most common way authors write a tool
+    list, and it is the portability defect the rule exists for — the skill works
+    in Claude Code and silently loses its tool grant on every other host.
+    """
+    v = v.strip()
+    if len(v) >= 2 and v[0] == "[" and v[-1] == "]":
+        inner = v[1:-1].strip()
+        return [] if not inner else [_unquote(p.strip()) for p in inner.split(",")]
+    return _unquote(v)
+
+
 def _unquote(v):
     v = v.strip()
     if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
@@ -156,7 +198,7 @@ def audit(skill_dir, house=False):
     _check_description(a, fm, fm_lines, rel, house)
     _check_optional_fields(a, fm, fm_lines, rel)
     _check_keys(a, fm, fm_lines, rel)
-    _check_body_budget(a, body, rel)
+    _check_body_budget(a, body, rel, house)
     _check_bundle(a, skill_dir, text, name_on_disk)
     _check_links(a, skill_dir, text, rel)
     _check_prose(a, body, rel)
@@ -271,7 +313,7 @@ def _check_keys(a, fm, lines, rel):
         a.ok("FM_UNKNOWN_KEY", "no frontmatter key outside spec ∪ host extensions", rel)
 
 
-def _check_body_budget(a, body, rel):
+def _check_body_budget(a, body, rel, house=False):
     n_lines = body.count("\n") + 1
     est = int(len(body) / CHARS_PER_TOKEN)
     # Both, not either: a body over the line budget still has to report its
@@ -288,6 +330,17 @@ def _check_body_budget(a, body, rel):
     if not over:
         a.ok("BODY_BUDGET", "body is %d lines / ~%d tokens (budget %d / %d)"
              % (n_lines, est, BODY_MAX_LINES, BODY_MAX_TOKENS), rel)
+    # The house half, and it is the same rule DESC_HEADROOM applies to the other
+    # field: a body at the ceiling cannot absorb the next paragraph, so it gets
+    # absorbed into a reference that should have been split instead.
+    if house and not over and est >= BODY_TARGET_TOKENS:
+        a.gap("BODY_HEADROOM", "body is ~%d tokens — inside the %d budget but past the "
+              "%d working limit (house rule): the next section will breach it, and the "
+              "answer then is a split, not a trim"
+              % (est, BODY_MAX_TOKENS, BODY_TARGET_TOKENS), rel)
+    elif house and not over:
+        a.ok("BODY_HEADROOM", "body is ~%d/%d tokens, inside the working limit"
+             % (est, BODY_TARGET_TOKENS), rel)
 
 
 def _bundle_closure(skill_dir, skill_text):
@@ -451,7 +504,9 @@ def main(argv):
         description="Audit a skill directory against the Agent Skills standard.")
     p.add_argument("skill_dir", help="the directory containing SKILL.md")
     p.add_argument("--house", action="store_true",
-                   help="also apply the ssheleg canon (Use-when opener, EN+RU triggers)")
+                   help="also apply the ssheleg canon: Use-when opener, EN+RU triggers, "
+                        "and the 5%% working headroom on BOTH the description (970 of "
+                        "1024) and the body (4750 of 5000)")
     p.add_argument("--json", action="store_true", help="emit results as JSON")
     p.add_argument("--quiet", action="store_true", help="print GAP lines only")
     args = p.parse_args(argv[1:])