@ssheleg/make-skill 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## v0.11.1 — 2026-08-10
+
+A behavioural pass over v0.11.0 — walking the skill the way an agent walks it and
+running every command it hands out, rather than re-reading the files. The
+structural gates were already green; what this found was in the one field no
+structural gate covers.
+
+### Fixed — the description had a neighbour and no answer to it
+
+Coexistence was measured instead of assumed, across the 130 skills of the 23
+enabled plugins on the author's machine. The nearest neighbour is **not** the one
+`test/evals/RESULTS.md` predicted:
+
+| Neighbour | Overlap |
+|---|---|
+| **`claude-mem:version-bump`** | **9.6%** |
+| `agent-sync` | 5.5% |
+| `task-pipeline` (the predicted one) | 4.7% |
+
+`version-bump` advertises "version increments across package.json,
+marketplace.json, plugin.json manifests, git tagging, GitHub releases, and
+changelog generation" — this skill's release checklist, and enabled alongside it.
+The overlap is not vocabulary, it is *job*.
+
+- The description now carries the clause `references/authoring.md` prescribes for
+  exactly this case: **NOT for a version bump or release in a repo that ships
+  anything but a skill or plugin.**
+- **`triggers.json` gains q21 and q22**, the same manifest-bump-and-release
+  request once where the artifact IS a skill and once where it is not, on
+  opposite sides of the split so the near-miss is measured in validation rather
+  than tuned on. 22 queries, 11 positive / 11 near-miss negative.
+- `RESULTS.md` records the measured table and drops the guess.
+
+### Added — the headroom rule reaches the field that decides triggering
+
+v0.11.0 gave the body a 5% working limit and left the description at 1003 of
+1024\. Adding the clause above needed 60 characters that did not exist — the same
+disease, in the field that decides whether the skill fires at all. Both the house
+validator and the bundled auditor (`--house`) now hold the description to **≤970
+of 1024**, with a negative self-test on each.
+
+### Verified, not assumed
+
+Every command the canon hands an agent was executed against the released
+artifact: `make-skill-audit` by bare name, the non-Claude fallback path, the
+raw-fallback reference URLs (200 — checked for the first time), `npx skills add
+--list` (no skeleton leaks), `npx` from a non-repo cwd, `claude plugin details`.
+The hook was exercised on all three of its paths and returns valid JSON. Building
+a skill from `assets/SKILL.template.md` and auditing it gives 0 GAP. The
+compression in v0.11.0 was checked against every fact the evaluation scenarios
+depend on: all of them are still reachable, and all 11 references are still
+linked from the body.
+
+The evaluation suite is still **authored and never executed against a model** —
+that gap needs a fresh session per query per model, and this pass does not close
+it. What it does show is why it matters: the risk this repo had written down was
+not the risk it had.
+
 ## v0.11.0 — 2026-08-10
 
 A file-by-file audit of the whole repo, run with this skill's own evidence rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "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.11.0",
+  "version": "0.11.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" / "сделай скилл", "new skill" / "новый скилл", "wrap it in a plugin" / "заверни в плагин", "publish a skill" / "опубликуй скилл", "retrofit a skill to the standard" / "приведи скилл к стандарту", "does this skill match the spec" / "соответствует ли скилл стандарту", "plugin.json / marketplace.json" / "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. Encodes the Agent Skills open standard AND Anthropic's platform rules (front-matter limits, disclosure budgets, Skills API surfaces, evals), the Claude Code plugin reference (manifest schemas, component layout, validate --strict), plus the proven ssheleg pipeline - marketplace layout, version sync, validator+CI, multi-agent distribution, npm gotchas, end-to-end first publish.
+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.
 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.11.0"
+  version: "0.11.1"
   homepage: https://github.com/ssheleg/make-skill
 ---
 
@@ -95,7 +95,9 @@ differences and the checklist: `references/agent-skills-spec.md`.
 House additions on top of the spec:
 
 - `description` starts "Use when …" and lists concrete trigger phrases — English
-  AND Russian (user works in both). A skill nobody triggers is dead weight.
+  AND Russian (user works in both). A skill nobody triggers is dead weight. Hold
+  **5% headroom here too** (≤970 of 1024): a near-miss neighbour forces a "NOT
+  for …" clause, and a description at 98% of cap has nowhere to put it.
 - One naming pattern, preferably gerund (`processing-pdfs`); never `helper`,
   `utils`, `tools`, `data` — vague names lose every selection.
 - One skill = one job. Multiple concerns → multiple skills + a shared contract
@@ -110,8 +112,8 @@ House additions on top of the spec:
 - **Evals before prose:** run the target task with NO skill, record the
   failures, write ≥3 evaluations against them, then write the minimum that
   passes; a skill built without a baseline documents imagined problems. Adding
-  to an existing family → test **coexistence**: a broad description steals the
-  triggers of the skills already installed.
+  to an existing family → **measure coexistence against the INSTALLED set**, do
+  not guess it: the neighbour you would name is usually not the nearest one.
 - Ship a one-command entry point: idempotent — inspect state → repair missing
   pieces → status report → exactly ONE suggested next action. Detect mode, never
   ask. **The skill IS that command**; the invocation differs by channel
@@ -290,9 +292,9 @@ agent is **A2A** (`a2a.md`). Non-negotiables for any such skill:
   chars/token, cl100k gives 3.8–4.5). Budget against a tokenizer and expect the
   CLI to look alarming for a body already inside 5000 real tokens.
 - **A number you typed by hand is an assertion, not documentation.** Counts of
-  files, steps and checklist items drift the release after you write them —
-  this canon shipped "13-item" beside "14-item" and "ten references" beside
-  eleven. Compute it, or have the validator compare it to the artifact.
+  files, steps and checklist items drift the release after you write them — this
+  canon shipped "13-item" beside "14-item". Compute it, or have the validator
+  compare it to the artifact.
 
 ## Release (every version)
 
@@ -308,8 +310,7 @@ session:
   --yes && rm -f ~/.claude/skills/<name>`, then remind about the restart;
 - **move the family pin in the SAME session.** A member released without its
   umbrella pin bumped is invisible: `list` advertises the old version and
-  `update` installs it. Seen here 2026-08-10 — npm served make-skill 0.10.0
-  while `sshlg-skills list` still said 0.9.1;
+  `update` installs it (seen here 2026-08-10);
 - **arm the tag-triggered release workflow** (`RELEASE_ENABLED`,
   `PUBLISH_NPMJS`, off by default) so the next release needs no human. Manual
   publishing is how a registry ends up behind its own tags — six of seven

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

@@ -30,6 +30,10 @@ import sys
 # --- limits, each with the authority that sets it --------------------------
 NAME_MAX = 64           # spec: name is 1-64 characters
 DESC_MAX = 1024         # spec: description is 1-1024 characters
+# House working limit: 5% under the cap. The description is the whole triggering
+# 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
 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
@@ -224,6 +228,14 @@ 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)
+        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' "
+                  "clause a near-miss neighbour will require"
+                  % (len(desc), DESC_MAX, DESC_TARGET), rel, ln)
+        elif len(desc) <= DESC_TARGET:
+            a.ok("DESC_HEADROOM", "description is %d/%d chars, inside the working limit"
+                 % (len(desc), DESC_TARGET), rel, ln)
 
 
 def _check_optional_fields(a, fm, lines, rel):