@ssheleg/make-skill 0.27.1 → 0.28.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## v0.28.0 — the house audit measures the token budget instead of estimating it
+
+Sherlock external-v3 (13 findings) plus the enterprise handoff (PR #18) and the
+CI correction the audit forced across the family.
+
+- **The house auditor was issuing a token verdict from an estimate.** With no
+  tokenizer on the runner it fell back to chars/3.9 and gapped seven family
+  skills that are all inside the limit when actually measured. That is the defect
+  this script's own doctrine names (FIX-MS-01.01): the estimate overshoots prose
+  carrying Russian and code, and a verdict from the wrong instrument wearing the
+  right instrument's name is worse than no verdict. Every member's CI now
+  installs tiktoken and pins this version, so the budget is MEASURED.
+- `references/enterprise.md` gains the dependency-closure and provenance
+  material for reviewing or adapting someone else's skill.
+- The reworded row that pointed at it hit exactly the 4750 working limit this
+  repo's own validator refuses — tightened rather than waived.
+
 ## 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

package/README.md

@@ -164,6 +164,7 @@ agent opens only when the situation calls for them:
 | `surfaces.md` | Claude Code vs the Claude API vs claude.ai — the Skills API (upload, versions, 8 per request), and the no-network / no-package-install limits that break scripts moved between surfaces |
 | `enterprise.md` | installing a skill you didn't write, and running a fleet — risk tiers, the review checklist, the five approval gates, lifecycle, recall limits, rollback |
 | `retrofit.md` | the audit procedure — the 14-item checklist, what counts as evidence for a PASS, and the short form for a personal skill |
+| `outcome-evaluation.md` | the outcome-eval method — frozen inputs, baseline-vs-current arms, artifact checks, the routing/correctness/visual split, and PASS/FAIL/ERROR/NOT_RUN verdicts with no host-locked actor |
 | `host-capabilities.md` | hooks, subagents, commands, scripts and MCP dependencies — what each buys, what it costs in always-on tokens, hook events and exit-code semantics, and the degradation clauses that keep a skill working where none of them exist |
 | `claude-code-plugin.md` | the [Claude Code layer](https://code.claude.com/docs/en/plugins-reference) — `plugin.json` / `marketplace.json` schemas, plugin sources, component locations, host-only front-matter, path variables, cache and symlink rules, the `claude plugin` CLI |
 | `distribution.md` | the repo layout, every install channel, exact CLI flags, npm publishing traps, the release checklist |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.27.1",
+  "version": "0.28.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.",
   "keywords": [
     "skill",
@@ -47,6 +47,7 @@
     "node": ">=16"
   },
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && python3 test/checker_parity_test.py && python3 test/residue_test.py && node test/installer_test.js"
+    "test": "python3 test/validate.py && python3 test/plant_guard_test.py && python3 test/checker_parity_test.py && python3 test/residue_test.py && node test/installer_test.js && npm run test:audit",
+    "test:audit": "for t in test/audit_regressions/*.py; do python3 \"$t\" || exit 1; done"
   }
 }

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.27.1",
+  "version": "0.28.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.27.1"
+  version: "0.28.0"
   homepage: https://github.com/ssheleg/make-skill
 ---
 
@@ -22,8 +22,9 @@ orchestrator, release automation). **make-skill itself** is built to this canon.
 | `references/agent-skills-spec.md` | authoring or auditing ANY `SKILL.md` — hard limits from both authorities, optional fields, budgets, who rejects what |
 | `references/authoring.md` | writing or tuning a body/description — naming, third person, degrees of freedom, script rules, eval loops |
 | `references/surfaces.md` | shipping anywhere but Claude Code — Skills API upload/versions/8-per-request, claude.ai zip, the no-network limits |
-| `references/enterprise.md` | installing someone else's skill, or governing a fleet — risk tiers, review checklist, approval gates, lifecycle |
+| `references/enterprise.md` | reviewing, adapting or installing an external skill — dependency closure, provenance, risk tiers, lifecycle |
 | `references/retrofit.md` | auditing an existing skill/repo — the 14-item checklist, the evidence rules, the personal-skill short form |
+| `references/outcome-evaluation.md` | proving a skill changed real outcomes — frozen inputs, baseline vs current, artifact checks, the routing/correctness/visual split, PASS/FAIL/ERROR/NOT_RUN |
 | `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 |
@@ -45,9 +46,8 @@ Detect from the request and any path in `$ARGUMENTS`; announce the choice.
 | Personal skill should become installable | Promote |
 
 With no argument, **detect instead of asking**: a `SKILL.md`, `.claude-plugin/`
-or `plugins/*/skills/*/` in the current directory → run the Retrofit audit and
-report the gap table plus ONE next action. Nothing to detect → ask in one line
-what to create.
+or `plugins/*/skills/*/` here → run the Retrofit audit, report the gap table
+plus ONE next action. Nothing to detect → ask in one line what to create.
 
 Distributable work is a real project: spec (`docs/evidence/specs/`) before
 code, and the spec locks target-project file contracts FIRST — skills are
@@ -129,20 +129,19 @@ House additions on top of the spec:
 
 ### Degradation contract (every skill that touches a host capability)
 
-Hooks, subagents, `/commands`, plugin path variables and MCP servers exist only
-inside Claude Code — a minority of where skills run. **Each is an accelerator
-with a written fallback; the skill still finishes its job without it, more
-slowly.** Write the three cases into the body, in the agent's words, at the
-point it will need them (shapes: `references/host-capabilities.md`):
-
-- **Not Claude Code** (Cursor, Codex, skills CLI, API): no hooks, no subagents,
-  no `/command`. Name the inline procedure; bundled `scripts/` still travel, so
-  give the path per channel.
-- **Recommended plugin/skill absent**: say once what is degraded, continue on
-  the manual path. A stage that refuses to start because an optional companion
-  is missing is broken, not strict.
-- **Tool, interpreter or MCP server absent**: state it once, fall back to the
-  by-hand procedure, never retry in a loop. Interactive auth is a human step.
+Hooks, subagents, `/commands`, plugin path variables and MCP servers are HOST
+capabilities that vary by host AND version — subagents and MCP are native to
+some non-Claude runtimes, so DETECT them, never assume "Claude Code only".
+**Each is an accelerator with a written fallback; the skill finishes its job
+without it, more slowly** — a portable body names the inline procedure, not one
+host's exact tool spelling. Write the three fallback cases into the body, in
+the agent's words, at the point it will need them — a HOST lacking a capability
+(the set differs per host: not every non-Claude runtime lacks subagents/MCP), a
+recommended companion absent, and a tool/interpreter/MCP server absent (state it
+once, fall back by hand, never loop; interactive auth is a human step). The
+fallback shapes are in `references/host-capabilities.md`; the per-host
+capability matrix (with each norm's owner and check date) in
+`references/agent-skills-spec.md`.
 
 A fallback you know but did not write is not a fallback.
 
@@ -198,28 +197,25 @@ Done = the five VERIFIED facts in that sequence's step 10 — nothing assumed.
 
 ## Retrofit (bring an existing skill/repo up to standard)
 
-Audit first, fix second, in the same session. Verdict per item: PASS / GAP /
-NOT-RUN with evidence — a `file:line` or the output of the command you actually
-ran. "Looks fine" is not a verdict, and neither is a PASS on a check that was
-reasoned about instead of executed; a check whose tool is absent is **NOT-RUN
-with the reason**, never a PASS.
-
-**Run the bundled auditor first** — it does the mechanical half
-deterministically, and it never depends on an unset variable:
-
-```bash
-make-skill-audit <skill-dir> --house    # Claude Code: the plugin's bin/ is on PATH
-```
-
-Anywhere else, run `scripts/audit_skill.py` from the make-skill directory you
-just read this from. **Then work the 14-item checklist in
-`references/retrofit.md`** — spec floor, plugin floor, surfaces, one-job, entry
-point, layout and version sync, validator and CI, evaluations, README,
-distribution, repo meta, gotchas, protocols, host capabilities. For a PERSONAL
-skill only three items apply; that file says which.
-
-**Then:** report the gap table, fix everything fixable now, bump a minor/patch
-version, run the release checklist.
+**Three modes, three effect contracts (MS-03): `audit` reads (evidence + plan
+only); `retrofit` writes only what the request scoped; `release` publishes.**
+The move between them is decided by INTENT and prior authorization, never by
+the skill invoked — a compliance QUESTION stays an audit («аудит скилов» asks
+for a verdict, not a diff). Verdict per item: PASS / GAP / NOT-RUN with
+evidence — a `file:line` or the command's actual output. "Looks fine" is not a
+verdict, nor is a PASS reasoned about instead of executed; a check whose tool
+is absent is **NOT-RUN with the reason**, never a PASS.
+
+**Run the bundled auditor first** (the deterministic mechanical half), then
+work the 14-item checklist — both the `make-skill-audit --house` invocation
+and the checklist live in `references/retrofit.md`; a PERSONAL skill owes only
+three of the items.
+
+**Then: report the gap table — and stop there in `audit` mode.** Only with
+`retrofit` granted: fix what the report names; only with `release`: bump
+minor/patch and run the release checklist. Load
+`references/outcome-evaluation.md` only when the work CHANGES behaviour — a
+conformance audit stops at its report, no outcome arms.
 
 ## Promote (personal → distributable)
 

package/plugins/make-skill/skills/make-skill/references/agent-skills-spec.md

@@ -134,9 +134,40 @@ Rules:
 |---|---|---|
 | `skills-ref validate ./<skill dir>` | the open standard's frontmatter rules | Python, installed from source out of `github.com/agentskills/agentskills`; not on npm or PyPI |
 | Skills API upload | Anthropic's extra rules (reserved words, XML tags, dir name, 30 MB) | the only place they are enforced — see `references/surfaces.md` |
-| `claude plugin validate … --strict` | plugin/marketplace **manifests only**, not SKILL.md frontmatter | `references/claude-code-plugin.md` |
+| `claude plugin validate … --strict` | plugin/marketplace manifests — AND, since Claude Code v2.1.233, `SKILL.md` frontmatter in skill directories too (version-gate the claim; older builds validated manifests only) | `references/claude-code-plugin.md` |
 | your `test/validate.py` | house rules + everything the three above miss | the only one that runs on every commit |
 
+## Host capability matrix — presence varies by host AND version (MS-04)
+
+"Claude Code only" is wrong for several of these: some non-Claude runtimes
+(Codex) provide subagents and MCP natively. DETECT the capability; do not
+assume its absence. Presence is per host AND per version.
+
+| Capability | Claude Code | Codex | Cursor | skills CLI / API | Detect by |
+|---|---|---|---|---|---|
+| Hooks | yes | no | no | no | host docs / config |
+| Subagents | yes | **yes (native)** | no | no | runtime probe |
+| MCP servers | yes | **yes (native)** | varies | no | runtime probe |
+| `/commands` | yes | no | no | no | host docs |
+| Plugin path vars | yes | no | no | no | env presence |
+
+And every NORM this skill enforces carries its **owner** (spec = the Agent
+Skills standard, host = a runtime's own rule, house = this family), whether it
+is **required vs recommended**, and the **date last verified against source** —
+a number with no owner reads as physics, and an unversioned norm has no expiry:
+
+| Norm | Owner | Required? | Last checked |
+|---|---|---|---|
+| `name` ≤ 64 chars, `description` ≤ 1024 | spec | required | 2026-09-09 |
+| body < 5000 tokens | spec | recommended | 2026-09-09 |
+| body < 4750 tokens (headroom) | house | recommended | 2026-09-09 |
+| Skills API: 8 skills/request, 30 MB | host | required (that surface) | 2026-09-09 |
+| `--strict` validates SKILL.md frontmatter | host (Claude Code ≥ v2.1.233) | n/a | 2026-09-09 |
+
+A recommendation (500 lines, 5000 tokens, the house limits) is a QUALITY norm,
+not a universal reason a host refuses to LOAD the skill — a body over budget is
+worse authoring, not an install error everywhere.
+
 ## Conformance checklist
 
 - [ ] `name`: matches dir, ≤64 chars, `[a-z0-9-]`, no leading/trailing/double

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

@@ -20,6 +20,7 @@ and [agentskills.io](https://agentskills.io/skill-creation/best-practices).
 - Body patterns worth copying
 - Workflows and feedback loops
 - Content guidelines (terminology, time, paths, table of contents)
+- Selective loading — every reference earns its tokens
 - 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
@@ -157,6 +158,10 @@ field makes the agent worse than it was without the skill.
 - **Add what the agent lacks**; cut anything it already knows. Test: "would the
   agent get this wrong without this line?" No → delete it.
 - **Procedures over answers** — teach the method, not one instance's result.
+- **Copying from OUTSIDE** — when a body pattern is borrowed from an external
+  source rather than written fresh, route the intake through the source/runtime
+  contract in `references/enterprise.md` (§ Selective knowledge adoption): a
+  pinned permalink and an attribution receipt, and no-key is not no-dependency.
 
 ## Workflows and feedback loops
 
@@ -201,6 +206,46 @@ the body.
   rewriting the eight ssheleg routers into English cut them **3408 → 1885
   tokens** with no loss of meaning.
 
+## Selective loading — every reference earns its tokens
+
+A reference is a loan against the context window, and the load condition is the
+contract that says when the loan is worth taking. Three rules, each of which has
+been paid for:
+
+- **Every reference states its own load condition** — the `**Load this when:**`
+  opener this file itself uses, or a "read X when Y" sentence at the link site in
+  `SKILL.md`. "See `references/`" is a pointer at a directory: it loads either
+  everything (the budget bleeds on every turn) or nothing (dead doctrine), and
+  `scripts/audit_skill.py` flags it. A condition names the situation, not the
+  file: "read `references/mcp.md` when the skill must reach an MCP server", never
+  "additional details in mcp.md".
+- **Split primary from appendix, and say which is which.** Primary material is
+  what a decision REQUIRES: the contract, the acceptance criteria, the failure
+  modes. Appendix material is depth — worked examples, history, fixtures — that
+  can stay unloaded without changing any decision. The split decides what a
+  budget cut may touch: **mandatory decisions and acceptance are never truncated
+  to fit a budget; the appendix is.** A body that trimmed its acceptance to make
+  a line count fit has traded the contract for the heuristic that was supposed
+  to protect it. Variants follow the same rule: where a reference exists in more
+  than one language or platform flavour, the load condition names WHICH variant a
+  given task requires, and only that one is loaded — a multilingual bundle that
+  loads every variant pays for the same knowledge twice.
+- **A required reference that does not resolve blocks the work.** If the body
+  says a decision depends on `references/x.md` and the file is absent, the audit
+  gap is a stop, not a warning — proceeding without the contract is how a skill
+  ships with half its acceptance. `audit_skill.py` exits non-zero on exactly
+  this.
+
+**The budget is tokens, and lines are only a heuristic.** "500 lines / 5000
+tokens" pairs a length heuristic with the real limit; the 500 never proves the
+5000. A multilingual body makes the gap concrete: Russian encodes at 1.9–2.3
+chars/token against English's 5.0 (`cl100k`), so 300 Cyrillic lines can out-cost
+500 English ones. A token figure is therefore either **measured by a named
+tokenizer** or **an explicitly labeled estimate** — `audit_skill.py` reports
+`~N tokens (chars / 3.9)`, and the divisor is printed because an estimate that
+hides its basis reads as a measurement. Never state a bare token count nothing
+computed.
+
 ## Scripts — the rules that separate a script from a liability
 
 A bundled script is more reliable than generated code, costs no context (only its
@@ -273,7 +318,10 @@ gate's own output.
 ## Evaluation and iteration — evals before prose
 
 **Build the evaluations before writing extensive documentation.** Otherwise the
-skill documents imagined problems.
+skill documents imagined problems. The judging method — frozen inputs, the
+baseline arm, artifact checks, the routing/correctness/visual split and the
+PASS/FAIL/ERROR/NOT_RUN verdicts — is `references/outcome-evaluation.md`; read
+it when a verdict is about to be written down.
 
 1. **Identify gaps** — run the agent on representative tasks with NO skill.
    Record the specific failures.
@@ -340,6 +388,8 @@ quality — are in `references/enterprise.md`.
 - [ ] Name follows one pattern, is not vague, contains no reserved word
 - [ ] Body under 500 lines / 5000 tokens; detail in one-level-deep files
 - [ ] Every reference has a stated load condition; >100-line ones have a TOC
+- [ ] Primary (decisions, acceptance) split from appendix; cuts only ever hit the appendix
+- [ ] Token figures are measured by a named tokenizer or labeled as estimates with their basis
 - [ ] Degrees of freedom match task fragility
 - [ ] No time-sensitive statements outside an "Old patterns" section
 - [ ] Consistent terminology; forward slashes everywhere

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

@@ -397,6 +397,24 @@ npx <name>                                     # from a NON-repo cwd
 claude plugin update <name>@<name>             # full id required
 ```
 
+## The publishable payload — what must NOT ride along
+
+The auditor's `DIST_*` checks (`scripts/audit_skill.py`) and this section are
+one rule: a payload is what a consumer receives, and two things leak into it by
+accident.
+
+- **An outward symlink.** A skill installed by symlink is correct; a symlink
+  INSIDE the payload pointing OUTSIDE it is not — it resolves on the author's
+  machine and dangles (or leaks a path) everywhere else. `npm pack` follows the
+  files allowlist, but a symlink caught by a glob ships as a link, so keep the
+  package's own files real and let installation create the links.
+- **An undeclared secret.** A `.env`, a `*token*` fixture, an `id_rsa`,
+  anything whose name reads as a credential must be excluded — `.npmignore` or
+  the `files` allowlist, and the auditor names any that remain. A closure
+  validated against the WHOLE checkout passes while the PACKAGED copy is
+  missing a required reference or carrying a secret; validate the payload, not
+  the checkout — `npm pack --dry-run` prints exactly what ships.
+
 ## Release checklist (every version)
 
 1. Bump the four versions together (`package.json` only if npm-distributed — else

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

@@ -20,6 +20,7 @@ plus the security section of the
 - Registry — what to record per skill
 - Recall limits and consolidation
 - Versioning, rollback, integrity
+- Selective knowledge adoption
 
 ## Why this is a security boundary at all
 
@@ -94,6 +95,31 @@ Reading the results: declining trigger accuracy → fix the description; coexist
 conflicts → narrow descriptions or merge the skills; persistently low output
 quality → rewrite or add validation; persistent failure across updates → deprecate.
 
+## Selective knowledge adoption — the source/runtime contract
+
+When a skill BORROWS from an external source — a snippet, a method, a whole
+reference — the intake is ONE canonical procedure, and it reaches a verdict
+WITHOUT calling any setup, login or provider: classification is reading, not
+running. Four verdicts, keyed by what the source actually needs:
+
+| The source... | Verdict | Why |
+|---|---|---|
+| authenticates by **OAuth but ships no key** | ADOPT, **declare the dependency** | no key is not "no dependency" — the runtime still needs the OAuth service; declare it, do not conclude it is free-standing |
+| runs an **`npx <tool>` with the package undeclared** | REJECT the undeclared runtime fetch, or **declare the exact package+version** | an `npx` at runtime is a supply-chain edge; an undeclared one is a fetch of whatever the registry serves that day |
+| ships **no license** | DO NOT COPY the bytes | reference the METHOD (procedures over answers), never vendor unlicensed source; adopt only what you may |
+| names a **deprecated source** | adopt the **method**, not the bytes; note the deprecation | pinning to a dead/moving ref imports a liability with an expiry |
+
+Two receipts every adoption carries:
+
+- **A pinned permalink** to the exact source revision (a commit-addressed URL,
+  never a branch tip) for anything copied OR adapted — the bytes must be
+  traceable to what they came from.
+- **An attribution receipt** — who wrote it, under what license, adapted how —
+  beside the borrowed content, so the next reader can re-verify the chain.
+
+`references/authoring.md`'s body-pattern list routes here whenever a pattern is
+copied from outside rather than written fresh.
+
 ## Lifecycle
 
 1. **Plan** — pick workflows that are repetitive, error-prone, or need specialist
@@ -139,3 +165,44 @@ user's active set stays focused.
   signed commits in the skill repo so provenance is more than a claim.
 - **Git is the source of truth**, one directory per skill, changes through pull
   requests — which also gives you the rollback and the audit trail for free.
+
+## Selective knowledge adoption
+
+Reviewing a collection does not mean installing it. When the operator wants
+methods without new dependencies, distinguish a transferable method from the
+upstream workflow, runtime, assets and services that happen to deliver it.
+
+1. Freeze the repository commit and inventory skills, commands, referenced files,
+   scripts, bundled binaries, submodules and remote marketplace entries. Mark
+   what was read semantically and what was only scanned. A directory listing or
+   search hit is not a complete audit of its contents.
+2. Record the applicable license/NOTICE at the file or subtree level. Do not
+   infer every subtree's terms from the root or a front-matter label. An unclear
+   or restricted copying grant is a reference-only outcome, not a reason to
+   remove attribution. Preserve required notices for any permitted adaptation.
+3. Trace the proposed transfer's dependency closure: required local references,
+   interpreters/packages, commands, host APIs, MCP servers, credentials, runtime
+   fetches, fonts/images, installer and update behavior. Repository build tools
+   and optional test tooling are distinct from runtime requirements.
+4. Choose explicitly: adapt a bounded method, retain as a reference, offer an
+   optional adapter, defer for missing evidence, or reject. Do not install an
+   upstream orchestrator merely to obtain its typography or review checklist.
+5. Author the smallest local procedure that fills a measured gap. Name its
+   family owner and router. Keep existing paths and shared artifact contracts;
+   avoid a second brand folder, plan format or always-on workflow. Reuse an
+   existing skill/mode unless a separate invocation has a distinct user job.
+6. For dependency-free core, require no new credential, service, automatic
+   download or mandatory external package. Use the host's already available
+   capabilities or a documented inline path. Optional tooling must remain
+   optional in the exit criteria; lack of a renderer means NOT_RUN for visual
+   inspection, never an invented screenshot verdict.
+7. Test the isolated transfer's reference closure and absence of unintended
+   network/credential requirements. Compare actual outputs on representative
+   tasks with the existing setup, including no-op, ambiguity and coexistence.
+   An improved instruction or structural PASS is not an observed quality gain.
+
+The transfer record contains source commit/path/digest, scope read, relevant
+terms, method retained, material excluded, destination, dependency decisions,
+acceptance cases and the future update owner. No external text acquires higher
+instruction priority because it was fetched during this review. Do not execute
+foreign installers or scripts simply to inventory them.

package/plugins/make-skill/skills/make-skill/references/outcome-evaluation.md

@@ -0,0 +1,58 @@
+# Outcome evaluation — judging what the skill produced, not what it said
+
+**Load this when:** proving a skill changed real outcomes — before a release,
+after a retrofit, or when two versions disagree. The eval loop in
+`references/authoring.md` says WHEN to eval (before prose, against a baseline);
+this file is the METHOD: what is frozen, what is compared, and what a verdict
+is allowed to mean.
+
+## The method, in one table
+
+| Element | Rule |
+|---|---|
+| Inputs | **frozen** — the same prompts, files and fixtures for every arm; an input that drifts between arms measures the drift, not the skill |
+| Arms | **baseline without the skill** and **the current skill version** — two runs, same inputs; a delta with no baseline arm is a number with no zero |
+| What is judged | **actual artifacts** — the file written, the diff produced, the page rendered; never the transcript's claim that it did so ("wrote the file" in prose is not the file) |
+| Actors | the host supplies the tool names — a CLI, a browser, a subagent are ways to RUN an arm, and **no specific one is mandatory**; an eval hard-wired to one host's tool cannot run anywhere else, which is a hostlock wearing a harness |
+
+## Three judgments, never blended
+
+One eval row answers ONE of these, and the report keeps the axes apart:
+
+- **Routing** — did the skill fire when it should, and stay quiet when it
+  should not? Judged on trigger behaviour alone; a perfect output from a skill
+  that fired on the wrong prompt is a routing failure with good manners.
+- **Output correctness** — is the artifact right? Judged mechanically where
+  possible (a validator, a diff against an expected shape, an exit code), by
+  rubric where not.
+- **Visual judgment** — does the rendered thing read well? A human-or-judge
+  call on the artifact's presentation. It never stands in for correctness: a
+  beautiful wrong answer fails, an ugly right one passes and files a note.
+
+Blending them is how a skill "improves" on paper: one blended score lets a
+routing regression hide behind a correctness win.
+
+## Verdicts: PASS, FAIL, ERROR, NOT_RUN
+
+- **PASS / FAIL** — the judgment ran against the artifact and answered.
+- **ERROR** — the process broke: the arm crashed, the fixture was malformed,
+  the judge threw. An error is its own status; folding it into FAIL blames the
+  skill for the harness, and folding it into PASS is fiction.
+- **NOT_RUN** — the tool the case needs is absent on this host (no browser, no
+  subagent, no network where one is required). NOT_RUN is never PASS, and it
+  names what it would take to run — the same contract the accessibility and
+  audit doctrines hold.
+
+An aggregate over rows inherits the weakest honesty: any ERROR or NOT_RUN in a
+set means the set is not "all green", however many PASSes surround it.
+
+## Worked examples, one per axis
+
+```
+axis: routing      input: "подключи оплату картой"        expect: stripe-billing fires
+axis: routing      input: "explain what a webhook is"     expect: no skill fires
+axis: correctness  artifact: the generated SKILL.md       check: audit_skill.py exits 0
+axis: visual       artifact: the rendered landing hero    check: judge rubric §type-rhythm
+```
+
+Four rows, three axes, and no row's verdict can move another's.

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

@@ -92,7 +92,139 @@ 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.
+# AND the estimate is an ESTIMATE (FIX-MS-01.01): a 16 000-hieroglyph body is
+# 16 000 cl100k tokens and estimates ~4 102 — so the estimate never grants a
+# token PASS and is never CALLED tokens. A real, NAMED tokenizer measures;
+# without one the token budget is UNMEASURED and the estimate rides beside it
+# as its own field.
 CHARS_PER_TOKEN = 3.9
+
+# Optional tokenizer adapter. `None` = unresolved; tests may inject
+# `(callable, "name")` or `(None, None)` directly to pin either path.
+# `MAKE_SKILL_TOKENIZER` selects a tiktoken encoding by name; an UNSUPPORTED
+# name refuses to measure (a warning + UNMEASURED) — it never silently falls
+# back to another encoding or to the estimate, because a verdict from the
+# wrong instrument wearing the right instrument's name is worse than no
+# verdict (FIX-MS-01.02).
+TOKENIZER = None
+DEFAULT_ENCODING = "cl100k_base"
+
+# Who owns each threshold — `spec` is the Agent Skills standard / Anthropic's
+# platform rules, `house` is this family's working rule, `host` would be a
+# per-host runtime limit. A number without its authority reads as physics;
+# these are policies, each negotiable only with its owner.
+THRESHOLDS = {
+    "BODY_MAX_LINES": ("spec", 500),
+    "BODY_MAX_TOKENS": ("spec", 5000),
+    "BODY_TARGET_TOKENS": ("house", 4750),
+    "DESC_MAX_CHARS": ("spec", 1024),
+}
+
+# The differential corpus: pinned counts for DEFAULT_ENCODING, measured with
+# tiktoken 0.14.0 (2026-09-09). Same string + same tokenizer revision must give
+# the same measured count on every machine — a drift here means the adapter
+# or the encoding changed, and either is a finding, never a rounding error.
+TOKEN_CORPUS = {
+    "english": ("the quick brown fox jumps over the lazy dog", 9),
+    "code": ("def verify(sig, key):\n    return hmac.compare_digest(sig, key)\n", 15),
+    "russian": ("проверка бюджета токенов выполняется настоящим токенизатором", 28),
+    "mixed": ("body budget: бюджет тела — 5000 tokens, не оценка", 22),
+    "cjk": ("字符预算不是估计值", 9),
+}
+
+
+def resolve_tokenizer():
+    global TOKENIZER
+    if TOKENIZER is None:
+        name = os.environ.get("MAKE_SKILL_TOKENIZER") or DEFAULT_ENCODING
+        # tiktoken caches encoding data in TMPDIR by default — residue a test
+        # run must not leave. A stable per-user cache, unless the operator
+        # already chose one.
+        os.environ.setdefault("TIKTOKEN_CACHE_DIR", os.path.join(
+            os.path.expanduser("~"), ".cache", "make-skill", "tiktoken"))
+        try:
+            import tiktoken
+            enc = tiktoken.get_encoding(name)
+            TOKENIZER = (lambda text: len(enc.encode(text)), f"tiktoken:{name}")
+        except Exception as exc:
+            if os.environ.get("MAKE_SKILL_TOKENIZER"):
+                print(f"audit: tokenizer {name!r} is unsupported ({exc}) — token "
+                      "budgets are UNMEASURED, not silently re-measured with a "
+                      "different encoding", file=sys.stderr)
+            TOKENIZER = (None, None)
+    return TOKENIZER
+
+
+def corpus_check():
+    """The adapter against the pinned oracle. Returns (verdict, detail):
+    'agree' when every sample matches its pinned count, 'NOT_RUN' without a
+    tokenizer, 'DISAGREE' naming the first divergent sample."""
+    count_fn, tok_name = resolve_tokenizer()
+    if count_fn is None:
+        return "NOT_RUN", "no tokenizer installed — the differential did not run"
+    if tok_name != f"tiktoken:{DEFAULT_ENCODING}":
+        return "NOT_RUN", (f"corpus counts are pinned for {DEFAULT_ENCODING}; "
+                           f"{tok_name} is a different instrument")
+    for name, (sample, pinned) in sorted(TOKEN_CORPUS.items()):
+        got = count_fn(sample)
+        if got != pinned:
+            return "DISAGREE", (f"{name}: adapter says {got}, the pinned oracle "
+                                f"says {pinned} — same string, same revision, "
+                                "different count")
+    return "agree", f"{len(TOKEN_CORPUS)} samples agree with {tok_name}"
+
+
+# Optional FULL-YAML conformance adapter (FIX-MS-02.02). The strict subset
+# parser is the always-available precheck; where a real YAML parser is ALSO
+# installed, it is used as an ORACLE — the subset parse is compared against it
+# on quoted scalars, escapes and multiline forms, and a divergence is a
+# reported finding. Without the parser there is NO PASS of a full-YAML check:
+# the verdict is NOT_RUN, never a green tick, and malformed input is always an
+# error rather than a silent pass.
+YAML_PARSER = None
+
+
+def resolve_yaml_parser():
+    global YAML_PARSER
+    if YAML_PARSER is None:
+        try:
+            import yaml
+            YAML_PARSER = (lambda s: yaml.safe_load(s), "pyyaml")
+        except Exception:
+            YAML_PARSER = (None, None)
+    return YAML_PARSER
+
+
+def yaml_conformance(frontmatter_text):
+    """Compare the strict-subset parse against a full YAML parser, where one is
+    installed. Returns (verdict, detail): 'agree' | 'DIVERGES: …' |
+    'MALFORMED: …' | 'NOT_RUN: …' (no parser). The subset parse never scores
+    a full-YAML PASS on its own."""
+    parse, name = resolve_yaml_parser()
+    if parse is None:
+        return "NOT_RUN", ("no full YAML parser installed — the strict subset "
+                           "precheck ran, but full-YAML conformance is unproven")
+    try:
+        real = parse(frontmatter_text)
+    except Exception as exc:                       # noqa: BLE001 — any parse error
+        return "MALFORMED", f"the real parser rejects this frontmatter: {exc}"
+    if not isinstance(real, dict):
+        return "MALFORMED", "frontmatter is not a mapping"
+    subset, _lines = parse_frontmatter(frontmatter_text)
+    diffs = []
+    for k in set(real) | set(subset):
+        rv, sv = real.get(k), subset.get(k)
+        if isinstance(rv, dict) and isinstance(sv, dict):
+            for kk in set(rv) | set(sv):
+                if rv.get(kk) != sv.get(kk):
+                    diffs.append(f"{k}.{kk}: subset {sv.get(kk)!r} vs {name} {rv.get(kk)!r}")
+        elif rv != sv:
+            diffs.append(f"{k}: subset {sv!r} vs {name} {rv!r}")
+    if diffs:
+        return "DIVERGES", "; ".join(sorted(diffs))
+    return "agree", f"the subset parse matches {name}"
+
+
 TOC_MIN_LINES = 100     # Anthropic: longer reference files need a table of contents
 
 SPEC_KEYS = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
@@ -116,6 +248,12 @@ TIME_BRANCH_RE = re.compile(
     r"november|december|\d{4})\b", re.I)
 BUNDLE_DIRS = ("references", "scripts", "assets")
 
+# A file in a publishable payload whose name reads as a credential. Fixtures and
+# test data are the common carriers; the auditor names it rather than shipping it.
+DIST_SECRET_RE = re.compile(
+    r"(?i)(?:^|[._/-])(?:secret|secrets|token|password|passwd|api[_-]?key|apikey|"
+    r"credential|credentials|\.env|id_rsa|id_ed25519|private[_-]?key)(?:$|[._/-])")
+
 
 class Audit:
     """Collects verdicts so every check reports, rather than the first failure."""
@@ -142,11 +280,23 @@ class Audit:
 
 
 def parse_frontmatter(text):
-    """YAML subset: top-level scalars, block scalars, one nested map.
-
-    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 STRICT stdlib precheck of an explicitly bounded YAML subset — NOT full
+    YAML, and it does not pretend to be (FIX-MS-02.01).
+
+    The supported subset: top-level scalars (quoted or plain), block scalars
+    (`>`/`|` and their chomping variants), inline flow sequences (`[a, b]`),
+    and ONE nested map. Everything else is out of subset and must be caught,
+    never waved through — a precheck that silently accepts what the real
+    uploader rejects is worse than no precheck.
+
+    Returns (data, line_of_key). A bare scalar that a real YAML parser would
+    COERCE keeps its type here too: `version: 1.0` becomes the float 1.0, not
+    the string "1.0", so a field the contract requires to be a string
+    (metadata values, name, description) is caught by its own type check
+    instead of passing as a stringified number. Quote it and it stays a
+    string. 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
@@ -154,8 +304,11 @@ def parse_frontmatter(text):
     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).
     """
+    parse_frontmatter.last_duplicates = []
     data, lines, key, mode = {}, {}, None, None
     scalars = set()
+    duplicates = []            # (scope, key) pairs seen more than once
+    nested_seen = set()
     for i, raw in enumerate(text.split("\n"), start=2):  # +2: the opening '---'
         if not raw.strip():
             continue
@@ -165,6 +318,9 @@ def parse_frontmatter(text):
                 key, mode = None, None
                 continue
             key, val = m.group(1), m.group(2).strip()
+            if key in data:
+                duplicates.append(("top", key))
+            nested_seen = set()
             lines[key] = i
             if val in (">", "|", ">-", "|-", ">+", "|+"):
                 data[key], mode = "", "block"
@@ -184,12 +340,38 @@ def parse_frontmatter(text):
         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())
+                if m.group(1) in nested_seen:
+                    duplicates.append((key, m.group(1)))
+                nested_seen.add(m.group(1))
+                data[key][m.group(1)] = _typed_scalar(m.group(2).strip())
     for k in scalars:
         data[k] = _finish_scalar(data[k])
+    parse_frontmatter.last_duplicates = duplicates
     return data, lines
 
 
+def _typed_scalar(v):
+    """A bare scalar keeps the TYPE a real YAML parser would give it; a quoted
+    one stays a string. This is what lets a string-required field notice that
+    `1.0` is a float and `true` is a bool (FIX-MS-02.01)."""
+    v = v.strip()
+    if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
+        return v[1:-1]                       # explicitly quoted → string
+    if v in ("true", "false", "True", "False"):
+        return v.lower() == "true"
+    if v in ("null", "~", "Null", "NULL", ""):
+        return None if v != "" else ""
+    if re.match(r"^[+-]?\d+$", v):
+        return int(v)
+    if re.match(r"^[+-]?(\d+\.\d*|\.\d+|\d+)([eE][+-]?\d+)?$", v) and \
+            re.search(r"[.eE]", v):
+        try:
+            return float(v)
+        except ValueError:
+            return v
+    return v
+
+
 def _finish_scalar(v):
     """A flow sequence is a LIST, not a string that happens to look like one.
 
@@ -236,6 +418,29 @@ def audit(skill_dir, house=False):
     fm, fm_lines = parse_frontmatter(m.group(1))
     body = text[m.end():]
 
+    dups = getattr(parse_frontmatter, "last_duplicates", [])
+    if dups:
+        named = ", ".join(k if scope == "top" else f"{scope}.{k}" for scope, k in dups)
+        a.gap("FM_DUPLICATE_KEY", "duplicate frontmatter key(s): %s — a real YAML "
+              "parser rejects or last-wins them; either way the precheck must not "
+              "pass two values for one key" % named, rel)
+    else:
+        a.ok("FM_DUPLICATE_KEY", "no duplicate frontmatter keys", rel)
+
+    yv, yd = yaml_conformance(m.group(1))
+    if yv == "DIVERGES":
+        a.gap("FM_YAML_CONFORMANCE", "the strict-subset parse diverges from the "
+              "installed YAML parser: %s — the uploader will read what the real "
+              "parser reads, not the subset" % yd, rel)
+    elif yv == "MALFORMED":
+        a.gap("FM_YAML_CONFORMANCE", "malformed frontmatter: %s" % yd, rel)
+    elif yv == "NOT_RUN":
+        a.ok("FM_YAML_CONFORMANCE", "full-YAML conformance NOT_RUN (%s) — the "
+             "strict subset precheck ran; install PyYAML to prove conformance" % yd, rel)
+    else:
+        a.ok("FM_YAML_CONFORMANCE", "the subset parse matches the installed "
+             "YAML parser", rel)
+
     _check_name(a, fm, fm_lines, name_on_disk, rel)
     _check_description(a, fm, fm_lines, rel, house)
     _check_optional_fields(a, fm, fm_lines, rel)
@@ -243,6 +448,7 @@ def audit(skill_dir, house=False):
     _check_body_budget(a, body, rel, house)
     _check_bundle(a, skill_dir, text, name_on_disk)
     _check_links(a, skill_dir, text, rel)
+    _check_distribution(a, skill_dir, name_on_disk)
     _check_prose(a, body, rel)
     return a
 
@@ -368,32 +574,53 @@ def _check_keys(a, fm, lines, rel):
 
 def _check_body_budget(a, body, rel, house=False):
     n_lines = body.count("\n") + 1
+    count_fn, tok_name = resolve_tokenizer()
     est = int(len(body) / CHARS_PER_TOKEN)
     # Both, not either: a body over the line budget still has to report its
-    # token count, or the second fix arrives only after the first one ships.
+    # token verdict, or the second fix arrives only after the first one ships.
     over = False
     if n_lines >= BODY_MAX_LINES:
         a.gap("BODY_LINES", "body is %d lines, the budget is < %d — move detail into "
               "references/" % (n_lines, BODY_MAX_LINES), rel)
         over = True
-    if est >= BODY_MAX_TOKENS:
-        a.gap("BODY_TOKENS", "body is ~%d tokens (%d chars / %s), the budget is < %d"
-              % (est, len(body), CHARS_PER_TOKEN, BODY_MAX_TOKENS), rel)
+    if count_fn is None:
+        # No adapter, no token verdict: the budget is UNMEASURED, and the
+        # byte/char estimate is reported as an ESTIMATE — it is not tokens,
+        # it cannot PASS the budget, and it cannot fail it either (a
+        # 16k-hieroglyph body estimates ~4k and measures 16k).
+        a.ok("BODY_TOKENS_UNMEASURED",
+             "token budget UNMEASURED — no tokenizer installed; the estimate "
+             "~%d (%d chars / %s) is an estimate, NOT tokens: install tiktoken "
+             "to measure" % (est, len(body), CHARS_PER_TOKEN), rel)
+        if not over:
+            a.ok("BODY_BUDGET", "body is %d lines (budget %d); token budget "
+                 "unmeasured" % (n_lines, BODY_MAX_LINES), rel)
+        if house:
+            a.ok("BODY_HEADROOM_UNMEASURED",
+                 "the %d-token working limit needs a measurement — unmeasured, "
+                 "not passed" % BODY_TARGET_TOKENS, rel)
+        return
+    measured = count_fn(body)
+    if measured >= BODY_MAX_TOKENS:
+        a.gap("BODY_TOKENS", "body is %d tokens (%s), the budget is < %d"
+              % (measured, tok_name, BODY_MAX_TOKENS), rel)
         over = True
     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)
+        a.ok("BODY_BUDGET", "body is %d lines / %d tokens (%s; budget %d / %d)"
+             % (n_lines, measured, tok_name, 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)
+    # absorbed into a reference that should have been split instead. House
+    # thresholds ride the MEASURED count only — a house rule on an estimate is
+    # a verdict on the instrument.
+    if house and not over and measured >= BODY_TARGET_TOKENS:
+        a.gap("BODY_HEADROOM", "body is %d tokens (%s) — 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"
+              % (measured, tok_name, 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)
+        a.ok("BODY_HEADROOM", "body is %d/%d tokens (%s), inside the working limit"
+             % (measured, BODY_TARGET_TOKENS, tok_name), rel)
 
 
 def _bundle_closure(skill_dir, skill_text):
@@ -454,6 +681,56 @@ def _bundle_closure(skill_dir, skill_text):
     return seen
 
 
+def package_closure(payload_files, required, optional):
+    """Whether a PACKAGED payload resolves its references (PXS-06 / ED-01.02).
+
+    `payload_files` is the set of paths actually present in what would ship —
+    the packaged copy, not the whole checkout, because a checkout resolves a
+    ref through a neighbour the package leaves behind. A REQUIRED reference
+    missing from the payload FAILS closure; an OPTIONAL one missing is reported
+    as optional, never promoted to required (an external optional reference is
+    not the package's to carry).
+    """
+    present = set(payload_files)
+    missing_required = sorted(r for r in required if r not in present)
+    missing_optional = sorted(o for o in optional if o not in present)
+    return {"ok": not missing_required,
+            "missing_required": missing_required,
+            "optional_unavailable": missing_optional}
+
+
+def _check_distribution(a, skill_dir, dir_name):
+    """The publishable payload carries no outward symlink and no undeclared secret.
+
+    A symlink pointing outside the skill directory resolves on the author's
+    machine and dangles (or leaks) everywhere else; a file whose name reads as
+    a credential is a secret nobody declared. Neither belongs in what ships.
+    """
+    root = os.path.realpath(skill_dir)
+    found_symlink = found_secret = False
+    for base, dirs, files in os.walk(skill_dir):
+        for entry in list(dirs) + files:
+            full = os.path.join(base, entry)
+            rel = os.path.relpath(full, skill_dir)
+            if os.path.islink(full):
+                target = os.path.realpath(full)
+                if not (target == root or target.startswith(root + os.sep)):
+                    found_symlink = True
+                    a.gap("DIST_SYMLINK_ESCAPE",
+                          "%s is a symlink pointing outside the skill directory — it "
+                          "dangles or leaks when the payload ships without its target"
+                          % rel, os.path.join(dir_name, rel))
+            if os.path.isfile(full) and DIST_SECRET_RE.search(rel):
+                found_secret = True
+                a.gap("DIST_UNDECLARED_SECRET",
+                      "%s reads as a credential — a secret must not ride in a "
+                      "publishable payload; exclude it (.npmignore / files allowlist)"
+                      % rel, os.path.join(dir_name, rel))
+    if not found_symlink and not found_secret:
+        a.ok("DIST_PAYLOAD", "publishable payload carries no outward symlink or "
+             "undeclared secret", dir_name)
+
+
 def _check_bundle(a, skill_dir, skill_text, dir_name):
     """references/ scripts/ assets/: one level deep, reachable, navigable."""
     reachable = _bundle_closure(skill_dir, skill_text)