@ssheleg/make-skill 0.25.1 → 0.25.3

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## v0.25.3 — the runner we said did not exist, and the date a claim about someone else now carries
+
+- **B-122 closed: `references/authoring.md` told authors for four weeks that
+  there was no built-in eval runner, and prescribed a home-rolled suite on that
+  basis.** `claude plugin eval` had shipped. The section now names it, its case
+  format (`evals/<case>/case.yaml`, or `prompt.md` beside `graders/*.md`), and
+  the fact that `--ablation with-without` performs steps 3 and 5 of the very
+  procedure the paragraph prescribes by hand — plus the detail that it publishes
+  its HTML report to claude.ai unless `--no-publish` is passed, which is the
+  wrong default for an unreleased skill. **The replacement is a measurement, not
+  a correction of one absence into another**: on 2026-08-31, Claude Code 2.1.236,
+  every path (`eval`, `eval init`, `eval init --bare`, `eval <target>`) prints
+  ``plugin eval` is currently in early access`, writes nothing and exits 1, with
+  no settings key, environment variable or feature flag turning it on. That is
+  why `test/evals/` remains what runs here, and the paragraph says which day it
+  should be migrated. Two derived statements went with it: `distribution.md`'s
+  layout comment called the suite *"run by a human"*, and `retrofit.md`'s item 8
+  asked only that evaluations *exist* — the state MSK-01 had just spent a whole
+  run closing.
+- **The class, not the sentence: `THIRD_PARTY_CLAIMS` in `test/validate.py`.**
+  A load-bearing claim about someone else's tool is registered beside the command
+  that re-checks it, and the guard fails unless the claim, that command and an
+  ISO date still sit within eight lines of each other — and fails equally when a
+  registered claim has been deleted from the doctrine but left in the registry,
+  so the registry cannot outlive what it describes. The skill's own rule *"No
+  time-sensitive statements"* sits 100 lines above the sentence that broke it and
+  nothing enforced it; this is the enforcement.
+- **A generic detector was built first, measured, and rejected with the number.**
+  Over the shipped doctrine a pattern for absence-claims flagged **10 lines, of
+  which roughly half are legitimate** — the fallback rows of
+  `host-capabilities.md` ("on any other host there are no subagents") are made of
+  that sentence shape on purpose. A guard with a ~50% false-positive rate is the
+  over-defense that gets switched off, so the explicit registry replaced it; the
+  reasoning is recorded in the code beside the table rather than lost.
+- **The three plants are in CI, and the group count still computes.** Added as
+  cases to the existing *claims, budgets and runnable commands* step rather than
+  as a new step, so `grep -c 'name: Negative self-test'` stays at **9** and
+  `CONTRIBUTING.md`'s *"9 negative self-test groups"* — a claim this validator
+  compares against the workflow — remains true. Each case asserts its own
+  expected message. The first local run of the guard **passed its plants for the
+  wrong reason**: the claim wraps a line break and the check was line-anchored,
+  so all three plants tripped the registry-rot branch instead of their own. The
+  matcher is whitespace-tolerant now, and every plant in the block asserts it
+  changed something before the validator is asked anything.
+
+## v0.25.2 — the evals have been run, and the discovery check runs somewhere
+
+- **MSK-01 closed: the evaluation suite was executed against two models, and the
+  numbers live in `test/evals/RESULTS.md` as a dated run (2026-08-31), not a
+  claim.** All 22 trigger queries probed blind per model — haiku 22/22, sonnet
+  20/22 (q01 and q10 answered "none": under-triggering on positives, ZERO false
+  positives on the near-miss negatives across both models) — and all four
+  behavioural scenarios executed and scored per `expected_behavior` line (sonnet
+  31/35, haiku 24/35; the s01 repositories were re-audited with the bundled
+  auditor rather than trusted from the agent's report). The Method section
+  states the harness and its limits: one probe per query instead of the
+  README's fired/3, Agent-tool subagents on the author's machine whose global
+  config carries the family routing map (a bias that makes the clean negatives
+  the strongest result), model aliases rather than exact ids, and two probes
+  counted with a stated non-compliance caveat. Headline finding: the standing
+  worry (turn-stealing) did not materialize; the observed failure is sonnet
+  under-triggering on two positive categories, and s03-haiku answered a
+  surfaces question without consulting the installed skill — selection and
+  consultation measured apart, on purpose.
+- **MSK-03 closed: the discovery check the body demands now runs in CI.**
+  SKILL.md's stray-SKILL.md gotcha ends "verify with the skills CLI's `--list`"
+  — and nothing ran it anywhere: the operator machine's hygiene guard refuses
+  the bare skills CLI on family members by design, and CI never asked. The new
+  `skills-cli-discovery` job in `validate.yml` runs the listing against
+  `ssheleg/make-skill` and asserts it serves exactly ONE skill, named
+  make-skill, with ANSI stripped before asserting. Its own job, like
+  `claude-plugin-validate`, so a registry outage cannot mask an
+  offline-validator failure; it reads the repository's default branch, so the
+  post-merge push run and the release's `workflow_call` on the tag assert the
+  published tree.
+- **MSK-04 closed: body headroom restored by displacement — the words moved,
+  none were lost.** The Cyrillic budget measurement (1.9–2.3 chars/token,
+  3408→1885) moved to `authoring.md` → *Content guidelines*; the six skeleton
+  filenames moved into `distribution.md`'s layout tree; the five verified facts
+  and the machine-refresh command sequence are now referenced at their single
+  home in `distribution.md`'s checklists instead of being restated; the
+  long-file rule already lived in `authoring.md` and the body now points there.
+  Re-measured with the bundled auditor: body ~4742/4750 tokens (8 spare) →
+  ~4677/4750 (73 spare), after also paying for the next bullet. The
+  description is untouched at 965/970 — its headroom is spent only on trigger
+  changes, and this release makes none.
+- **XF-10: the MCP/A2A carve-out now runs both directions at the layer an agent
+  reads first.** The References-table rows for `mcp.md` and `a2a.md` carry "the
+  protocol wire itself → `agent-interop` (agent-stack)" — the two reference
+  files' own headers already said it, and now the router-level table says it
+  too, so a reader deciding what to load learns the boundary before opening
+  either file.
+- Also: `test/evals/README.md`'s file table said "20 realistic queries" over a
+  `triggers.json` holding 22 — the same drift class as MSK-02, in a wording no
+  guard could parse. Reworded to the checkable "22 trigger queries" form, which
+  puts the sentence under `test/validate.py`'s counted-claims sweep instead of
+  under anyone's memory. `SKILL-CARD.md`'s evaluation status and posture
+  sections now describe the executed run and the replication still owed,
+  instead of "never executed".
+
 ## v0.25.1 — the rule keeps its default, and the family's exception is written down
 
 - **The same-name command rule now carries its recorded exception** (operator

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.25.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.",
+  "version": "0.25.3",
+  "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",
     "plugin",

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.25.1",
+  "version": "0.25.3",
   "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.25.1"
+  version: "0.25.3"
   homepage: https://github.com/ssheleg/make-skill
 ---
 
@@ -27,8 +27,8 @@ orchestrator, release automation). **make-skill itself** is built to this canon.
 | `references/host-capabilities.md` | shipping a **hook, subagent, command, script or MCP dependency** — what each buys and costs, hook events and exit codes, the degradation clauses |
 | `references/claude-code-plugin.md` | anything shipping as a **Claude Code plugin/marketplace** — manifest schemas, component layout, path variables, `validate` failures |
 | `references/distribution.md` | the repo layout, releases, and all five channels — plugin, skills CLI, npx, Cursor, umbrella family repo |
-| `references/mcp.md` | skill vs **MCP** server, declaring the dependency, consent and untrusted-output rules |
-| `references/a2a.md` | the skill spans two autonomous agents (**A2A**) — choosing it, the two meanings of "skill", driving a peer safely |
+| `references/mcp.md` | skill vs **MCP** server, declaring the dependency, consent and untrusted-output rules; the protocol wire itself → `agent-interop` (agent-stack) |
+| `references/a2a.md` | the skill spans two autonomous agents (**A2A**) — choosing it, the two meanings of "skill", driving a peer safely; the wire itself → `agent-interop` (agent-stack) |
 
 Missing from this copy? Raw fallback:
 `raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<file>`
@@ -81,8 +81,8 @@ differences and the checklist: `references/agent-skills-spec.md`.
   99% of budget turns the next correction into a fight with the validator.
   Heavier material goes to `references/`, `scripts/`, `assets/` INSIDE the skill
   dir, one level deep, each linked from the body with a stated load trigger
-  ("read X when Y") — never a bare "see references/". Reference files >100 lines
-  open with a `## Contents` list: a partial `head` read is what agents get.
+  ("read X when Y") — never a bare "see references/". Long-file and layout rules:
+  `references/authoring.md` → *Content guidelines*.
 - Gotchas stay in `SKILL.md`: the agent can't know to open a file about a trap
   it doesn't know exists.
 - **Write for the weakest surface you claim** (`references/surfaces.md`): the
@@ -97,9 +97,8 @@ House additions on top of the spec:
   survives in four places only, where the string itself is the point: a
   **trigger phrase**, a **refusal phrase** (the operator types both — translated,
   they no longer match what was said), a **proper noun**, a **language example**
-  (`«вы»/«ты»`). A budget rule before a style one: Russian encodes at 1.9–2.3
-  chars/token against English's 5.0 (`cl100k`), and rewriting the eight ssheleg
-  routers into English cut them **3408 → 1885 tokens** with no loss of meaning.
+  (`«вы»/«ты»`). A budget rule before a style one — the measured cost of
+  Cyrillic prose is in `references/authoring.md` → *Content guidelines*.
 - `description` starts "Use when …" and lists concrete trigger phrases — English
   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
@@ -153,10 +152,9 @@ A fallback you know but did not write is not a fallback.
 Retrofit), wrapped as `bin/make-skill-audit` for Claude Code. Beside them:
 `hooks/` (PostToolUse, silent unless a `SKILL.md` was written),
 `commands/skill-audit.md` (deliberately NOT the skill's name),
-`agents/skill-auditor.md`, and six skeletons: `assets/SKILL.template.md`,
-`assets/plugin.template.json`, `assets/marketplace.template.json`,
-`assets/hooks.template.json`, `assets/agent.template.md`,
-`assets/command.template.md`.
+`agents/skill-auditor.md`, and six `assets/*.template.*` skeletons — one per
+component, filenames in `references/distribution.md` → *The distributable repo
+layout*.
 
 ## Create (personal)
 
@@ -196,8 +194,7 @@ regardless:
 Take it ALL the way, no half-done handoffs. Only the first publish needs a human
 (npm 2FA); **arming CI publishing is part of shipping**, so the second does not.
 **The 11-step sequence is in `references/distribution.md` → *First publish*.**
-Done = five VERIFIED facts: repo + CI green, npm resolvable via npx, plugin
-installed, skills-CLI discovery working, next tag publishing without a human.
+Done = the five VERIFIED facts in that sequence's step 10 — nothing assumed.
 
 ## Retrofit (bring an existing skill/repo up to standard)
 
@@ -310,9 +307,8 @@ session:
 - everything green BEFORE the tag: `python3 test/validate.py` plus BOTH
   `claude plugin validate … --strict` runs;
 - **refresh THIS machine's global installs as Definition of Done** (per global
-  `~/.claude/CLAUDE.md`): `claude plugin marketplace update <name>` →
-  `claude plugin update <name>@<name>` → `npx skills update <name> --global
-  --yes && rm -f ~/.claude/skills/<name>`, then remind about the restart;
+  `~/.claude/CLAUDE.md`) — the exact three-command sequence is checklist step 6;
+  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);

package/plugins/make-skill/skills/make-skill/references/authoring.md

@@ -155,6 +155,11 @@ the body.
   first 100 lines and never learn the rest exists.
 - **One level deep from `SKILL.md`.** A file reachable only through another file
   gets partially read or missed entirely. Every reference links from the body.
+- **English prose is a budget rule before a style one** (the house rule in
+  `SKILL.md` states which four literals stay Cyrillic). The measured cost:
+  Russian encodes at 1.9–2.3 chars/token against English's 5.0 (`cl100k`), and
+  rewriting the eight ssheleg routers into English cut them **3408 → 1885
+  tokens** with no loss of meaning.
 
 ## Scripts — the rules that separate a script from a liability
 
@@ -237,8 +242,24 @@ skill documents imagined problems.
 4. **Write the minimum** that fixes the gaps.
 5. **Iterate** — re-run, compare to baseline, refine.
 
-Evaluation record — there is no built-in runner, so keep them in the repo as
-data and run them yourself. House layout: `test/evals/triggers.json` (~20
+**The upstream runner exists — check whether it runs for you before building
+around it.** `claude plugin eval <target>` reads `evals/<case>/case.yaml`, or a
+`prompt.md` beside `graders/*.md`, and `--ablation with-without` runs the
+no-plugin arm and reports the delta — steps 3 and 5 above, performed for you.
+It defaults to publishing its HTML report to claude.ai; `--no-publish` keeps it
+local, which is the right default for an unreleased skill.
+
+**Measured 2026-08-31 on Claude Code 2.1.236: every path — `eval`, `eval init`,
+`eval init --bare`, `eval <target>` — prints ``plugin eval` is currently in
+early access`, writes nothing and exits 1.** No settings key, environment
+variable or feature flag on that machine turned it on. That is why the layout
+below exists and is what actually runs here; the day `claude plugin eval --help`
+is followed by a run rather than that line, this suite is the one to migrate.
+**Re-check before trusting either half of this paragraph** — an absence is the
+most perishable thing a document can assert, and nothing in this repository
+changes on the day it stops being true.
+
+House layout: `test/evals/triggers.json` (~20
 queries, half near-miss negatives) and `test/evals/scenarios.json` (≥3, the
 shape below), with any input under `test/evals/fixtures/` — **never named
 `SKILL.md`**, which would ship as a real skill:

package/plugins/make-skill/skills/make-skill/references/distribution.md

@@ -51,7 +51,11 @@ the shape from `ssheleg/super-ux`:
 │   ├── .claude-plugin/plugin.json      # ONLY the manifest lives in .claude-plugin/
 │   ├── skills/<skill>/SKILL.md  +  references/*.md  +  scripts/  +  assets/
 │   │                                   # skeletons live HERE, not at the repo root:
-│   │                                   # only the skill dir travels on every channel
+│   │                                   # only the skill dir travels on every channel.
+│   │                                   # make-skill ships six: SKILL.template.md,
+│   │                                   # plugin.template.json, marketplace.template.json,
+│   │                                   # hooks.template.json, agent.template.md,
+│   │                                   # command.template.md
 │   ├── bin/<exe>                       # Claude Code puts this on the Bash PATH:
 │   │                                   # the only reliable way to hand the agent
 │   │                                   # a runnable command (no path variable)
@@ -61,7 +65,7 @@ the shape from `ssheleg/super-ux`:
 ├── cursor/rules/*.mdc                  # if agent-rules make sense for Cursor
 ├── bin/<name>.js + package.json        # npx installer (zero-dep Node)
 ├── test/validate.py                    # consistency validator (stdlib only)
-├── test/evals/                         # triggers.json + scenarios.json (data, run by a human)
+├── test/evals/                         # triggers.json + scenarios.json (driven here; `claude plugin eval` is gated, authoring.md)
 ├── .github/workflows/validate.yml      # validator on push+PR (+ release.yml, off by default)
 ├── install.sh                          # POSIX fallback
 ├── README.md (English-first), CHANGELOG.md, LICENSE (MIT)

package/plugins/make-skill/skills/make-skill/references/retrofit.md

@@ -98,11 +98,13 @@ Report the table before changing anything, then fix.
 7. **Validator**: present, green, and able to fail — run the negative test. CI
    present, last run `success`, with `claude plugin validate --strict` as its own
    job so an upstream outage cannot mask a house failure.
-8. **Evaluations** exist in `test/evals/` (`references/authoring.md`): ≥3
+8. **Evaluations** exist and have been executed (`references/authoring.md`): ≥3
    behavioral scenarios, a trigger set whose negatives are near-misses, both
    classes on both sides of the train/validation split, coexistence checked
    against the skills already installed, and a re-run on every model the skill
-   claims support for.
+   claims support for. Try `claude plugin eval` first and record what it did —
+   authored-but-never-executed is the state this item exists to catch, and the
+   house layout in `test/evals/` is the fallback for when that runner is gated.
 9. **README**: badges (npm/CI/license), install + update matrix, English-first
    prose, and the bundled `references/` listed so a reader sees what ships.
 10. **Distribution live-checks** (`references/distribution.md`): `npx --yes