@ssheleg/make-skill 0.26.0 → 0.27.1

package/CHANGELOG.md

@@ -1,3 +1,65 @@
+## v0.27.1 — the tarball stops shipping compiled Python, and the audit vocabulary the routing block promised becomes advertised
+
+Family audit 2026-09-06, wave `AUDIT-WAVE-0906`. Two findings, both a gap between what
+this member says and what it ships.
+
+**The npm tarball carried a 33kB `.pyc` from a used checkout.** `files` includes
+`plugins`, the gate imports the auditor, and Python drops
+`scripts/__pycache__/audit_skill.cpython-314.pyc` beside it — so a publish from any
+machine that had run the suite shipped bytecode nobody wrote. `.gitignore` already
+covered it, and that is exactly why it looked handled: git never carried the file, but
+npm's `files` allowlist does not read `.gitignore` inside a directory it was told to
+include. The durable fix is the shape `seo-aeo-audit` already ships — `"!**/__pycache__"`
+and `"!**/*.pyc"` in `files`. **Measured with the residue present on disk, not after
+deleting it**: the `.pyc` was regenerated first, then `npm pack --dry-run | grep -c pyc`
+→ **0**. The auditor's `BUNDLE_NESTED` GAP for that directory goes with it.
+
+**The umbrella's routing block advertises "skill audit" / «аудит скилов», and the
+description never did.** Both phrases now sit in the trigger enumeration, verbatim, after
+the "сделай скилл" pair. The room was paid for by trimming **54** characters from the
+non-trigger prose — "open standard and" → "standard,", "front-matter limits" → "limits",
+"manifest schemas, component layout" → "manifests, layout", "the Claude Code plugin
+reference" → "the plugin reference" — and **every previously advertised quoted phrase
+survives verbatim**, which is what the umbrella's soundness fixture refuses a pin
+without. Auditor before → after: description **965/970 → 943/970**, `DESC_WHAT` **550 →
+582** chars beyond the triggers, body untouched at ~4677/4750, **0 GAP**.
+
+## v0.27.0 — the standard-keeper asked WHEN nine times and WHAT never
+
+`B-139`. `audit_skill.py` carried nine `DESC_*` rules — length, headroom, person, Russian
+triggers, XML, target, the `Use when` opener — and **not one asked whether the
+description says what the skill DOES.** That is the half of Anthropic's guidance `B-76`
+quoted directly: *a description that never says what the skill does passes*. Measured
+2026-09-03 across the family: **28 of 28 skills pass `DESC_USEWHEN`, 0 gaps** — the WHEN
+half is universal and the WHAT half was unchecked.
+
+`DESC_WHAT` measures the description with its mechanical parts removed — the `Use when`
+opener, the trigger list, the `Not for` clause and the opt-out sentence — and refuses
+what is left below 60 characters.
+
+**Built on the PARSED description, which is the whole reason the previous attempt was
+refused.** That prototype read raw front matter, reported a **0-character** WHAT half for
+six skills and missed the opening clause of twenty, because several descriptions are YAML
+block scalars (`>-`) a raw-text regex reads straight past. `parse_frontmatter` already
+resolves them.
+
+**The floor is stated with its margin.** Measured across the shipped family the smallest
+honest WHAT half is **149** characters (`ux-audit`) and the largest **949**
+(`seo-aeo-audit`), so 60 clears every real description by more than double while still
+catching `Use when the user asks. Triggers - "делай" / "do it".`, whose WHAT half is
+**13**. A case asserts that margin, so raising the floor without re-measuring fails.
+
+**This rule finds no gap today and that is said out loud.** A standard is for the
+description not yet written, and a rule that fires on nothing now is worth only what its
+plants prove — so it was watched refusing a WHEN-only description and watched going
+silent when disabled.
+
+**One case was reworded after being caught claiming somebody else's work.** It asserted
+the WHAT half is read from the parsed value rather than raw text — and the plant for that
+property is caught by an existing case guarding `parse_frontmatter`'s folding, one layer
+up. It now claims only what it holds: both spellings of one description reach the same
+verdict, neither passes vacuously, and the parsed value carries no newline.
+
 ## v0.26.0 — where a rule lives decides whether it exists
 
 `authoring.md` treated progressive disclosure as a budget question. It is also a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.26.0",
+  "version": "0.27.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.",
   "keywords": [
     "skill",
@@ -36,7 +36,9 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "SECURITY.md"
+    "SECURITY.md",
+    "!**/__pycache__",
+    "!**/*.pyc"
   ],
   "publishConfig": {
     "access": "public"

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.26.0",
+  "version": "0.27.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -1,11 +1,11 @@
 ---
 name: make-skill
-description: Use when creating, upgrading, auditing, or publishing agent skills and Claude Code plugins - "make a skill" / "сделай скилл", "wrap it in a plugin" / "заверни в плагин", "publish a skill" / "опубликуй скилл", "retrofit a skill to the standard" / "приведи скилл к стандарту", "does this skill match the spec" / "соответствует ли скилл стандарту", "claude plugin validate fails" / "проверь плагин по документации Anthropic", "is this skill safe to install" / "безопасно ли ставить этот скилл" - or when a skill must reach an MCP server or another agent over A2A. NOT for a version bump or release in a repo that ships anything but a skill or plugin. Encodes the Agent Skills open standard and Anthropic's platform rules (front-matter limits, budgets, the Skills API, evals), the Claude Code plugin reference (manifest schemas, component layout, validate --strict), plus the ssheleg pipeline - marketplace layout, version sync, validator+CI, distribution, npm gotchas.
+description: Use when creating, upgrading, auditing, or publishing agent skills and Claude Code plugins - "make a skill" / "сделай скилл", "skill audit" / «аудит скилов», "wrap it in a plugin" / "заверни в плагин", "publish a skill" / "опубликуй скилл", "retrofit a skill to the standard" / "приведи скилл к стандарту", "does this skill match the spec" / "соответствует ли скилл стандарту", "claude plugin validate fails" / "проверь плагин по документации Anthropic", "is this skill safe to install" / "безопасно ли ставить этот скилл" - or when a skill must reach an MCP server or another agent over A2A. NOT for a version bump or release in a repo that ships anything but a skill or plugin. Encodes the Agent Skills standard, Anthropic's platform rules (limits, budgets, Skills API, evals), the plugin reference (manifests, layout, validate --strict), plus the ssheleg pipeline - marketplace layout, version sync, validator+CI, distribution, npm gotchas.
 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.26.0"
+  version: "0.27.1"
   homepage: https://github.com/ssheleg/make-skill
 ---
 

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

@@ -38,6 +38,48 @@ DESC_MAX = 1024         # spec: description is 1-1024 characters
 # budget AND the field that must grow when a near-miss skill appears ("say what
 # it is NOT for"). A description at 98% of cap cannot absorb that sentence.
 DESC_TARGET = 970
+# B-139 — the nine `DESC_*` rules ask WHEN and never WHAT.
+#
+# Anthropic's guidance asks a description to say what the skill DOES as well as when to
+# use it, and `B-76` quoted the failure directly: *a description that never says what the
+# skill does passes*. Measured 2026-09-03 across the family: **28 of 28 skills pass
+# `DESC_USEWHEN`, 0 gaps** — the WHEN half is universal and the WHAT half was unchecked.
+#
+# The WHAT half is the description with its mechanical parts removed: the `Use when`
+# opener, the trigger list, the `Not for` clause and the opt-out sentence. What remains is
+# the prose that names the act. A description that is an opener plus a trigger list leaves
+# almost nothing, which is exactly the shape the rule refuses.
+#
+# The floor is 60 and it is deliberately permissive. Measured on the shipped family, the
+# smallest honest WHAT half is **149** characters (`ux-audit`) and the largest 949, so 60
+# clears every real description by more than double and still catches
+# `Use when the user asks. Triggers - "x" / "у".`, whose WHAT half is 13.
+#
+# **This rule finds no gap today, and that is stated rather than hidden.** A standard is
+# for the description not yet written; a rule that fires on nothing now is only worth
+# anything if it was watched firing on a plant, which `test/checker_parity_test.py` does.
+DESC_WHAT_MIN = 60
+
+# Built on the PARSED description, never the raw front matter. A prototype was built
+# against raw text and refused: it reported a 0-character WHAT half for six skills and
+# missed the opening clause of twenty, because several descriptions are YAML block
+# scalars (`>-`) that a raw-text regex reads straight past. `parse_frontmatter` already
+# resolves them, and the prototype did not use it.
+_WHAT_OPENER = re.compile(r"^use when\s+", re.I)
+_WHAT_STRIP = (
+    re.compile(r"\bTriggers?\s*[-–—:].*", re.S | re.I),
+    re.compile(r"\bNot for\b.*", re.S | re.I),
+    re.compile(r"\bsay\s+['\"«].*", re.S | re.I),
+)
+
+
+def what_half(description):
+    """The prose that names the act, with the mechanical parts removed."""
+    core = _WHAT_OPENER.sub("", " ".join(str(description or "").split()))
+    for rx in _WHAT_STRIP:
+        core = rx.sub("", core)
+    return core.strip(" .,;—-")
+
 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
@@ -270,6 +312,17 @@ def _check_description(a, fm, lines, rel, house):
             a.gap("DESC_RU", "description carries no Russian trigger phrases (house rule)", rel, ln)
         else:
             a.ok("DESC_RU", "description carries Russian trigger phrases (house rule)", rel, ln)
+        what = what_half(desc)
+        if len(what) < DESC_WHAT_MIN:
+            a.gap("DESC_WHAT", "description says WHEN and never WHAT: %d chars remain "
+                  "after the opener, the trigger list and the refusal are removed, and "
+                  "the floor is %d (house rule). Anthropic's guidance asks for both "
+                  "halves, and a description that is an opener plus a trigger list "
+                  "selects the skill without telling the model what it will do"
+                  % (len(what), DESC_WHAT_MIN), rel, ln)
+        else:
+            a.ok("DESC_WHAT", "description states WHAT the skill does in %d chars "
+                 "beyond its triggers (house rule)" % len(what), rel, ln)
         if DESC_TARGET < len(desc) <= DESC_MAX:
             a.gap("DESC_HEADROOM", "description is %d chars — inside the %d cap but past the "
                   "%d working limit (house rule): leave room for the 'what this is NOT for' "