@ssheleg/make-skill 0.6.1 → 0.6.5

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## v0.6.5 — 2026-07-30
+
+### Added
+- **`claude plugin validate <path> --strict` is now canon** — the upstream gate,
+  wired into CI against both the plugin and the marketplace manifest. It needs
+  no auth or API key, so a runner can install `@anthropic-ai/claude-code` and run
+  it. The canon records the two failures it found across all six repos of this
+  family at once, because neither is visible to a house validator:
+  - **`argument-hint` must be quoted.** Bare `[a | b]` is a YAML flow sequence,
+    so it parses as a list — and one comma or stray character breaks the block
+    outright, at which point the command loads with empty metadata and no
+    description, silently.
+  - **`homepage` and `repository` are not top-level `marketplace.json` fields.**
+    They belong to a plugin entry. Unrecognized fields are warnings the runtime
+    tolerates, which is why they survive everything except `--strict`.
+
+### Fixed
+- This repo's own command hint and marketplace manifest, per the above.
+
+## v0.6.4 — 2026-07-30
+
+### Changed
+- **Publishing to npm is no longer taught as a permanent human step.** The canon
+  said 2FA makes non-interactive publishing impossible and to plan the manual
+  step; that is only true of an interactive publish and a classic token. Arming
+  CI publishing is now step 9 of the first publish, and the definition of done
+  gained a fifth fact: *the next tag publishes without a human*.
+- **`references/distribution.md` §3** carries both auth routes — npm trusted
+  publishing (OIDC, no credential at all: npm >= 11.5.1, Node >= 22.14,
+  `id-token: write`, the workflow filename registered on npmjs.com) and a
+  granular automation token in `NPM_TOKEN` — and says to write the workflow so
+  both work, which makes adopting OIDC later a secret deletion rather than a CI
+  edit.
+- Three properties the publish job needs, each of which is a red build if
+  missing: skip a version already on the registry (publishing over one is a hard
+  403), a `workflow_dispatch` input naming an existing tag (a dispatch runs the
+  workflow file as of the ref it is dispatched on, so an old tag can never gain
+  a new job), and polling `npm view` afterwards, because published is a claim
+  until the registry serves it.
+- The release-automation section is no longer marked *optional*, with the
+  measurement that argues it: six of this family's seven packages were behind
+  their own tags on 2026-07-30, one by three releases.
+
+## v0.6.3 — 2026-07-30
+
+### Added
+- **Declare the licence in BOTH manifests — now part of the spec floor.** An
+  SPDX id belongs in the SKILL.md front matter *and* in the `marketplace.json`
+  plugin entry (a documented field there too). A `LICENSE` file in the repo root
+  reaches neither the plugin listing nor an installed skill. This gap was found
+  across all six repos of this family on the same day, and it stayed open
+  precisely because this checklist never asked for it: both fields are optional,
+  so nothing ever errored.
+
+### Changed
+- `license: MIT` declared in this repo's own two manifests, which is where the
+  rule should have been demonstrated first.
+
+## v0.6.2 — 2026-07-30
+
+A family member's release did not end where the skill said it ended. Publishing
+to npm left the umbrella pin pointing at the previous version, so the launcher
+kept advertising — and `update` kept installing — the release before it, with
+nothing in either repo to reveal the gap.
+
+### Added
+- **First-publish step 10** (`SKILL.md`): a skill that belongs to a family is
+  not released until the umbrella's `skills.json` pin moves and the umbrella is
+  released, verified with `npx --yes sshlg-skills@latest list`.
+- **`references/distribution.md` §5** — the same rule with the incident that
+  produced it (`agent-sync` 1.3.4 on npm while `list` still said 1.3.3).
+
+### Changed
+- README — family list and the three family commands; `CONTRIBUTING.md`.
+
 ## v0.6.1 — 2026-07-28
 
 Open-source hygiene pass — the repo is public, so the files a first-time

package/README.md

@@ -139,6 +139,19 @@ cd make-skill && ./install.sh          # idempotent; --force to overwrite
 
 ### Updating
 
+**The family updates as one package** — a bundle with one member current and the rest stale is a
+combination nobody tested:
+
+```bash
+npx sshlg-skills update               # installed but behind — updates everything
+npx sshlg-skills install              # nothing installed yet
+npx --yes sshlg-skills@latest list    # what the current release of each member is
+```
+
+Restart your agent afterwards: skills and hooks load at session start.
+
+Per-channel, when you are updating this one member only:
+
 **One channel per agent.** A plugin plus a plain `~/.claude/skills` copy on the
 same Claude Code install shadow each other, and the stale one usually wins.
 
@@ -191,13 +204,19 @@ Built by ssheleg — [sshlg.me](https://sshlg.me)
 - Telegram — [@sshlg](https://t.me/sshlg)
 
 Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):
-`super-ux`, `task-pipeline`, `make-skill`, `sheleg-design`, `seo-aeo-audit`.
-One command installs all five for every agent you use:
+`super-ux`, `task-pipeline`, `agent-sync`, `make-skill`, `sheleg-design`, `seo-aeo-audit`.
+**The family installs and updates as one package**, for every agent you use — a bundle with one
+member current and the rest stale is a combination nobody tested:
 
 ```bash
-npx sshlg-skills install
+npx sshlg-skills install              # nothing installed yet — the whole family, any agent
+npx sshlg-skills update               # installed but behind — updates everything
+npx --yes sshlg-skills@latest list    # what the current release of each member is
 ```
 
+Restart your agent afterwards: skills and hooks load at session start, so the session that
+updates is not the session that gets the new ones.
+
 ## License
 
 MIT © 2026 ssheleg.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.6.1",
+  "version": "0.6.5",
   "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way — conformance to the Agent Skills open standard (front-matter limits, progressive-disclosure budgets), marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, and MCP / A2A rules for protocol-connected skills. This package is the installer CLI.",
   "keywords": [
     "skill",

package/plugins/make-skill/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "make-skill",
   "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way: conformance to the Agent Skills open standard, marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, end-to-end first publish, plus MCP / A2A references for protocol-connected skills.",
-  "version": "0.6.1",
+  "version": "0.6.5",
   "author": {
     "name": "ssheleg"
   },

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

@@ -1,6 +1,6 @@
 ---
 description: Create, retrofit, audit, or publish an agent skill / Claude Code plugin the proven ssheleg way — Agent Skills spec conformance, marketplace layout, version sync, validator + CI, multi-channel distribution, MCP / A2A rules.
-argument-hint: <what to build/retrofit/audit, or a skill path>
+argument-hint: "<what to build/retrofit/audit, or a skill path>"
 ---
 Use the `make-skill` skill for the task below. First **detect the workflow** from
 the task and any path in `$ARGUMENTS`, announce it, then follow the skill exactly:

package/plugins/make-skill/skills/make-skill/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: make-skill
 description: Use when creating, upgrading, auditing, or publishing agent skills and Claude Code plugins - "make a skill" / "сделай скилл", "new skill" / "новый скилл", "ssheleg skill" / "ssheleg скилл", "wrap it in a plugin" / "заверни в плагин", "publish a skill" / "опубликуй скилл", "retrofit a skill to the standard" / "приведи скилл к стандарту", "does this skill match the spec" / "соответствует ли скилл стандарту" - or when a skill must reach an MCP server or another agent over A2A. Encodes the Agent Skills open standard (front-matter limits, progressive-disclosure budgets) plus the proven ssheleg pipeline - marketplace layout, version sync, validator+CI, multi-agent distribution (Claude Code plugin, vercel skills CLI, npx, Cursor), npm gotchas, end-to-end first publish.
+license: MIT
 ---
 
 # make-skill — Create, Retrofit, and Ship Skills the Proven Way
@@ -53,6 +54,13 @@ is non-negotiable; this canon only adds on top** (details + checklist:
   required MCP servers, runtimes, network here), `metadata` (string→string map;
   quote versions), `allowed-tools` (space-separated string, experimental).
   Nothing else belongs in front-matter.
+- **`license` is optional but declare it anyway — in BOTH manifests.** An SPDX
+  id in the front matter AND in the `marketplace.json` plugin entry (a documented
+  field there too). A `LICENSE` file in the repo root is invisible to someone
+  reading the plugin listing or the installed skill: shipping code whose terms
+  are one repo-visit away is a gap, and it stays open because nothing errors.
+  Observed 2026-07-30 across all six repos in this family at once — every one had
+  the file, none declared it in either manifest.
 - Body **< 500 lines and < 5000 tokens**. Heavier material goes to `references/`,
   `scripts/`, `assets/` INSIDE the skill dir, one level deep, each with a stated
   load trigger ("read X when Y") — never a bare "see references/".
@@ -126,6 +134,24 @@ top CHANGELOG entry — SAME semver, bumped together, validator enforces. If
 version an agent outside Claude Code ever sees), it joins the sync as a 5th
 point.
 
+**`claude plugin validate <path> --strict` is the upstream gate — wire it into
+CI, both manifests.** Your own validator enforces house rules; this one enforces
+Claude Code's actual schema, and it catches a class your validator cannot see.
+It needs no auth and no API key, so a GitHub runner can install
+`@anthropic-ai/claude-code` and run it. Two failures it found across this whole
+family at once:
+
+- **Front matter that silently drops.** `argument-hint: [a | b]` is a YAML flow
+  sequence, not a string: it parses as a *list*, and one value containing a
+  comma or a stray character breaks the block outright — at which point the
+  command loads with **empty metadata and no description**, with nothing at
+  runtime saying so. **Always quote `argument-hint`**, single quotes when the
+  value itself contains double quotes.
+- **`homepage` and `repository` at the top level of `marketplace.json` are not
+  fields.** They are valid on a *plugin entry*; at the root Claude Code ignores
+  them. Unrecognized fields are warnings the runtime tolerates, which is exactly
+  why they survive without `--strict`.
+
 **Validator** (adapt super-ux `test/validate.py`): manifests parse+fields;
 SKILL.md front-matter — **spec rules** (name charset/length, description ≤1024,
 `compatibility` ≤500, `metadata` all-string, `allowed-tools` a string, no unknown
@@ -141,7 +167,8 @@ is the tie-breaker on the standard; the house validator owns the repo rules.
 ### First publish — end-to-end, same session
 
 Take it ALL the way: GitHub + CI green + npm published + verified installs.
-No half-done handoffs — the ONLY human step is npm 2FA.
+No half-done handoffs. The first publish needs a human for 2FA; **arming CI
+publishing is part of shipping**, so the second one does not (see step 9).
 
 1. **Preflight before code:** `npm view <name>` (E404 = free);
    `gh auth status` (may lie — just try repo create later); `npm whoami`
@@ -164,8 +191,20 @@ No half-done handoffs — the ONLY human step is npm 2FA.
 8. **Install for the user:** `claude plugin marketplace add <owner>/<name>` +
    `claude plugin install <name>@<name>`; verify
    `npx --yes skills add <owner>/<name> --list` finds the skills.
-9. Done = four verified facts: GitHub repo + CI green; npm resolvable via
-   npx; plugin installed; skills-CLI discovery works.
+9. **Arm CI publishing so this is the last manual publish.** Ship the release
+   workflow (above), then hand over exactly two commands — `gh secret set
+   NPM_TOKEN --repo <owner>/<name>` (a GRANULAR AUTOMATION token; the user
+   pastes it, never you) and `gh variable set PUBLISH_NPMJS --body true --repo
+   <owner>/<name>`. Secret first: arming the variable with no token queues a red
+   run on the next tag.
+10. Done = five verified facts: GitHub repo + CI green; npm resolvable via
+   npx; plugin installed; skills-CLI discovery works; the next tag publishes
+   without a human.
+11. **If it belongs to a family** (`sshlg-skills`): bump its `version` pin in
+   the umbrella's `skills.json`, release the umbrella, and verify with
+   `npx --yes sshlg-skills@latest list`. Until that lands the launcher
+   advertises the OLD version and `update` installs it — see
+   `references/distribution.md` §5.
 
 ## Retrofit (bring an existing skill/repo up to standard)
 
@@ -317,10 +356,18 @@ Non-negotiables for any such skill:
 7. Global `~/.claude/CLAUDE.md` — only for rules that must fire even without
    the skill installed.
 
-**Optional — toggleable release automation** (reference impl:
-`ssheleg/task-pipeline` `.github/workflows/release.yml`). A `v*`-tag workflow,
-**off by default** and armed per repo via a `RELEASE_ENABLED` repo variable
-(so forks decide for themselves), that validates the tag ↔ manifest version,
-cuts the GitHub release from the matching CHANGELOG section, and smoke-tests
-`npx github:<owner>/<repo>#<tag>` from a clean cwd. npm publish stays the human
-2FA step. Turns steps 2/4 into CI; keep step 6 manual (it touches this machine).
+**Toggleable release automation — set it up, don't leave it optional**
+(reference impl: `ssheleg/task-pipeline` `.github/workflows/release.yml`). A
+`v*`-tag workflow, **off by default** and armed per repo by two variables so a
+fork inherits nothing: `RELEASE_ENABLED` for the GitHub release,
+`PUBLISH_NPMJS` for the registry. It validates the tag ↔ manifest version, cuts
+the GitHub release from the matching CHANGELOG section, smoke-tests `npx
+github:<owner>/<repo>#<tag>` from a clean cwd, then publishes to npm with
+provenance. Auth per `references/distribution.md` §3 — OIDC or `NPM_TOKEN`,
+written so both work. Turns steps 2/4/5 into CI; keep step 6 manual (it touches
+this machine).
+
+**A release nobody has to attend is the point.** Leaving publish manual is how a
+registry ends up several versions behind its own tags with nothing anywhere
+showing the gap — measured across this family on 2026-07-30: six of seven
+packages behind, one by three releases.

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

@@ -58,8 +58,30 @@ package's own repo, `npx` resolves the local package and reports a false
 
 ### npm gotchas — each one cost a debugging round
 
-- **npm 2FA:** publish throws EOTP; non-interactive is impossible without a
-  granular automation token. Plan it as the one human step; verify after.
+- **npm 2FA:** an interactive `npm publish` throws EOTP, and a *classic* token
+  does not get past it. Two ways out, both of which remove the human step for
+  good — set one up rather than planning a manual publish forever:
+  - **Trusted publishing (OIDC) — preferred, no credential exists to leak.**
+    npm CLI ≥ 11.5.1, Node ≥ 22.14, `permissions: id-token: write`, and the
+    package configured on npmjs.com with the exact workflow *filename* as its
+    trusted publisher. No `NODE_AUTH_TOKEN` at all.
+  - **Granular automation token** in `NPM_TOKEN`, passed as `NODE_AUTH_TOKEN`.
+    Works immediately with no npmjs.com setup, at the cost of a long-lived
+    credential to rotate.
+
+  Write the workflow so both work — always grant `id-token: write` and always
+  pass `NODE_AUTH_TOKEN` from the secret. Then adopting OIDC later is deleting a
+  secret, not editing CI. `id-token: write` is also what signs `--provenance`.
+
+  Three properties the job needs, each earned the hard way:
+  - **Skip a version already on the registry.** Publishing over one is a hard
+    403, which turns every re-run into a red build.
+  - **A `workflow_dispatch` input naming an existing tag.** A dispatch runs the
+    workflow file *as of the ref it is dispatched on*, so a tag pushed before the
+    publish job existed can never gain one — the input lets the current workflow
+    run against an old tag.
+  - **Poll `npm view` after publishing.** The read replica lags the write master
+    by a minute or two; published is a claim until the registry serves it.
 - **Check the npm name FIRST, but don't trust E404:** `npm view <name>` → E404
   means free, yet npm's **name-similarity** policy only fires on PUT, so
   `npm publish` can still 403 "too similar to existing package <x>" (e.g.
@@ -104,6 +126,14 @@ above — `npx skills add` (non-Claude agents, repeated `--agent`), `claude plug
 truth; the validator keeps it in sync with `.gitmodules`. One command
 installs/updates the whole family everywhere.
 
+**The umbrella pins each member's version, so a member release is not done until the pin moves.**
+`sshlg-skills/skills.json` carries a `version` per member and `list` prints it. Publish a member
+without bumping that pin and the launcher keeps advertising — and `update` keeps installing — the
+previous release, with nothing in either repo to reveal the gap. Observed 2026-07-29: `agent-sync`
+1.3.4 was on npm and installed everywhere while `list` still said 1.3.3, so a project comparing its
+install against `list` told every agent to update to what it already had. Bump the pin, release the
+umbrella, then confirm with `npx --yes sshlg-skills@latest list`.
+
 ## Platforms
 
 The Node installer (`bin/*.js`, `os.homedir()`/`path.join`), `npx github:…`, the