@ssheleg/make-skill 0.23.5 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # 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
+  2026-08-28 against Claude Code 2.1.236; the previous pass was 2026-07-30 against 2.1.212.
+  `archive` sources install a zip over HTTPS with no git and no npm (2.1.224); `command`
+  sources let a local command print the plugin directory (2.1.229) and are the one class an
+  organisation can switch off wholesale with `disableCommandPluginSources`; entry-level
+  `headersHelper` mints registry headers and **requires `strict: false`** (2.1.238); a
+  `skills` path of `"."` scans the plugin root instead of `skills/` (2.1.221). Bare-name
+  sources under `metadata.pluginRoot` are in too (2.1.239).
+- The `headersHelper` contract is written out because every clause of it is a way to fail
+  silently — ten seconds, 500 ASCII characters, stdout JSON — and because Claude Code
+  **strips every environment variable whose name contains `TOKEN`, `SECRET`, `KEY` or
+  `AUTH`** before running it. A helper that reads its credential from one of those is handed
+  nothing, and the failure surfaces as a permissions error at the registry.
+- **`distribution.md` gains "How updates reach the machine — decide it, then SAY it".** An
+  installer that never mentions updates has still chosen a model, and the model is *never*.
+  Claude Code carries a per-marketplace `autoUpdate` flag in `known_marketplaces.json` that
+  is **not in the documented settings surface**; `/plugin` writes it and third-party
+  installers write it directly. Measured on one machine 2026-08-28: of 20 marketplaces, the
+  2 installed by `vercel-labs/plugins` carry it and 18 do not, because
+  `claude plugin marketplace add` never sets it.
+- The section states the trap rather than a preference: for packs that **compose**,
+  per-marketplace auto-update moves each on its own clock and produces a combination nobody
+  tested — the same reason a family launcher refuses a per-member argument. For packs that
+  stand alone it is the better answer. Either way the installer's last line says how the
+  next version arrives, because "Installed" is not a complete sentence.
+
 ## v0.23.5 — the channel that sends the installs, on npm too
 
 - The `skills.sh` badge and the canonical `homepage` reached GitHub in the previous cycle and stopped

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

package/plugins/make-skill/skills/make-skill/references/claude-code-plugin.md

@@ -10,7 +10,10 @@ Upstream (read against these, not from memory — the schema grows every release
 - Marketplaces — <https://code.claude.com/docs/en/plugin-marketplaces>
 - Skills — <https://code.claude.com/docs/en/skills>
 
-*Read from the docs on 2026-07-30 against Claude Code 2.1.212. Re-read before
+*Read from the docs on 2026-07-30 against Claude Code 2.1.212, and again 2026-08-28
+against 2.1.236 — that pass added the `archive` and `command` sources, entry-level
+`headersHelper`, bare-name sources under `metadata.pluginRoot`, and `"skills": ["."]`,
+all of which landed between the two readings. Re-read before
 trusting a version-gated field in a new quarter.*
 
 The [Agent Skills spec](https://agentskills.io/specification) (see
@@ -128,6 +131,12 @@ marketplace-only `source`, `category`, `tags`, `strict`, `relevance`,
 | `url` | `{"source":"url","url":"https://…​.git","ref?":…,"sha?":…}` |
 | `git-subdir` | `{"source":"git-subdir","url":"…","path":"packages/x","ref?":…,"sha?":…}` — sparse clone |
 | `npm` | `{"source":"npm","package":"@scope/pkg","version?":…,"registry?":…}` — no git SHA to fall back on, so set `version` in the manifest or the entry, else it resolves to `unknown` and updates never fire |
+| `archive` **2.1.224+** | `{"source":"archive","url":"https://…/x-2.1.0.zip","sha256?":"<64 hex>"}` — a zip over HTTPS, **no git and no npm on the machine**. The digest is optional and is the only thing standing between a URL and whatever is behind it today; set it |
+| `command` **2.1.229+** | `{"source":"command","command":"my-tool plugin-path","timeout?":60,"mode?":"copy"}` — a local command prints the directory. `timeout` defaults to 60s, max 600; `mode` is `copy` (default) or `link`. An organisation can be configured to refuse this entire class with `disableCommandPluginSources`, so it is the one source that may be unavailable for reasons no error in your repo explains |
+
+**Bare-name sources, 2.1.239+.** With `metadata.pluginRoot` set on the marketplace,
+an entry may write `"source": "my-plugin"` and have it resolve under that root — the
+`./` requirement above applies only without it.
 
 `sha` beats `ref` when both are set. **Marketplace source ≠ plugin source**: the
 first says where `marketplace.json` lives (supports `ref` only), the second where
@@ -137,6 +146,23 @@ each plugin comes from (`ref` and `sha`).
 to it. `strict: false` makes the entry the entire definition — and a
 `plugin.json` that also declares components is then a load error.
 
+**`headersHelper` on an entry, 2.1.238+ — and it needs `strict: false`.** Beside
+`source`, it names a command that mints HTTP headers for a private registry, and it runs
+**only** when that one plugin is installed or updated. The marketplace-level form is
+different: declared in `extraKnownMarketplaces` on a `url` marketplace, it runs before
+every catalog fetch and archive download on that origin, and one run is reused for 60
+seconds. Both are separate from the MCP `headersHelper` documented later in this file.
+
+The command's contract, because each clause is a way to fail silently: one JSON object of
+header names to string values on stdout, exit 0, **within 10 seconds**; at most 500
+printable ASCII characters with no run of four spaces; run through `sh` (or `cmd.exe`)
+from `~/.claude`. Claude Code **strips every variable whose name contains `TOKEN`,
+`SECRET`, `KEY` or `AUTH`** from its environment — so a helper that reads its credential
+from one of those is handed nothing, and the failure looks like a permissions problem at
+the registry. It receives `CLAUDE_CODE_MARKETPLACE_URL`, `CLAUDE_CODE_MARKETPLACE_NAME`,
+`CLAUDE_CODE_PLUGIN_NAME` and `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` instead. The user has to
+accept the command before it runs at all.
+
 Version resolution order: `plugin.json` → marketplace entry → git SHA →
 `unknown`.
 
@@ -145,7 +171,7 @@ Version resolution order: `plugin.json` → marketplace entry → git SHA →
 | Component | Default location |
 |---|---|
 | manifest | `.claude-plugin/plugin.json` |
-| skills | `skills/<name>/SKILL.md` |
+| skills | `skills/<name>/SKILL.md` — and **`"skills": ["."]` is legal from 2.1.221**: it scans the plugin ROOT for `<name>/SKILL.md` instead of `skills/`, which is what a repository whose skills sit at the top level needs |
 | commands | `commands/*.md` (flat skills; prefer `skills/` for new plugins) |
 | agents | `agents/*.md` |
 | workflows | `workflows/*.js` |

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,83 @@ 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
+operator installs once, the pack drifts, and nothing tells them. Decide between three, and
+print the answer at the end of the install.
+
+**Claude Code's own switch is a per-marketplace `autoUpdate` flag** in
+`~/.claude/plugins/known_marketplaces.json`. It is real and it is **not in the documented
+settings surface** — not in the settings reference, not in the marketplace page; `/plugin`
+writes it, and third-party installers write it directly. `vercel-labs/plugins` prompts
+`Enable auto-updates? [Y/n]`, defaults to yes, and only asks when the marketplace is new,
+the target is Claude Code or Cursor, and the install did **not** go through the official
+CLI. Measured on one machine 2026-08-28: of 20 marketplaces, the 2 installed by that tool
+carry `autoUpdate: true` and the other 18 have no such key — **`claude plugin marketplace
+add` does not set it**, so a plugin installed the official way never auto-updates unless
+somebody turns it on.
+
+| Model | Who updates | Right when |
+|---|---|---|
+| **Per-marketplace `autoUpdate`** | Claude Code, in the background, each marketplace on its own clock | packs are **independent** — one can move without the others meaning anything |
+| **A launcher command** (`npx <name> update`) | the operator, in one pass, whole set | packs **compose** — they are released and tested together |
+| **Nothing** | nobody | never; this is the default you get by not choosing |
+
+**The trap, and it is the whole reason this section exists.** For a FAMILY that composes,
+per-marketplace auto-update is actively wrong: each member moves on its own schedule and
+the machine ends up in a combination the maintainers never tested together. That is the
+same reason a family launcher refuses a per-member argument. If your packs are
+independent, `autoUpdate` is the better answer and you should offer it; if they compose,
+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)
 
 - **Piped stdin + readline:** sequential `rl.question()` drops buffered lines.
@@ -323,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).