@ssheleg/make-skill 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,185 @@
 # 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.
+It found one defect that made the canon read as nonsense, one that made its first
+documented command fail, and a class of drift nothing was checking. Every fix
+here ships with the rule that stops it coming back.
+
+### Fixed — the two defects that manufacture wrong answers
+
+- **A path variable used as a noun.** `SKILL.md` said "Hooks, subagents,
+  `/commands`, `${CLAUDE_PLUGIN_ROOT}` and MCP servers exist only inside Claude
+  Code". The body is substituted at load time, so what an agent actually read was
+  "Hooks, subagents, `/commands`, `/Users/…/plugins/cache/make-skill/0.10.0` and
+  MCP servers exist only inside Claude Code" — a filesystem path presented as a
+  host capability. The body now names the capability, and the validator rejects
+  any `${CLAUDE_*}` in it.
+
+- **The first command of the audit procedure could not run.** `retrofit.md`, the
+  `/skill-audit` command and the `skill-auditor` agent all opened with
+  `python3 "${CLAUDE_PLUGIN_ROOT}/skills/make-skill/scripts/audit_skill.py"`.
+  That variable is substituted into *text* and exported to *hooks*, but it is
+  **empty in the Bash tool** — measured on Claude Code 2.1.220, the command
+  expands to `/skills/...` and dies. The instruction immediately above it says
+  "do not reason your way through it", so the agent was left with a forbidden
+  fallback and a broken tool, and the cheap way out is a PASS nobody ran.
+
+  Fixed at the root: **`plugins/make-skill/bin/make-skill-audit`**. Claude Code
+  puts a plugin's `bin/` on the Bash tool's PATH, so the auditor is now reachable
+  by name with no variable in the command. The wrapper resolves its payload from
+  its own location (following symlinks), so it also works copied, symlinked into
+  an agents hub, or called by absolute path. `bin/` is now documented as a host
+  capability in its own right — it is the only reliable way to hand an agent a
+  runnable command.
+
+### Added — NOT-RUN, the missing verdict
+
+An audit with only PASS and GAP forces a check whose tool is absent into one of
+them, and the cheaper lie is PASS. `retrofit.md` now defines **NOT-RUN**, and the
+standing example is its own item 1: `skills-ref validate` installs from source
+only, so on most machines "NOT-RUN, with the reason" is the honest result. The
+conformance checklist says so where the demand is made.
+
+### Fixed — claims about the repo that the repo contradicted
+
+Each of these was true when written and drifted the release after:
+
+- `SKILL.md` said "13-item checklist" in its reference table and "14-item" nine
+  sections later; the file has 14.
+- `SKILL-CARD.md` — the card a reviewer reads before installing — was pinned at
+  0.9.0, claimed "ten files" of instruction surface against eleven, and "six
+  groups" of CI self-tests against eight.
+- `README.md` never listed `mcp-ship.md`, added in v0.10.0.
+- `README.md`'s "no agent turn required" one-liner used a glob one directory
+  level too shallow: `no matches found`, and at the right depth it matches every
+  cached version at once.
+- `CONTRIBUTING.md` said "npm publishing stays a human step" 24 lines above "there
+  is no manual `npm publish` step in any repo in the family", named `chars/4`
+  where the validator uses the measured 3.9, and counted four channels where the
+  canon documents five.
+- Three files claimed the hook is "30 lines"; it is 43. The claim is gone rather
+  than corrected — the number told a reader nothing.
+
+**The rule that closes the class:** counted claims are now compared to the
+artifacts they describe (checklist items, reference files, CI self-test groups),
+`SKILL-CARD.md`'s version must equal `plugin.json`'s, and every shipped
+`references/*.md` must appear in the README. A new gotcha states the principle: a
+number typed by hand is an assertion, not documentation.
+
+### Fixed — the Cursor rule contradicted the validator
+
+`cursor/rules/make-skill.mdc` prescribed a repo-root `templates/` directory,
+which `test/validate.py` rejects outright and a CI self-test asserts against. A
+Cursor user following the shipped rule built a repo this repo refuses. The rule
+now matches the canon, drops the superseded "npm publish = human 2FA", carries
+the path-variable fact and the family-pin rule — and the validator fails if a
+`.mdc` prescribes that layout again.
+
+### Fixed — the installers created the shadow the canon forbids
+
+`bin/make-skill.js` and `install.sh` wrote `~/.claude/skills/make-skill`, which
+is exactly the duplicate-shadow this canon spends three paragraphs warning about,
+with no check and no warning. Both now detect an installed plugin and refuse,
+naming the update commands instead; `--force` still overrides.
+
+### Fixed — the auditor
+
+- `PASS NAME_CHARSET … is spec-legal` was printed for `claude-invoice-helper`,
+  two lines above the GAP rejecting it. A PASS line quoted out of context is how
+  a wrong verdict acquires real command output as its evidence; it now says
+  "uses a legal charset".
+- `REF_NO_TRIGGER` did not blank quoted spans, although `_strip_quoted` exists
+  for exactly that: the canon could not quote the "see references/" it forbids
+  without tripping its own linter.
+- Link findings now carry `file:line`, the house checks (`--house`) report PASS
+  as well as GAP — "the house rules were checked" has to be provable from the
+  output the canon tells the agent to cite — and a body over the line budget also
+  reports its token count instead of hiding it behind `elif`.
+
+### Fixed — release and budget
+
+- **`release.yml` now runs both `claude plugin validate … --strict` on the tag.**
+  The validate workflow also runs there, but it is a separate workflow: a red run
+  in it could not stop a release being cut and published.
+- **The body budget has a working limit.** v0.10.0 shipped at ~4995 of 5000 — 20
+  characters from a red build, which turns every future correction into a trade
+  against an existing section. The validator now fails past **4750** (5%
+  headroom); this release moved duplicated material into the references that
+  already carried it and landed at ~4671.
+- **The family pin is a stated non-negotiable of every release.** make-skill
+  0.10.0 was on npm and installed while `sshlg-skills list` still advertised
+  0.9.1 — the exact failure `distribution.md` describes, on this repo, found by
+  this audit.
+- `XML_TAG_RE` is now compared between `test/validate.py` and the shipped
+  auditor: one rule, one pattern, or a skill passes one gate and fails the other.
+
+### Notes
+
+The evaluation suite is still **authored and never executed against a model**
+(`test/evals/RESULTS.md`). Running it needs a fresh agent session per query on
+each model in scope, which no CI job here does and no single session can honestly
+fake. It remains the largest open gap, and `SKILL-CARD.md` says so to a reviewer.
+
 ## v0.10.0 — 2026-08-06
 
 ### Added

package/README.md

@@ -35,10 +35,12 @@ make a skill that turns our incident runbooks into a triage workflow
 ```
 
 …or run just the mechanical half against any skill directory, no agent turn
-required:
+required. The plugin puts the auditor on the Bash tool's PATH, and the skills-CLI
+copy ships the script it wraps:
 
 ```bash
-python3 ~/.claude/plugins/*/make-skill/*/skills/make-skill/scripts/audit_skill.py ./my-skill --house
+make-skill-audit ./my-skill --house                                    # in Claude Code
+python3 ~/.agents/skills/make-skill/scripts/audit_skill.py ./my-skill --house   # any terminal
 ```
 
 With no argument the skill detects the situation — a `SKILL.md` or
@@ -148,6 +150,7 @@ agent opens only when the situation calls for them:
 | `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 |
 | `mcp.md` | [MCP](https://modelcontextprotocol.io) — skill vs server, primitives and methods, transports, consent and untrusted-output rules |
+| `mcp-ship.md` | shipping an MCP server — mounting it in an existing app and the double-path 404, auth middleware, the 404/307/401 bisect, `server.json` and the MCP Registry |
 | `a2a.md` | [A2A](https://a2a-protocol.org) — Agent Cards, task lifecycle, method mapping, v0.x→1.0 wire drift |
 
 Plus six skeletons in `skills/make-skill/assets/` — inside the skill directory,
@@ -175,7 +178,9 @@ npx skills add ssheleg/make-skill
 Don't target `claude-code` here if you installed the plugin above — see
 one-channel-per-agent.
 
-**npx, no clone:**
+**npx, no clone** — installs a plain copy into `~/.claude/skills/make-skill`, so
+use it only if you did **not** install the plugin above. Both installers detect
+the plugin and refuse rather than leave a copy shadowing it:
 
 ```bash
 npx github:ssheleg/make-skill     # always current with this repo
@@ -185,7 +190,7 @@ npx @ssheleg/make-skill           # npm registry (scoped: npm blocks the bare na
 **Cursor, per project:** copy [`cursor/rules/make-skill.mdc`](cursor/rules/make-skill.mdc)
 into `.cursor/rules/` — it is self-contained by design.
 
-**Plain skill:**
+**Plain skill** — same one-channel caveat as `npx` above:
 
 ```bash
 git clone https://github.com/ssheleg/make-skill
@@ -228,7 +233,8 @@ says so); `bash` for `install.sh` and the hook (Windows users: use `npx`, the
 plugin, or the skills CLI). The canon itself is plain Markdown and needs nothing.
 
 What runs on its own: one `PostToolUse` hook, which exits silently unless the
-file you just wrote is a `SKILL.md`. It is 30 lines and is described in
+file you just wrote is a `SKILL.md`. Read it at
+`plugins/make-skill/hooks/skill-md-audit.sh`; it is described in
 [SECURITY.md](SECURITY.md) and [SKILL-CARD.md](SKILL-CARD.md).
 
 ## Repo layout
@@ -242,6 +248,7 @@ plugins/make-skill/
 │   ├── references/*.md               # loaded on demand
 │   ├── scripts/audit_skill.py        # audits any skill dir, stdlib only
 │   └── assets/*.template.*           # six skeletons: skill, manifests, hooks, agent, command
+├── bin/make-skill-audit              # on Claude Code's Bash PATH — the auditor by name
 ├── hooks/                            # Claude Code only — PostToolUse SKILL.md audit
 ├── agents/skill-auditor.md           # Claude Code only
 └── commands/skill-audit.md           # Claude Code only, never named after a skill

package/SECURITY.md

@@ -24,15 +24,21 @@ is the only thing that runs without you asking:
   author skills it is a no-op you never see. When it is a `SKILL.md`, it runs
   the bundled auditor on that directory and returns the report as advice
   (`systemMessage`). It never blocks, never writes a file, never makes a network
-  call, and needs no `jq`. Thirty lines; read them before enabling the plugin.
+  call, and needs no `jq`. Read it before enabling the plugin — it is short.
 - **`skills/make-skill/scripts/audit_skill.py`** reads a skill directory and
   prints a report. Standard library only. It writes nothing and is run by you,
   the `/skill-audit` command, the subagent, or the hook above.
+- **`plugins/make-skill/bin/make-skill-audit`** is a POSIX-shell wrapper that
+  Claude Code places on the Bash tool's PATH while the plugin is enabled. It
+  resolves the auditor relative to its own location and `exec`s it; it runs only
+  when you invoke it, and it touches nothing else.
 - **`bin/make-skill.js`** (run via `npx`) and **`install.sh`** copy the skill
   directory into `~/.claude/skills/make-skill` and nothing else — no command file,
-  no other path in `$HOME` — and overwrite only with `--force`. Both are
-  zero-dependency: no network calls, no postinstall script. CI asserts the
-  absence of `~/.claude/commands/make-skill.md` on every run.
+  no other path in `$HOME` — and overwrite only with `--force`. Both refuse to
+  install at all when the Claude Code plugin is present, rather than leaving a
+  plain copy that shadows it. Both are zero-dependency: no network calls, no
+  postinstall script. CI asserts the absence of `~/.claude/commands/make-skill.md`
+  on every run.
 - **`test/validate.py`** reads repository files and exits with a status. It writes
   nothing. `test/evals/` is inert data — text a human feeds to an agent — and
   `test/evals/fixtures/untrusted-skill.md` is a deliberately malicious *sample*

package/bin/make-skill.js

@@ -88,6 +88,24 @@ function main(argv) {
   }
 
   const home = os.homedir();
+
+  // One channel per agent. A plain ~/.claude/skills/make-skill beside an
+  // installed plugin is two listings of the same skill, and the stale copy wins
+  // — the exact trap this canon documents. Refuse rather than create it.
+  const marketplace = path.join(home, '.claude', 'plugins', 'marketplaces', 'make-skill');
+  if (fs.existsSync(marketplace) && !force) {
+    console.log(
+      'skip: make-skill is already installed as a Claude Code plugin\n' +
+      `       (${marketplace}).\n` +
+      '       Installing a plain copy into ~/.claude/skills would shadow it, and the\n' +
+      '       stale copy is the one that wins. Update the plugin instead:\n' +
+      '         claude plugin marketplace update make-skill\n' +
+      '         claude plugin update make-skill@make-skill\n' +
+      '       Pass --force if you really want both.'
+    );
+    return 0;
+  }
+
   installOne(
     'make-skill skill',
     skillSrc,

package/cursor/rules/make-skill.mdc

@@ -72,9 +72,10 @@ canon below only ADDS to it.
 .claude-plugin/marketplace.json            # plugins[0].source: ./plugins/<name>
 plugins/<name>/.claude-plugin/plugin.json
 plugins/<name>/skills/<skill>/SKILL.md (+ references/, scripts/, assets/)
+plugins/<name>/skills/<skill>/assets/*.template.*   # skeletons — NEVER SKILL.md
 plugins/<name>/commands/*.md               # only under a name no skill uses
+plugins/<name>/bin/<exe>                   # on Claude Code's Bash PATH
 cursor/rules/*.mdc                         # self-contained, NO relative links
-templates/*.md                             # skeletons — NEVER name one SKILL.md
 bin/<name>.js + package.json               # zero-dep npx installer
 test/validate.py                           # stdlib-only consistency validator
 test/evals/                                # triggers.json + scenarios.json (data, run by a human)
@@ -110,13 +111,16 @@ checker, not a house opinion:
 - A pinned `version` is the update cache key — bump it or nobody ever receives
   the change. Marketplace names like `agent-skills`/`anthropic-*` are reserved
   and stop loading.
-- Bundled scripts resolve through `${CLAUDE_PLUGIN_ROOT}`, state through
-  `${CLAUDE_PLUGIN_DATA}` — both Claude-Code-only, so keep relative paths as the
-  portable contract.
+- Path variables are substituted into skill/command/agent TEXT and exported to
+  HOOK processes — but `${CLAUDE_PLUGIN_ROOT}` is **empty in the Bash tool**, so
+  a command you tell the agent to run must never be built from it (it expands to
+  `/skills/...` and dies). Put runnable scripts in the plugin's `bin/`, which
+  Claude Code adds to the Bash PATH, and call them by name; keep relative paths
+  as the portable contract. State through `${CLAUDE_PLUGIN_DATA}`.
 
 ## Host capabilities and the degradation contract
 
-Hooks, subagents, `/commands`, `${CLAUDE_PLUGIN_ROOT}` and MCP servers exist only
+Hooks, subagents, `/commands`, plugin path variables and MCP servers exist only
 inside Claude Code — which is a minority of where skills run. **Each is an
 accelerator with a WRITTEN fallback; the skill still finishes its job without
 it.** Put all three cases in the body, in the words the agent reads when it hits
@@ -148,9 +152,19 @@ through a quoted `"${CLAUDE_PLUGIN_ROOT}/…"` with a `timeout`; hook scripts ex
   with `npx skills add <repo> --list`.
 - **Validator must be able to fail:** CI runs a negative self-test (corrupt a copy →
   expect FAIL). A validator that can't fail is decoration.
+- **A number typed by hand is an assertion, not documentation.** Counts of files,
+  steps and checklist items drift the release after you write them — compute
+  them, or have the validator compare each claim to the artifact.
+- **Audit verdicts are PASS / GAP / NOT-RUN.** Without the third, a check whose
+  tool is missing gets recorded as a PASS nobody earned.
 - **One channel per agent:** don't run a plugin AND a plain `~/.claude/skills` copy
   on the same install — the stale plain copy shadows the plugin.
-- **npm name first:** `npm view <name>` (E404 = free). **npm publish = human 2FA.**
+- **npm name first:** `npm view <name>` (E404 = free — the name-similarity 403
+  only fires on publish). **A `v*` tag publishes**: arm CI publishing once and a
+  manual `npm publish` is the fallback, not the route.
+- **A release is not done until the family pin moves.** An umbrella that still
+  pins the previous version keeps advertising and installing it, with nothing in
+  either repo revealing the gap.
 - **Commands ARE skills now:** a `commands/<x>.md` beside `skills/<x>/` registers
   `/<x>` twice — the skill wins, the command is unreachable always-on cost. Check
   with `claude plugin details <name>@<marketplace>`; quote every `argument-hint`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.10.0",
-  "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way \u2014 conformance to the Agent Skills open standard AND Anthropic's platform rules (front-matter limits, disclosure budgets, per-surface runtime limits, the Skills API, evals) plus the Claude Code plugin reference (manifest schemas, component layout, claude plugin validate --strict), marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, the review checklist for third-party skills, and MCP / A2A rules for protocol-connected skills. This package is the installer CLI.",
+  "version": "0.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",
     "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.10.0",
+  "version": "0.11.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/make-skill/agents/skill-auditor.md

@@ -13,16 +13,16 @@ You audit skills. You do not fix them, and you do not offer to.
    `.claude/skills/*/`, or a single directory handed to you.
 
 2. For each one, run the bundled auditor first — it is deterministic and costs
-   no reasoning:
+   no reasoning. The make-skill plugin puts it on your PATH:
 
    ```bash
-   python3 "${CLAUDE_PLUGIN_ROOT}/skills/make-skill/scripts/audit_skill.py" <skill-dir> --house
+   make-skill-audit <skill-dir> --house
    ```
 
-   If `${CLAUDE_PLUGIN_ROOT}` is unset, find the script under the make-skill
-   directory you were loaded from. If `python3` is missing, say so once and fall
-   back to reading `references/agent-skills-spec.md` and checking by hand — a
-   missing interpreter changes how you work, not whether you report.
+   If it exits 2 for a missing `python3`, say so once and check the mechanical
+   items by hand from `references/agent-skills-spec.md`. A missing interpreter
+   changes how you work, not whether you report — and it makes those items
+   **NOT-RUN**, never PASS.
 
 3. Work the judgement half from
    `${CLAUDE_PLUGIN_ROOT}/skills/make-skill/references/retrofit.md`: one job per
@@ -41,6 +41,6 @@ One table for the caller, nothing else:
 |---|---|---|
 
 `PASS` only for a check you actually ran — a `file:line` or the command output.
-`GAP` carries what is wrong and the fix that closes it. No "looks fine". Finish
-with the single highest-value next action across everything you audited, and
-stop.
+`GAP` carries what is wrong and the fix that closes it. `NOT-RUN` names the tool
+that was missing. No "looks fine". Finish with the single highest-value next
+action across everything you audited, and stop.

package/plugins/make-skill/bin/make-skill-audit

@@ -0,0 +1,41 @@
+#!/usr/bin/env sh
+# make-skill-audit — the bundled skill auditor, reachable by name.
+#
+# Claude Code puts a plugin's bin/ on the Bash tool's PATH while the plugin is
+# enabled, so `make-skill-audit <dir> --house` works in a session. That matters
+# because ${CLAUDE_PLUGIN_ROOT} is substituted into skill/command text but is
+# NOT exported to the Bash tool's environment: a documented command written
+# around it expands to "/skills/..." and fails, and an agent that cannot run the
+# deterministic half tends to reason through it and report a PASS it never ran.
+#
+# Resolves the auditor from its own location, never from an environment
+# variable, so it also works when copied, symlinked into a hub, or invoked
+# through an absolute path.
+set -eu
+
+self="$0"
+# Follow symlinks without readlink -f, which BSD/macOS does not have.
+while [ -L "$self" ]; do
+  link="$(readlink "$self")"
+  case "$link" in
+    /*) self="$link" ;;
+    *)  self="$(dirname "$self")/$link" ;;
+  esac
+done
+here="$(cd "$(dirname "$self")" && pwd)"
+auditor="$here/../skills/make-skill/scripts/audit_skill.py"
+
+if [ ! -f "$auditor" ]; then
+  echo "make-skill-audit: auditor not found at $auditor" >&2
+  echo "Run scripts/audit_skill.py from the make-skill skill directory instead." >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "make-skill-audit: no python3 on PATH." >&2
+  echo "Record the mechanical items NOT-RUN with this reason, then work the" >&2
+  echo "checklist by hand from references/agent-skills-spec.md." >&2
+  exit 2
+fi
+
+exec python3 "$auditor" "$@"

package/plugins/make-skill/commands/skill-audit.md

@@ -7,25 +7,24 @@ Audit the skill at `$ARGUMENTS` (default: the skill directory in the current
 working directory, or every `skills/*/` under `plugins/*/` if this is a plugin
 repo).
 
-1. Run the bundled auditor — it does the mechanical half deterministically:
+1. Run the bundled auditor — it does the mechanical half deterministically. This
+   plugin puts it on your PATH:
 
    ```bash
-   python3 "${CLAUDE_PLUGIN_ROOT}/skills/make-skill/scripts/audit_skill.py" <skill-dir> --house
+   make-skill-audit <skill-dir> --house
    ```
 
-   No `${CLAUDE_PLUGIN_ROOT}` (not running as a Claude Code plugin)? The script
-   sits at `scripts/audit_skill.py` inside the skill directory you are reading
-   this from — commonly `~/.agents/skills/make-skill/` or
-   `~/.claude/skills/make-skill/`. No `python3` at all? Do the same checks by
-   hand from `references/agent-skills-spec.md`; the checklist is the same one the
-   script implements.
+   No `python3`? The wrapper says so and exits 2. Record the mechanical items as
+   **NOT-RUN with that reason** and check them by hand from the spec reference —
+   never as PASS.
 
 2. Then work the judgement half from
    `${CLAUDE_PLUGIN_ROOT}/skills/make-skill/references/retrofit.md` — one job,
    entry point, evaluations, distribution, repo meta. The script cannot answer
-   those.
+   those. Read the file; do not reconstruct it from memory.
 
-3. Report one gap table: `PASS` / `GAP` per item, each with `file:line` or the
-   command output that proves it. End with exactly ONE suggested next action.
+3. Report one gap table: `PASS` / `GAP` / `NOT-RUN` per item, each with
+   `file:line` or the command output that proves it. End with exactly ONE
+   suggested next action.
 
 Do not fix anything until the table is reported.

package/plugins/make-skill/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "make-skill — spec check on every SKILL.md write. The hook exits 0 without output for any path that is not a SKILL.md, so installing this plugin globally changes nothing in projects that do not author skills. It never blocks: PostToolUse runs after the write, and the result is advice, not a veto.",
+  "description": "make-skill — spec check on every SKILL.md write. The hook exits 0 without output for any path that is not a SKILL.md, so installing this plugin globally changes nothing in projects that do not author skills. It applies the Agent Skills spec floor only (no --house), so it never imposes this repo's own conventions on someone else's skill. It never blocks: PostToolUse runs after the write, and the result is advice, not a veto.",
   "hooks": {
     "PostToolUse": [
       {