@ssheleg/make-skill 0.5.1 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## 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
+contributor looks for now exist.
+
+### Added
+- `CODE_OF_CONDUCT.md`, issue forms for bugs and ideas, and a pull-request
+  template carrying this repo's actual checks (`test/validate.py`, `bash -n
+  install.sh`).
+- US spelling in the changelog.
+
+## v0.6.0 — 2026-07-28
+
+Production pass for a public repository: the README now explains the project
+before it explains its own conventions, contributors get an entry point, and the
+last inaccuracies found by reading every file end to end are gone.
+
+### Added
+- **`CONTRIBUTING.md`** — what belongs in the canon (evidence, not advice), the
+  offline one-liner that runs the entire CI suite locally, the rules the
+  validator enforces, and the standing requirement that every new validator rule
+  ships with a negative test.
+- **`SECURITY.md`** — private reporting channel, an exact statement of what the
+  installers touch (`~/.claude/skills/make-skill`, `~/.claude/commands/`, no
+  network, no postinstall, zero dependencies), and the point that a skill is text
+  an agent executes, so it deserves review before installation.
+- `--version` / `-v` on the installer CLI, asserted in CI against
+  `package.json`.
+- **Public-repo floor** in the canon and in the validator: README, CHANGELOG,
+  LICENSE, CONTRIBUTING and SECURITY are required root files once a repo is
+  public, each with a negative self-test.
+- Validator rule: every `references/*.md` must carry a `Load this when:` line.
+  A reference without a stated condition is loaded always or never — the exact
+  failure progressive disclosure exists to prevent.
+- `bugs` URL in `package.json`; `SECURITY.md` added to the published files.
+
+### Fixed
+- **The shadow-copy gotcha understated the problem.** Docs said to remove a stray
+  `~/.claude/skills/<name>` copy "if it appears". It reappears on schedule: the
+  skills CLI auto-detects Claude Code and recreates that path — usually as a
+  symlink — on every `--global` add or update, whether or not `claude-code` was
+  targeted. The prune is now documented as part of the update command itself.
+- The v0.1.0 implementation plan still described `templates/SKILL.md` and an
+  unscoped npm package; marked executed and pointed at the spec's Superseded
+  table, matching the treatment its sibling spec already had.
+- Reference files derived from moving specs (Agent Skills, MCP, A2A) now carry
+  the date they were read, so a stale claim is visible instead of implied.
+
+### Changed
+- **README rewritten for a first-time reader**: what it is in two sentences, a
+  quickstart that ends in a working command, what you actually get (standard
+  conformance, a validator that can fail, every channel, the named gotchas,
+  where a skill ends and MCP/A2A begin), an install matrix with the prune step
+  in it, and a requirements section.
+- `permissions: contents: read` on the validate workflow.
+- `package.json` keys ordered conventionally.
+
 ## v0.5.1 — 2026-07-28
 
 Full-repo consistency pass: every file read against every other, contradictions
@@ -12,7 +125,7 @@ fixed rather than annotated.
 - **The canon demanded a README section this repo deliberately doesn't have.**
   `README.md (EN + closing RU section)` in the layout and "RU section" in the
   Retrofit audit contradicted the v0.4.0 decision to ship an English-only README.
-  Canon now says English-first, with Russian where it actually changes behaviour
+  Canon now says English-first, with Russian where it actually changes behavior
   (trigger phrases) and an optional RU section for RU-facing projects.
 - **The entry-point command contradicted its own design rule.** The canon says a
   `/<name>` command must "detect mode, never ask"; `/make-skill` with no argument

package/README.md

@@ -4,133 +4,197 @@
 [![validate](https://github.com/ssheleg/make-skill/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/make-skill/actions/workflows/validate.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-Create, retrofit, audit, and ship agent **skills** and **Claude Code plugins** the
-proven ssheleg way — conformance to the [Agent Skills open standard](https://agentskills.io/specification),
-marketplace repo layout, four-way version sync, a structural validator + CI,
-multi-channel distribution, and end-to-end first publish, encoded as a skill so
-every new skill follows the same standard.
+**A skill that builds skills.** Install it and your coding agent knows how to
+create, audit, and ship [Agent Skills](https://agentskills.io/specification) and
+Claude Code plugins properly — conforming to the open standard, validated in CI,
+and installable on every agent instead of just yours.
+
+The idea for a skill takes ten minutes. The packaging eats the evening: which
+front-matter fields are legal, how long a description may be, four manifests that
+must carry one identical version, plugin ids that only work in full `name@name`
+form, an installer that quietly leaves a second copy shadowing the one you just
+fixed. `make-skill` is that evening, written down and enforced.
+
+## Quickstart
+
+```bash
+claude plugin marketplace add ssheleg/make-skill
+claude plugin install make-skill@make-skill
+```
+
+Restart Claude Code, then just ask:
+
+```
+make a skill that turns our incident runbooks into a triage workflow
+```
+
+…or point it at something that already exists:
+
+```
+/make-skill audit ./skills/my-skill against the spec
+```
+
+Inside a skill repo, `/make-skill` with no argument detects the situation and runs
+the audit rather than asking you what you meant.
 
 ## What it does
 
-`make-skill` is a meta-skill: point it at a task and it routes to the right workflow.
+Four workflows, picked automatically from what you asked for:
 
 | Workflow | When |
 |---|---|
 | **Create (personal)** | a skill only for your own agents (`~/.claude/skills/<name>/`) |
 | **Create (distributable)** | a skill others install → full marketplace repo + first publish |
-| **Retrofit** | an existing skill/repo below the standard → audit → fix → release |
+| **Retrofit** | an existing skill or repo below the standard → audit → fix → release |
 | **Promote** | a personal skill that should become installable |
 
-It encodes: conformance to the [Agent Skills open standard](https://agentskills.io/specification),
-the repo layout, the version-sync hard rule, the validator (with negative
-self-tests), the distribution matrix (Claude Code plugin, vercel skills CLI, npx,
-Cursor), the npm gotchas, and a release checklist.
+Each one ends somewhere verifiable — a validator exit code, a green CI run, a
+resolvable install — not "should work now".
+
+## What you get
+
+**Conformance to the open standard, not just a house style.** The
+[Agent Skills specification](https://agentskills.io/specification) sets hard
+limits — `name` is 1–64 chars of `a-z0-9` and single hyphens and must match its
+directory, `description` caps at 1024 characters, the body should stay under 500
+lines and 5000 tokens. Local conventions that merely *feel* right drift from those
+without anyone noticing; here they're checked.
+
+**A validator that can fail.** `test/validate.py` (Python stdlib only, no deps)
+checks spec rules, version sync across every manifest, front-matter on commands
+and Cursor rules, link integrity, and the traps below. CI runs it plus **negative
+self-tests** — deliberately broken copies that must make it exit non-zero. A
+validator nobody has seen fail is decoration.
+
+**Every distribution channel, with the flags that actually work.** Claude Code
+plugin, the [vercel `skills` CLI](https://github.com/vercel-labs/skills) (70+
+agents), `npx`, Cursor rules, and umbrella-repo families — including the
+one-channel-per-agent rule that stops them from shadowing each other.
 
-Bundled references the skill loads on demand:
+**The gotchas that each cost a debugging round**, so your first publish works
+instead of your fourth:
+
+- a stray `SKILL.md` anywhere in the repo ships as a *real* skill on every agent;
+- `npm view` returning E404 does **not** mean the name is publishable;
+- npm reports expired-token failures as `404 Not Found` on publish;
+- `npx <pkg>` inside the package's own repo resolves the local copy and lies;
+- the skills CLI recreates the Claude Code shadow copy on every `--global` update,
+  whether or not you targeted Claude Code.
+
+**Knowing where a skill ends.** A skill is instructions — it cannot hold a
+credential or open a socket. When the task needs a live system that's an **MCP**
+server; when the other side is another autonomous agent that's **A2A**. The skill
+ships references for both, including the version drift that silently breaks
+integrations.
+
+## What ships with it
+
+The skill body stays small on purpose; the detail sits in reference files the
+agent opens only when the situation calls for them:
 
 | Reference | Covers |
 |---|---|
-| `agent-skills-spec.md` | the open standard — field limits, optional front-matter, token budgets, description-trigger evals |
+| `agent-skills-spec.md` | the open standard — field limits, optional front-matter, token budgets, the description trigger-eval loop |
 | `distribution.md` | every install channel, exact CLI flags, npm publishing traps |
-| `mcp.md` | [MCP](https://modelcontextprotocol.io) — skill vs server, primitives, transports, security rules |
-| `a2a.md` | [A2A](https://a2a-protocol.org) — Agent Cards, task lifecycle, v0.x→1.0 wire drift |
+| `mcp.md` | [MCP](https://modelcontextprotocol.io) — skill vs server, primitives and methods, transports, consent and untrusted-output rules |
+| `a2a.md` | [A2A](https://a2a-protocol.org) — Agent Cards, task lifecycle, method mapping, v0.x→1.0 wire drift |
 
-Reference implementations it mirrors: [super-ux](https://github.com/ssheleg/super-ux)
-(structure) and [task-pipeline](https://github.com/ssheleg/task-pipeline)
-(config-contract + toggleable release automation). make-skill is itself built to
-this canon.
+Plus `templates/SKILL.template.md`, a spec-legal skeleton with the limits written
+into it.
 
 ## Install
 
-**Plugin (recommended):**
-```
-/plugin marketplace add ssheleg/make-skill
-/plugin install make-skill@make-skill
-```
+**Claude Code (recommended):**
 
-**Any agent via the skills CLI (Cursor, Codex, OpenCode, 70+ — not Claude Code, use the plugin above):**
+```bash
+claude plugin marketplace add ssheleg/make-skill
+claude plugin install make-skill@make-skill
 ```
+
+**Any other agent — Cursor, Codex, OpenCode, Zed, 70+ via the skills CLI:**
+
+```bash
 npx skills add ssheleg/make-skill
 ```
 
-**npm / npx (no clone):**
-```
-npx github:ssheleg/make-skill     # straight from GitHub
-npx @ssheleg/make-skill           # from the npm registry (scoped — npm blocks the bare name)
-```
+Don't target `claude-code` here if you installed the plugin above — see
+one-channel-per-agent.
 
-**Cursor:**
-```
-npx skills add ssheleg/make-skill --agent cursor --global
+**npx, no clone:**
+
+```bash
+npx github:ssheleg/make-skill     # always current with this repo
+npx @ssheleg/make-skill           # npm registry (scoped: npm blocks the bare name)
 ```
-…or copy `cursor/rules/make-skill.mdc` into a project's `.cursor/rules/`.
+
+**Cursor, per project:** copy [`cursor/rules/make-skill.mdc`](cursor/rules/make-skill.mdc)
+into `.cursor/rules/` — it is self-contained by design.
 
 **Plain skill:**
-```
+
+```bash
 git clone https://github.com/ssheleg/make-skill
 cd make-skill && ./install.sh          # idempotent; --force to overwrite
 ```
 
-## Updating everywhere
+### 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
+```
 
-One channel per agent (a plugin plus a plain `~/.claude/skills` copy on the same
-Claude Code install shadow each other).
+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.
 
 | 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` (repeated `--agent`; never `claude-code`) |
-| npm | `npx @ssheleg/make-skill@latest` / `npx github:ssheleg/make-skill` |
+| Any agent (skills CLI) | `npx skills update make-skill --global --yes && rm -f ~/.claude/skills/make-skill` |
+| npx | `npx github:ssheleg/make-skill` / `npx @ssheleg/make-skill@latest` |
 | Plain skill | `git pull && ./install.sh --force` |
 
-## Use
+The prune in row two is not optional: the skills CLI recreates the Claude Code
+copy on every global update, even when Claude Code was never named.
+
+### Requirements
 
-Say *"make a skill"*, *"retrofit this skill to the standard"*, or *"does this
-skill match the spec?"* — or invoke `/make-skill <what to build, retrofit, or
-audit>`. With no argument inside a skill repo it detects the situation and runs
-the audit rather than asking. Russian phrasings (*"сделай скилл"*, *"приведи
-скилл к стандарту"*) route the same way.
+Node ≥ 16 for the `npx` installer; Python 3 only if you run the validator;
+`bash` for `install.sh` (Windows users: use `npx`, the plugin, or the skills CLI).
+The skill itself is plain Markdown and needs nothing.
 
 ## Repo layout
 
 ```
 .claude-plugin/marketplace.json
-plugins/make-skill/{.claude-plugin/plugin.json, commands/make-skill.md,
-                    skills/make-skill/{SKILL.md, references/*.md}}
-cursor/rules/make-skill.mdc          # self-contained Cursor rule
-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)
+plugins/make-skill/
+├── .claude-plugin/plugin.json
+├── commands/make-skill.md            # the /make-skill entry point
+└── skills/make-skill/
+    ├── SKILL.md                      # the canon, < 500 lines by rule
+    └── references/*.md               # loaded on demand
+cursor/rules/make-skill.mdc           # self-contained Cursor rule
+templates/SKILL.template.md           # spec-legal skeleton
+bin/make-skill.js + package.json      # zero-dep npx installer
+test/validate.py                      # structural validator
 .github/workflows/{validate,release}.yml
-install.sh  README.md  CHANGELOG.md  LICENSE
-docs/superpowers/{specs,plans}/
+install.sh  README.md  CHANGELOG.md  CONTRIBUTING.md  SECURITY.md  LICENSE
+docs/superpowers/{specs,plans}/       # historical design records
 ```
 
-## What this gives you
-
-The moment you catch yourself re-explaining the same workflow to your agent, you
-want a skill. Then the packaging eats your evening: front-matter limits, four
-files that must carry the identical version, plugin ids that only work in full
-`name@name` form, a CLI that silently installs a second copy shadowing the one
-you just fixed.
-
-- **Turns a workflow you keep repeating into something installable** — for
-  yourself, your team, or the public.
-- **Keeps you inside the open standard** — the `name` charset, the 1024-char
-  `description` cap, the <500-line / <5000-token body budget. The validator
-  fails on each, so a skill that installs on Claude Code also installs
-  everywhere else.
-- **Ships the scaffolding that keeps it alive:** repo layout, a validator, CI
-  with negative self-tests. A skill that fails loudly beats one that quietly
-  stops firing.
-- **Knows where a skill ends and a protocol begins** — when to write an MCP
-  server instead, how to consume one safely, and what changes when the other
-  side is another agent over A2A.
-- **Covers every distribution channel** — Claude Code plugin, 70+ agents via the
-  vercel `skills` CLI, `npx`, Cursor rules — and the one-channel-per-agent rule
-  that stops them from shadowing each other.
-- **Encodes the gotchas that each cost a debugging round**, so your first
-  publish works instead of your fourth.
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for how to run the
+validator and the full CI suite locally (both work offline, no dependencies to
+install). Security reports: [SECURITY.md](SECURITY.md).
 
 ## Author
 
@@ -140,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/SECURITY.md

@@ -0,0 +1,47 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Report privately through
+[GitHub Security Advisories](https://github.com/ssheleg/make-skill/security/advisories/new),
+or by Telegram to [@sshlg](https://t.me/sshlg) if you'd rather not use GitHub.
+Please don't open a public issue for something exploitable.
+
+Expect an acknowledgement within a few days. This is a small project maintained by
+one person — there is no bounty, but you'll be credited in the release notes
+unless you'd prefer otherwise.
+
+## What this project touches
+
+`make-skill` ships Markdown plus two small installers. Knowing exactly what runs
+where is most of the threat model:
+
+- **`bin/make-skill.js`** (run via `npx`) and **`install.sh`** copy files into
+  `~/.claude/skills/make-skill` and `~/.claude/commands/`. They create and
+  overwrite only those paths, never elsewhere in `$HOME`, and overwrite only with
+  `--force`. Both are zero-dependency: no network calls, no postinstall script.
+- **`test/validate.py`** reads repository files and exits with a status. It writes
+  nothing.
+- The Claude Code plugin and the `skills` CLI channels are handled by those tools,
+  not by code in this repo.
+
+Nothing here asks for credentials, and nothing phones home. The npm package has no
+dependencies, so its supply-chain surface is npm itself.
+
+## Content is instructions for an agent
+
+A skill is text that a coding agent loads into its context and follows. Two
+consequences worth stating plainly:
+
+- **Review a skill before installing it**, from any source including this one.
+  Prose that an agent treats as instruction deserves the same scrutiny as code you
+  would run.
+- The canon in this repo deliberately tells agents to treat everything coming back
+  from an MCP server or an A2A peer as **untrusted data, never instructions**, and
+  never to auto-approve tool calls or bypass consent prompts. If you find guidance
+  here that contradicts that, it is a bug — please report it.
+
+## Supported versions
+
+The latest release on `main` is supported. Fixes go into a new version rather than
+being backported.

package/bin/make-skill.js

@@ -17,12 +17,21 @@ const os = require('os');
 const ROOT = path.resolve(__dirname, '..');
 const REPO = 'ssheleg/make-skill';
 
+function version() {
+  try {
+    return require(path.join(ROOT, 'package.json')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
 function usage() {
-  console.log(`make-skill installer
+  console.log(`make-skill installer v${version()}
 
 Usage:
   npx @ssheleg/make-skill [--force]   install skill + /make-skill command into
                                       ~/.claude (skip existing unless --force)
+  npx @ssheleg/make-skill --version
   npx @ssheleg/make-skill --help
 
 Other install paths:
@@ -59,6 +68,10 @@ function main(argv) {
     usage();
     return 0;
   }
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(version());
+    return 0;
+  }
   const force = args.includes('--force');
   const unknown = args.filter((a) => a !== '--force');
   if (unknown.length) {

package/cursor/rules/make-skill.mdc

@@ -47,6 +47,7 @@ bin/<name>.js + package.json               # zero-dep npx installer
 test/validate.py                           # stdlib-only consistency validator
 .github/workflows/validate.yml (+ release.yml, off by default)
 install.sh, README.md (English-first), CHANGELOG.md, LICENSE (MIT)
+CONTRIBUTING.md + SECURITY.md              # required once the repo is public
 docs/superpowers/{specs,plans}/
 ```
 

package/package.json

@@ -1,29 +1,7 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.5.1",
+  "version": "0.6.4",
   "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.",
-  "bin": {
-    "make-skill": "bin/make-skill.js"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "bin",
-    "plugins",
-    "cursor",
-    "templates",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "repository": "github:ssheleg/make-skill",
-  "homepage": "https://github.com/ssheleg/make-skill",
-  "license": "MIT",
-  "author": "ssheleg",
-  "engines": {
-    "node": ">=16"
-  },
   "keywords": [
     "skill",
     "plugin",
@@ -37,5 +15,31 @@
     "agent-skills",
     "mcp",
     "a2a"
-  ]
+  ],
+  "homepage": "https://github.com/ssheleg/make-skill",
+  "bugs": {
+    "url": "https://github.com/ssheleg/make-skill/issues"
+  },
+  "repository": "github:ssheleg/make-skill",
+  "license": "MIT",
+  "author": "ssheleg",
+  "bin": {
+    "make-skill": "bin/make-skill.js"
+  },
+  "files": [
+    "bin",
+    "plugins",
+    "cursor",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  }
 }

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.5.1",
+  "version": "0.6.4",
   "author": {
     "name": "ssheleg"
   },

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

@@ -1,22 +1,18 @@
 ---
 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
 
-Reference implementations (local checkouts usually at `~/DATA/<name>`):
-- **`ssheleg/super-ux`** — the canonical structure; copy it verbatim when in
-  doubt. Multi-skill suite, Cursor rules, templates seeded into projects.
-- **`ssheleg/task-pipeline`** — the reference for the newer patterns: a
-  single-skill orchestrator with a generic JSON **config-contract**
-  (`pipeline.schema.json` + a copy-and-rewrite `pipeline.example.json`),
-  four-way version sync with jsonschema conformance in the validator, and
-  **toggleable release automation**.
-
-Both work end-to-end; match whichever is closer to the skill at hand.
-**make-skill itself** (`ssheleg/make-skill`) is built to this exact canon — the
-single-skill-plus-templates shape, distributed on all channels.
+Reference implementations to copy from (local checkouts usually `~/DATA/<name>`):
+**`ssheleg/super-ux`** — canonical structure, multi-skill suite, Cursor rules,
+seeded templates. **`ssheleg/task-pipeline`** — newer patterns: single-skill
+orchestrator, generic JSON config-contract (`pipeline.schema.json` +
+`pipeline.example.json`), jsonschema conformance in the validator, toggleable
+release automation. Match whichever is closer; both work end-to-end.
+**make-skill itself** is built to this canon.
 
 ## References — load on demand
 
@@ -58,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/".
@@ -110,9 +113,16 @@ path if it proves useful.
 ├── .github/workflows/validate.yml      # validator on push+PR (+ release.yml, off by default)
 ├── install.sh                          # POSIX fallback
 ├── README.md (English-first), CHANGELOG.md, LICENSE (MIT)
+├── CONTRIBUTING.md + SECURITY.md       # public repo: how to check work, where to report
 └── docs/superpowers/{specs,plans}/
 ```
 
+**Public-repo floor** (validator-enforced): a README that says what it does
+before how to install it; `CONTRIBUTING.md` with the exact offline commands that
+verify a change; `SECURITY.md` naming a private reporting channel and what the
+installers touch — a skill is text an agent executes, so "review before
+installing" belongs in writing.
+
 README language: **English-first** — it is the public face of the repo and most
 readers aren't Russian speakers. Russian belongs in the skill's trigger phrases
 (where it changes whether the skill fires) and, optionally, in a closing RU
@@ -139,7 +149,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`
@@ -162,8 +173,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)
 
@@ -193,7 +216,8 @@ with evidence (`file:line` or command output) — never "looks fine".
    `npx --yes skills add <repo> --list` lists ONLY real skills; `npx <name>`
    works from a non-repo cwd (if npm published); `.mdc` rules have no relative
    links and valid front-matter.
-8. Repo meta: homepage → npm page; LICENSE; CHANGELOG current.
+8. Repo meta: homepage + description + topics set on the forge; LICENSE;
+   CHANGELOG current; public repos also carry CONTRIBUTING.md and SECURITY.md.
 9. Gotcha compliance (see below): `from __future__ import annotations` in
    validate.py; `\x1b` literals not raw ESC; single prompter for piped
    stdin; raw-mode only behind isTTY guards.
@@ -283,11 +307,13 @@ Non-negotiables for any such skill:
   `3.x` won't catch it, local run will.
 - **gh auth status may lie** (invalid-token report while git+ssh path
   works): attempt the operation before declaring it blocked.
-- **Duplicate-shadow: one channel per agent.** A plugin install AND a plain
-  `~/.claude/skills/<name>` copy (from `install.sh` or `npx skills add
-  --agent '*'`) on the SAME Claude Code install = two listings; the plain copy
-  can be STALE and shadow the fresh plugin. Keep exactly one channel per
-  agent; `rm -rf ~/.claude/skills/<name>` if a stray plain copy appears.
+- **Duplicate-shadow: one channel per agent — and the shadow regrows.** A plugin
+  install AND a plain `~/.claude/skills/<name>` copy on the SAME Claude Code
+  install = two listings, and the plain copy (often STALE) wins. It is not only
+  `install.sh`: `npx skills add|update … --global` auto-detects Claude Code and
+  recreates that path — usually as a symlink — **even when `claude-code` was
+  never targeted**. So the prune belongs in the update step itself:
+  `npx skills update <name> --global --yes && rm -f ~/.claude/skills/<name>`.
 - **Plugin commands need the full `<name>@<name>`:** `claude plugin update
   <name>` → "Plugin not found"; it must be `claude plugin update
   <name>@<name>`. Same for install.
@@ -312,10 +338,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/a2a.md

@@ -8,7 +8,7 @@ Spec referenced here: **A2A 1.0.0**
 (<https://a2a-protocol.org/latest/specification/>). **Verify field and method
 names against the version you target before locking a contract** — v0.x → v1.0
 renamed the wire surface (examples below), and plenty of SDKs and blog posts still
-document v0.3.
+document v0.3. *Read from the spec on 2026-07-28.*
 
 ## A2A vs MCP — not competitors
 

package/plugins/make-skill/skills/make-skill/references/agent-skills-spec.md

@@ -11,6 +11,9 @@ Upstream sources (verify before locking anything — the spec moves):
 - Best practices — <https://agentskills.io/skill-creation/best-practices>
 - Description tuning — <https://agentskills.io/skill-creation/optimizing-descriptions>
 
+*Field limits and budgets below were read from the spec on 2026-07-28. Re-read
+before trusting them in a new quarter.*
+
 The ssheleg canon in `SKILL.md` is a **superset** of this spec. It may add rules
 (RU triggers, version sync, marketplace layout); it must never violate one.
 

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

@@ -6,6 +6,20 @@ auditing an existing repo's distribution in a Retrofit.
 Hard rule across all channels: **one channel per agent.** Two installs of the same
 skill on one agent = two listings, and the stale copy shadows the fresh one.
 
+**The shadow comes back on its own.** `npx skills add|update … --global`
+auto-detects Claude Code and writes `~/.claude/skills/<name>` — often as a symlink
+into `~/.agents/skills/<name>` — *even when `claude-code` was never named as a
+target*. So the routine that refreshes the Cursor/Codex channel silently recreates
+the shadow every single run. It cannot be handled by discipline; it needs a step:
+
+```bash
+npx skills update <name> --global --yes && rm -f ~/.claude/skills/<name>
+```
+
+Put that prune inside whatever script performs the update, so the supported path
+can't leave a shadow behind. A symlink shadows exactly as a directory does — check
+with `ls -ld`, and remember `find -type f` will not see through it.
+
 ## 1. Claude Code plugin
 
 `/plugin marketplace add <owner>/<repo>` → `/plugin install <name>@<name>`;
@@ -44,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.
@@ -90,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

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

@@ -7,6 +7,7 @@ Spec revision referenced here: **2025-11-25**
 (<https://modelcontextprotocol.io/specification/latest>). Pin the revision you
 build against and re-verify method names before locking a contract — MCP versions
 by date and the negotiated `protocolVersion` string is part of the handshake.
+*Read from the spec on 2026-07-28.*
 
 ## Skill vs MCP server — pick the right one