@ssheleg/make-skill 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 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
+routes work by matching a prompt against a table in `lib/triggers.js`, and every trigger
+there must be a word this skill's own `description` advertises. Nothing here knew that
+table existed. On 2026-08-16 `sheleg-design` 1.37.0 shipped green having dropped a phrase
+that was still a live trigger, the umbrella found out minutes after the tag, and it cost a
+patch release — because the member releases FIRST and the umbrella re-pins after.
+
+`test/validate.py` now asks the umbrella's own checker (`test/advertised_check.js`), which
+reads the module the hook itself calls. **No copy of the table lives here**, so there is
+nothing to drift. With no umbrella above this checkout — a standalone clone, and CI — it
+discloses rather than passing, because a check that cannot look must never read as one
+that looked.
+
+Watched refusing a real drop before shipping: every one of the seven members carrying
+routed triggers had one of its own advertised phrases removed and every one of them failed
+its own gate.
+
 ## v0.19.0 — 2026-08-16
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.19.0",
-  "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.20.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.0",
+  "version": "0.20.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.0"
+  version: "0.20.0"
   homepage: https://github.com/ssheleg/make-skill
 ---
 

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:])