@ssheleg/make-skill 0.23.5 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.23.5",
+  "version": "0.24.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",

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.24.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.24.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

@@ -212,7 +212,40 @@ 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.
 
-### Installer implementation traps (read while WRITING the CLI)
+### 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.
   Use ONE persistent-listener prompter for the whole flow (super-ux