@ssheleg/make-skill 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## v0.3.1 — 2026-07-25
+
+- Gotcha: **npm reports auth failures as `404` on publish.** A `PUT … 404` for a
+  package that `npm view` resolves means an expired token, not a missing package —
+  check `npm whoami` (E401 → `npm login`) before debugging the name. Cost two
+  debugging rounds.
+
+## v0.3.0 — 2026-07-25
+
+Review pass — a live shipping defect plus canon corrections that the repo itself
+was violating.
+
+- **FIX (shipping defect): `templates/SKILL.md` was distributed as a real skill.**
+  The skills CLI discovers EVERY `SKILL.md` in a repo, so the skeleton was listed
+  and installed on every agent as a placeholder skill literally named
+  `<skill-name>` (`npx skills add ssheleg/make-skill --list` → "Found 2 skills").
+  Renamed to `templates/SKILL.template.md`; the validator now **rejects any
+  `SKILL.md` outside `plugins/*/skills/*/`** so it cannot recur.
+- **Canon: shared contracts must live INSIDE the skill dir.** The skills CLI
+  ships only the skill's own directory, so a sibling `skills/references/`
+  (linked `../references/…`) reaches Claude Code plugins but arrives broken on
+  every other agent. Layout, authoring rules and the retrofit checklist updated;
+  new gotcha documents both this and the stray-SKILL.md trap.
+- **Validator hardened** (it now enforces what the canon preaches): description
+  must start "Use when …", must carry Russian triggers, frontmatter < 1024 chars,
+  no relative links inside `.mdc`, no stray `SKILL.md`. Each rule has a negative
+  test.
+- **Docs:** README no longer suggests the skills CLI for Claude Code (it shadows
+  the plugin); release checklist quotes the validator's real output.
+
 ## v0.2.0 — 2026-07-24
 
 Correct multi-agent + cross-platform distribution guidance (learned shipping the

package/README.md

@@ -37,7 +37,7 @@ this canon.
 /plugin install make-skill@make-skill
 ```
 
-**Any agent via the skills CLI (Claude Code, Cursor, Codex, 70+):**
+**Any agent via the skills CLI (Cursor, Codex, OpenCode, 70+ — not Claude Code, use the plugin above):**
 ```
 npx skills add ssheleg/make-skill
 ```
@@ -68,7 +68,7 @@ Claude Code install shadow each other).
 | Channel | Update |
 |---|---|
 | Claude Code (plugin) | `claude plugin marketplace update make-skill` → `claude plugin update make-skill@make-skill` → restart |
-| Any agent (skills CLI) | `npx skills update make-skill --global --yes` |
+| Any agent (skills CLI) | `npx skills update make-skill --global --yes` (repeated `--agent`; never `claude-code`) |
 | npm | `npx @ssheleg/make-skill@latest` / `npx github:ssheleg/make-skill` |
 | Plain skill | `git pull && ./install.sh --force` |
 
@@ -83,7 +83,7 @@ Say *"make a skill"* / *"сделай скилл"* / *"приведи скилл
 .claude-plugin/marketplace.json
 plugins/make-skill/{.claude-plugin/plugin.json, commands/make-skill.md, skills/make-skill/SKILL.md}
 cursor/rules/make-skill.mdc          # self-contained Cursor rule
-templates/SKILL.md                   # skeleton seeded into new skills
+templates/SKILL.template.md                   # skeleton seeded into new skills
 bin/make-skill.js + package.json     # npx installer
 test/validate.py                     # structural validator (+ negative self-test in CI)
 .github/workflows/{validate,release}.yml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Create, retrofit, and ship agent skills & Claude Code plugins the proven ssheleg way — marketplace repo layout, four-way version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, end-to-end first publish. This package is the installer CLI.",
   "bin": {
     "make-skill": "bin/make-skill.js"

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

@@ -1,7 +1,7 @@
 {
   "name": "make-skill",
   "description": "Create, retrofit, and ship agent skills & Claude Code plugins the proven ssheleg way: marketplace repo layout, four-way version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, end-to-end first publish. Reference impls: super-ux (structure) + task-pipeline (config-contract + release automation).",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "author": { "name": "ssheleg" },
   "homepage": "https://github.com/ssheleg/make-skill",
   "repository": "https://github.com/ssheleg/make-skill",

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

@@ -37,8 +37,14 @@ skills and rules are written against that contract, never ad hoc.
 - Front-matter: `name` MUST equal the directory name; `description` starts
   "Use when …" and lists concrete trigger phrases — English AND Russian
   (user works in both). A skill nobody triggers is dead weight.
-- One skill = one job. Multiple concerns → multiple skills + shared contract
-  in `skills/references/<contract>.md`, linked relatively (`../references/…`).
+- One skill = one job. Multiple concerns → multiple skills + a shared contract
+  file. **Put contracts INSIDE the skill dir** (`skills/<skill>/references/…`,
+  linked `references/…`) — the skills CLI ships only the skill's OWN directory,
+  so a SIBLING `skills/references/` (linked `../references/…`) reaches Claude
+  Code plugins but arrives **broken on every other agent** (dangling links, the
+  agent can't read the contract). If several skills must share one contract,
+  either duplicate it into each skill dir (validator-checked identical) or state
+  a raw-URL fallback in the body.
 - Body: imperative, procedural, checklists over prose. Non-negotiables
   stated as such (model: super-ux "Evidence discipline").
 - Commands (`commands/*.md`) are thin wrappers: front-matter `description`
@@ -65,9 +71,9 @@ path if it proves useful.
 ├── plugins/<name>/
 │   ├── .claude-plugin/plugin.json
 │   ├── commands/*.md
-│   └── skills/<skill>/SKILL.md  +  skills/references/*.md
+│   └── skills/<skill>/SKILL.md  +  skills/<skill>/references/*.md
 ├── cursor/rules/*.mdc                  # if agent-rules make sense for Cursor
-├── templates/*.md                      # skeletons the skills seed into projects
+├── templates/*.md                      # skeletons (NEVER name one SKILL.md — see Gotchas)
 ├── bin/<name>.js + package.json        # npx installer (zero-dep Node)
 ├── test/validate.py                    # consistency validator (stdlib only)
 ├── .github/workflows/validate.yml      # validator on push+PR
@@ -80,8 +86,11 @@ path if it proves useful.
 top CHANGELOG entry — SAME semver, bumped together, validator enforces.
 
 **Validator** (adapt super-ux `test/validate.py`): manifests parse+fields;
-SKILL.md front-matter (name==dir, description); command front-matter; `.mdc`
-front-matter; templates exist; relative md links resolve; version sync.
+SKILL.md front-matter (name==dir, description starts "Use when", EN+RU
+triggers, <1024 chars); command front-matter; `.mdc` front-matter AND no
+relative links inside `.mdc`; **no stray `SKILL.md` outside
+`plugins/*/skills/*/`**; templates exist; relative md links resolve; version
+sync.
 Plus a negative self-test (corrupt a copy → expect FAIL) — a validator that
 can't fail is decoration.
 
@@ -122,8 +131,9 @@ with evidence (`file:line` or command output) — never "looks fine".
 **Audit checklist:**
 
 1. Front-matter: name==dir; description "Use when…" + EN and RU triggers.
-2. One-job check; shared contracts extracted to `references/`, linked
-   relatively; no format duplication drift between skills.
+2. One-job check; shared contracts INSIDE the skill dir
+   (`skills/<skill>/references/…`), not a sibling — verify by installing via
+   the skills CLI and checking the contract files actually arrived.
 3. Entry-point command exists, idempotent (inspect → repair → status → one
    next action).
 4. Layout matches the standard tree; manifests complete; version sync ×4.
@@ -204,6 +214,12 @@ the plugin, or the skills CLI, never `install.sh`. Keep bin paths built with
   names are exempt) + `"publishConfig": {"access": "public"}` so `npm publish`
   needs no flag; or pick a clearly dissimilar unscoped name. The `bin` command
   name is independent of the package name — keep it short even when scoped.
+- **npm masks auth failures as 404 on publish.** A `PUT … 404 Not Found` for a
+  package that demonstrably exists (`npm view <name> version` returns a version)
+  is an EXPIRED TOKEN, not a missing/renamed package — npm hides 401/403 on write
+  so it can't be used to probe ownership. Always check `npm whoami` first: E401 →
+  `npm login`, then re-publish. npm sessions expire faster than you expect; before
+  a batch publish, run `npm whoami` once rather than debugging four 404s.
 - **First scoped publish lags the read path:** right after a successful publish,
   `npm view @scope/pkg` can still E404 for ~1–2 min (write-master has it, read
   replica hasn't). A publish that 403s "cannot publish over previously published
@@ -211,6 +227,13 @@ the plugin, or the skills CLI, never `install.sh`. Keep bin paths built with
   failure.
 - **npx inside the package's own repo** resolves to the local package →
   false `command not found`. Always e2e-test from another cwd.
+- **A stray `SKILL.md` anywhere in the repo ships as a REAL skill.** The skills
+  CLI discovers every `SKILL.md` in the tree, so a skeleton at
+  `templates/SKILL.md` gets installed into every agent as a placeholder skill
+  (seen live: a skill literally named `<skill-name>`). Name skeletons
+  `SKILL.template.md` and make the validator reject any `SKILL.md` outside
+  `plugins/*/skills/*/`. Verify with `npx skills add <repo> --list` — it must
+  list ONLY your real skills.
 - **Piped stdin + readline:** sequential `rl.question()` drops buffered
   lines; use ONE persistent-listener prompter for the whole flow (super-ux
   `makePrompter`). Non-TTY fallback for every prompt (`1,3`/`all`/`q`).
@@ -236,7 +259,7 @@ the plugin, or the skills CLI, never `install.sh`. Keep bin paths built with
 
 1. Bump the four versions together (`package.json` only if npm-distributed —
    else it's a 3-way sync); CHANGELOG entry.
-2. `python3 test/validate.py` → `OK (<n> checks)`.
+2. `python3 test/validate.py` → exit 0 (`PASS: …`).
 3. Functional tests: installer against scratch dir (fresh / rerun-skip /
    `--force`), `node --check` on CLI, pipe-driven menu tests.
 4. Conventional commit; push; confirm CI `success`; tag `v<ver>` + push tag;

package/templates/README.md

@@ -5,7 +5,7 @@ is absent; never overwrite existing files.
 
 | Template | Seeds | Used by |
 |---|---|---|
-| `SKILL.md` | a new `skills/<name>/SKILL.md` with canon frontmatter + section stubs | Create / Promote |
+|  `SKILL.template.md` | a new `skills/<name>/SKILL.md` with canon frontmatter + section stubs | Create / Promote |
 
 Distributable repos also get the full tree (manifests, `bin/`, `test/validate.py`,
 workflows, `install.sh`, README/CHANGELOG/LICENSE) — copy those from a reference