@ssheleg/make-skill 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## v0.25.0 — the installer refuses the shadow it documents, loudly
+
+- **The family audit of 2026-08-29 reproduced the shadow live:** a bare
+  `npx @ssheleg/telegram-dev` created three plain copies in `~/.claude/skills/` while the
+  telegram-dev plugin was enabled. Every member's bin installer had the same hole, and every
+  member's CI tested only a fresh `HOME`, so the plugin-present case had never run anywhere.
+  This is the standards repository, so the canon lands here first and its own installer is
+  the reference implementation.
+- **This repository's own check was the fail-open class, and the new canon names it.** Both
+  installers detected the plugin by the `~/.claude/plugins/marketplaces/make-skill`
+  directory alone — which under-reports (a `directory`-sourced marketplace has no dir
+  there; plugin names differ from marketplace names) — and the refusal exited **0**, which
+  reads as success to every script above it. `distribution.md` gains "The installer must
+  refuse the shadow it documents": detect from the TARGET home's
+  `installed_plugins.json` (keys are `<name>@<marketplace>`), refuse with the remedy and a
+  non-zero exit, offer `--force` as the recorded deliberate choice, fail open on a missing
+  or corrupt JSON, and gate only the `~/.claude` write — no other agent has plugins.
+- **`bin/make-skill.js` and `install.sh` implement it:** exit `3` on refusal, the remedy
+  names the spec read from the JSON (`claude plugin update make-skill@<marketplace>`) plus
+  the family launcher, `--force` overrides, absence/corruption of the JSON installs as
+  before, and the marketplaces-dir read is kept as the fallback signal. The last line of a
+  successful install now says how the next version arrives (the v0.24.0 canon, applied to
+  this repo's own CLI).
+- **`test/installer_test.js` joins `npm test` and CI** — 11 cases against throwaway HOMEs:
+  fresh / rerun-skip / `--force` / unknown-arg, plugin-present refusal (exit code, remedy
+  text, nothing written), a differently-named marketplace in the spec, corrupt JSON failing
+  open, no false refusal on other plugins or a `make-skill-extra` prefix-collider, the
+  marketplaces-dir fallback, and the same matrix for `install.sh`. Watched failing before
+  trusted: **6 of 11 red** against the pre-fix installers (`git stash` the two, run, pop).
+  The suite follows the house residue rule — a failing case keeps its HOME, and the run
+  ends by saying what it left.
+
 ## v0.24.0 — the plugin surface as it is now, and how updates reach a machine
 
 - **Four plugin features that landed after this skill last read the docs.** Re-read

package/bin/make-skill.js

@@ -18,6 +18,44 @@ const os = require('os');
 const ROOT = path.resolve(__dirname, '..');
 const REPO = 'ssheleg/make-skill';
 
+// Exit codes are the contract: 0 installed or skipped, 1 corrupted package,
+// 2 usage error, 3 refused — the plugin channel owns this agent (--force overrides).
+const EXIT_PLUGIN_PRESENT = 3;
+
+/**
+ * The plugin spec (`<name>@<marketplace>`) installed for `name` in this home,
+ * or null.
+ *
+ * `installed_plugins.json` is the record of what is actually installed. The
+ * `plugins/marketplaces/<name>` directory — the only thing this installer read
+ * until v0.25.0 — under-reports: a marketplace added from a local `directory`
+ * source has no dir there at all, and plugin names differ from marketplace
+ * names, so a check keyed on it stays green while the shadow lands. Absence
+ * and corruption both read as "no plugin": the fresh HOME is the common case,
+ * and an installer that crashes on a parse error refuses the machines that
+ * need it most.
+ */
+function installedPluginSpec(home, name) {
+  try {
+    const raw = fs.readFileSync(
+      path.join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    const plugins =
+      parsed && typeof parsed === 'object' &&
+      parsed.plugins && typeof parsed.plugins === 'object'
+        ? parsed.plugins
+        : parsed;
+    if (!plugins || typeof plugins !== 'object') return null;
+    for (const spec of Object.keys(plugins)) {
+      if (spec === name) return `${name}@${name}`;
+      if (spec.startsWith(name + '@')) return spec;
+    }
+  } catch {
+    // missing or corrupt = no plugin — fail open on absence, never crash
+  }
+  return null;
+}
+
 function version() {
   try {
     return require(path.join(ROOT, 'package.json')).version;
@@ -35,6 +73,12 @@ Usage:
   npx @ssheleg/make-skill --version
   npx @ssheleg/make-skill --help
 
+Exit codes:
+  0 installed or skipped   2 usage error
+  1 corrupted package      3 refused: the make-skill PLUGIN is installed in
+                             this home — a plain copy would shadow it (pass
+                             --force to write it anyway)
+
 Other install paths:
   Claude Code plugin:  /plugin marketplace add ${REPO}
                        /plugin install make-skill@make-skill
@@ -123,24 +167,39 @@ function main(argv) {
 
   // 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.
+  // — the exact shadow this canon forbids. Refuse rather than create it, and
+  // refuse LOUDLY: until v0.25.0 this check keyed on the marketplaces/ dir
+  // alone and exited 0 — the fail-open class. A directory-sourced marketplace
+  // has no dir there, plugin names differ from marketplace names, and a refusal
+  // that exits 0 reads as success to every script above it. Reproduced live
+  // 2026-08-29: a bare `npx @ssheleg/telegram-dev` shipped three shadows past
+  // exactly this hole while the plugin was enabled.
+  const spec = installedPluginSpec(home, 'make-skill');
   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.'
+  const viaMarketplaceDir = !spec && fs.existsSync(marketplace);
+  if ((spec || viaMarketplaceDir) && !force) {
+    const found = spec
+      ? `installed as the Claude Code plugin ${spec}\n` +
+        '         (declared in ~/.claude/plugins/installed_plugins.json)'
+      : `registered as a Claude Code marketplace\n         (${marketplace})`;
+    console.error(
+      `refused: make-skill is already ${found}.\n` +
+      '         A plain copy in ~/.claude/skills/make-skill would shadow the plugin\n' +
+      '         and serve this frozen version forever. Update the plugin channel\n' +
+      '         instead:\n' +
+      '           claude plugin marketplace update make-skill\n' +
+      `           claude plugin update ${spec || 'make-skill@make-skill'}\n` +
+      '         Family launcher (updates every member, prunes shadow copies):\n' +
+      '           npx --yes sshlg-skills@latest update\n' +
+      '         Pass --force to write the plain copy anyway — a deliberate choice\n' +
+      '         to run two channels, where the stale one wins.'
     );
     // Offered here too. The skill IS present on this machine — as the plugin —
     // so the routing block is exactly as wanted as on the install path. Two
     // doors into one install that behave differently is how a feature comes to
     // exist for half its users.
     offerRouters();
-    return 0;
+    return EXIT_PLUGIN_PRESENT;
   }
 
   installOne(
@@ -151,6 +210,15 @@ function main(argv) {
     force
   );
   offerRouters();
+  // The last line says how the next version arrives — "Installed" is not a
+  // complete sentence. Auto-update is off on purpose: this member composes
+  // with its family, and per-marketplace autoUpdate moves each member on its
+  // own clock, into combinations nobody tested together.
+  console.log(
+    '\nUpdates: rerun `npx @ssheleg/make-skill@latest --force`, or refresh the\n' +
+    'whole family with `npx --yes sshlg-skills@latest update` (every channel,\n' +
+    'and it prunes plain copies that would shadow a plugin).'
+  );
   return 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "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",
@@ -45,6 +45,6 @@
     "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"
+    "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"
   }
 }

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.24.0",
+  "version": "0.25.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.24.0"
+  version: "0.25.0"
   homepage: https://github.com/ssheleg/make-skill
 ---
 

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

@@ -10,7 +10,8 @@ API or claude.ai instead is `references/surfaces.md`.
 - The distributable repo layout (tree, public-repo floor, version sync, gates)
 - 1. Claude Code plugin
 - 2. vercel-labs skills CLI
-- 3. npx installer — npm gotchas, installer implementation traps
+- 3. npx installer — npm gotchas; the installer must refuse the shadow it
+  documents; how updates reach the machine; implementation traps
 - First publish — the 11-step sequence
 - 4. Cursor
 - 5. Ship a FAMILY via an umbrella repo
@@ -212,6 +213,50 @@ package's own repo, `npx` resolves the local package and reports a false
 - **`npx` inside the package's own repo** resolves the local package → a false
   `command not found`. Always e2e-test from another cwd.
 
+### The installer must refuse the shadow it documents
+
+The shadow rule at the top of this file is not only about the skills CLI: **a member's
+own `npx @scope/<name>` installer is the other machine that recreates the shadow.** It
+writes `~/.claude/skills/<name>` on request, and on a machine where the same skill is
+installed as a Claude Code plugin, that write is a plain copy that outranks the plugin
+and serves the version it was copied from forever. Measured 2026-08-29: a bare
+`npx @ssheleg/telegram-dev` created three plain copies in `~/.claude/skills/` while the
+`telegram-dev` plugin was enabled — and every bin installer in the family had the same
+hole, because every member's CI tested a fresh `HOME` only, so the plugin-present case
+had never run anywhere.
+
+The canon, for every bin installer that targets `~/.claude/skills/`:
+
+- **Detect the plugin from the TARGET home before writing.** Read that home's
+  `~/.claude/plugins/installed_plugins.json` and look for a plugin whose name matches
+  the skill under ANY marketplace — the keys are `<name>@<marketplace>`, and the two
+  names differ often. A `~/.claude/plugins/marketplaces/<name>` directory also signals
+  the plugin channel, but only as the fallback read: it **under-reports** — a
+  marketplace added from a local `directory` source has no dir there at all, and a
+  differently-named marketplace never matches the skill name. A presence check keyed on
+  that directory alone stays green while the shadow lands, which is the fail-open
+  class: it looks at the wrong file and then exits 0.
+- **Refuse, and exit non-zero.** Print what was found, why the plain copy is refused,
+  and the plugin-channel remedy — `claude plugin marketplace update <name>` then
+  `claude plugin update <name>@<marketplace>` with the spec read from the JSON, or the
+  family launcher (`npx --yes sshlg-skills@latest update`) for a member that composes
+  with its family. A refusal that exits 0 reads as success to every script above it:
+  this repository's own installer shipped exactly that half-measure until v0.25.0 —
+  marketplace-dir check, a `skip:` message, exit 0.
+- **`--force` is the deliberate override**, named inside the refusal itself. Two
+  channels on one agent is a choice someone may make on purpose, and the flag is where
+  that choice gets recorded instead of happening by accident.
+- **Absence fails open; corruption never crashes.** A missing or unparsable
+  `installed_plugins.json` reads as "no plugin" — the fresh HOME is the common case,
+  and an installer that dies on a parse error refuses the machines that need it most.
+- **Only Claude Code has plugins.** The check gates the `~/.claude` write alone;
+  installs into other agents' skill directories are untouched by it.
+- **CI runs the plugin-present case, not only a fresh HOME.** A fake HOME whose
+  `installed_plugins.json` declares the plugin, asserting all three at once: the
+  non-zero exit, the remedy in the output, and that nothing was written — plus the
+  `--force` path installing and the fresh HOME still installing. Reference
+  implementation: this repository's `bin/make-skill.js` and `test/installer_test.js`.
+
 ### How updates reach the machine — decide it, then SAY it
 
 An installer that never mentions updates has still chosen an update model: **never**. The
@@ -245,7 +290,7 @@ offer the launcher and say plainly that auto-update is off **on purpose**.
 Either way the last thing the installer prints is how the next version arrives. "Installed"
 is not a complete sentence.
 
-## Installer implementation traps (read while WRITING the CLI)
+### Installer implementation traps (read while WRITING the CLI)
 
 - **Piped stdin + readline:** sequential `rl.question()` drops buffered lines.
   Use ONE persistent-listener prompter for the whole flow (super-ux
@@ -356,7 +401,8 @@ claude plugin update <name>@<name>             # full id required
    `claude plugin validate ./plugins/<name> --strict` and
    `claude plugin validate . --strict` → both exit 0.
 3. Functional tests: installer against a scratch `HOME` (fresh / rerun-skip /
-   `--force`), `node --check` on the CLI, piped-menu tests.
+   `--force` / **plugin-present refusal**, per the canon in §3), `node --check`
+   on the CLI, piped-menu tests.
 4. Conventional commit; push; confirm CI `success`; tag `v<ver>` and push the tag;
    `gh release create` from the CHANGELOG section (or let the release workflow
    below do it).