@ssheleg/make-skill 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## v0.1.0 — 2026-07-24
+
+Initial release — the `make-skill` meta-skill promoted from a personal skill into
+a full distributable plugin, built to its own canon.
+
+- **Skill** (`plugins/make-skill/skills/make-skill/SKILL.md`): the proven pipeline
+  — authoring rules, the distributable repo layout, Create / Retrofit / Promote
+  workflows, end-to-end first publish, the distribution matrix, and the gotchas
+  catalog. Reference impls: super-ux (structure) + task-pipeline (config-contract
+  + release automation).
+- **Command** `/make-skill`: routes a task to the right workflow.
+- **Distribution (5 channels):** Claude Code plugin/marketplace, vercel skills CLI
+  (`npx skills add`), npm (**`@ssheleg/make-skill`** — scoped, because npm blocks
+  the bare `make-skill` as too similar to an existing package) + `npx github:`,
+  plain `install.sh` (idempotent, `--force`), and a self-contained Cursor rule
+  (`cursor/rules/make-skill.mdc`). Plugin, command, and `bin` names stay
+  `make-skill`; only the npm package is scoped.
+- **templates/SKILL.md**: canon skeleton seeded when scaffolding a new skill.
+- **Validator** (`test/validate.py`, stdlib-only): name sync, four-way version
+  sync (marketplace / plugin.json / package.json / CHANGELOG top), command +
+  Cursor `.mdc` frontmatter, npm `bin`/`files` shape, template presence, relative
+  link resolution. CI runs it plus negative self-tests (corrupt version, missing
+  template) and a functional installer test.
+- **Toggleable release automation** (`.github/workflows/release.yml`): off unless
+  the repo `RELEASE_ENABLED` variable is set; on a `v*` tag it validates the tag ↔
+  manifest version, cuts a GitHub release from this CHANGELOG, and npx-smoke-tests
+  from a clean checkout.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssheleg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# make-skill
+
+[![npm](https://img.shields.io/npm/v/@ssheleg/make-skill)](https://www.npmjs.com/package/@ssheleg/make-skill)
+[![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, and ship agent **skills** and **Claude Code plugins** the proven
+ssheleg way — 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.
+
+## What it does
+
+`make-skill` is a meta-skill: point it at a task and it routes to the right workflow.
+
+| 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 |
+| **Promote** | a personal skill that should become installable |
+
+It encodes: the repo layout, the version-sync hard rule, the validator (with a
+negative self-test), the distribution matrix (Claude Code plugin, vercel skills
+CLI, npx, Cursor), the npm gotchas, and a release checklist.
+
+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.
+
+## Install
+
+**Plugin (recommended):**
+```
+/plugin marketplace add ssheleg/make-skill
+/plugin install make-skill@make-skill
+```
+
+**Any agent via the skills CLI (Claude Code, Cursor, Codex, 70+):**
+```
+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)
+```
+
+**Cursor:**
+```
+npx skills add ssheleg/make-skill --agent cursor --global
+```
+…or copy `cursor/rules/make-skill.mdc` into a project's `.cursor/rules/`.
+
+**Plain skill:**
+```
+git clone https://github.com/ssheleg/make-skill
+cd make-skill && ./install.sh          # idempotent; --force to overwrite
+```
+
+## Updating everywhere
+
+One channel per agent (a plugin plus a plain `~/.claude/skills` copy on the same
+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` |
+| npm | `npx @ssheleg/make-skill@latest` / `npx github:ssheleg/make-skill` |
+| Plain skill | `git pull && ./install.sh --force` |
+
+## Use
+
+Say *"make a skill"* / *"сделай скилл"* / *"приведи скилл к стандарту"*, or
+`/make-skill <what to build or retrofit>`.
+
+## Repo layout
+
+```
+.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
+bin/make-skill.js + package.json     # npx installer
+test/validate.py                     # structural validator (+ negative self-test in CI)
+.github/workflows/{validate,release}.yml
+install.sh  README.md  CHANGELOG.md  LICENSE
+docs/superpowers/{specs,plans}/
+```
+
+## По-русски
+
+**make-skill** — мета-скилл: создаёт, дотягивает до стандарта и публикует агентские
+**скиллы** и **плагины Claude Code** проверенным способом ssheleg. Кодирует канон:
+раскладку marketplace-репозитория, синхрон версий по четырём точкам, структурный
+валидатор с негативным self-test'ом в CI, матрицу дистрибуции (плагин Claude Code,
+vercel skills CLI, npx, Cursor), npm-грабли и end-to-end первый релиз.
+
+Маршрутизация по задаче: **Create (personal)** — скилл только для своих агентов;
+**Create (distributable)** — устанавливаемый другими, полный репо + публикация;
+**Retrofit** — довести существующий скилл/репо до стандарта (аудит → фиксы →
+релиз); **Promote** — превратить персональный скилл в устанавливаемый.
+
+Эталоны структуры: [super-ux](https://github.com/ssheleg/super-ux) и
+[task-pipeline](https://github.com/ssheleg/task-pipeline). Запуск — `/make-skill
+<что создать/дотянуть>` или «сделай скилл». Установка — см. раздел Install выше.
+
+## License
+
+MIT © 2026 ssheleg.

package/bin/make-skill.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/*
+ * make-skill installer CLI.
+ *
+ * Installs the make-skill skill into ~/.claude/skills/make-skill and the
+ * /make-skill slash command into ~/.claude/commands/ (same layout as install.sh).
+ * Idempotent: existing installs are skipped unless --force. Zero dependencies.
+ *
+ * For other agents (Cursor, Codex, 70+) use: npx skills add ssheleg/make-skill
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ROOT = path.resolve(__dirname, '..');
+const REPO = 'ssheleg/make-skill';
+
+function usage() {
+  console.log(`make-skill installer
+
+Usage:
+  npx @ssheleg/make-skill [--force]   install skill + /make-skill command into
+                                      ~/.claude (skip existing unless --force)
+  npx @ssheleg/make-skill --help
+
+Other install paths:
+  Claude Code plugin:  /plugin marketplace add ${REPO}
+                       /plugin install make-skill@make-skill
+  Any agent (70+):     npx skills add ${REPO}`);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function installOne(label, src, dest, isDir, force) {
+  if (fs.existsSync(dest) && !force) {
+    console.log(`skip: ${label} already installed at ${dest} (rerun with --force to overwrite)`);
+    return;
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (isDir) copyDir(src, dest);
+  else fs.copyFileSync(src, dest);
+  console.log(`Installed ${label} -> ${dest}`);
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    usage();
+    return 0;
+  }
+  const force = args.includes('--force');
+  const unknown = args.filter((a) => a !== '--force');
+  if (unknown.length) {
+    console.error(`unknown argument(s): ${unknown.join(' ')}`);
+    usage();
+    return 2;
+  }
+
+  const skillSrc = path.join(ROOT, 'plugins/make-skill/skills/make-skill');
+  const cmdSrc = path.join(ROOT, 'plugins/make-skill/commands/make-skill.md');
+  for (const [p, what] of [[skillSrc, 'skill sources'], [cmdSrc, 'command source']]) {
+    if (!fs.existsSync(p)) {
+      console.error(`error: ${what} missing at ${p} — corrupted package?`);
+      return 1;
+    }
+  }
+
+  const home = os.homedir();
+  installOne(
+    'make-skill skill  ',
+    skillSrc,
+    path.join(home, '.claude', 'skills', 'make-skill'),
+    true,
+    force
+  );
+  installOne(
+    '/make-skill command',
+    cmdSrc,
+    path.join(home, '.claude', 'commands', 'make-skill.md'),
+    false,
+    force
+  );
+  return 0;
+}
+
+process.exit(main(process.argv));

package/cursor/rules/make-skill.mdc

@@ -0,0 +1,55 @@
+---
+description: "make-skill: create, retrofit, or publish an agent skill / plugin the proven ssheleg way — marketplace repo layout, four-way version sync, validator + CI, multi-channel distribution (Claude Code plugin, skills CLI, npx, Cursor), npm gotchas. Apply when creating a new skill, upgrading one to standard, or wrapping one into a plugin."
+alwaysApply: false
+---
+
+# make-skill — ship skills the proven way (Cursor)
+
+Self-contained rule (Cursor copies this into projects — no external links).
+
+## Authoring rules (every skill)
+
+- Front-matter: `name` == directory name; `description` starts "Use when …" with
+  concrete trigger phrases in English AND Russian. A skill nobody triggers is dead
+  weight.
+- One skill = one job. Multiple concerns → multiple skills + a shared contract file.
+- Body: imperative, procedural, checklists over prose. State non-negotiables as such.
+- Commands are thin wrappers: front-matter `description` (+ `argument-hint`), body =
+  "invoke skill X in mode Y", pass `$ARGUMENTS`.
+- Never overwrite user data: seed only when absent; overwrite only behind `--force`.
+
+## Distributable repo layout
+
+```
+.claude-plugin/marketplace.json            # plugins[0].source: ./plugins/<name>
+plugins/<name>/.claude-plugin/plugin.json
+plugins/<name>/commands/*.md
+plugins/<name>/skills/<skill>/SKILL.md (+ references/*.md)
+cursor/rules/*.mdc                         # self-contained, NO relative links
+templates/*.md                             # skeletons seeded into projects
+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 (EN+RU), CHANGELOG.md, LICENSE (MIT)
+docs/superpowers/{specs,plans}/
+```
+
+## Hard rules
+
+- **Version sync:** marketplace.json, plugin.json, package.json (if npm), and the
+  top CHANGELOG entry carry the SAME semver, bumped together; the validator enforces.
+- **Validator must be able to fail:** CI runs a negative self-test (corrupt a copy →
+  expect FAIL). A validator that can't fail is decoration.
+- **One channel per agent:** don't run a plugin AND a plain `~/.claude/skills` copy
+  on the same install — the stale plain copy shadows the plugin.
+- **npm name first:** `npm view <name>` (E404 = free). **npm publish = human 2FA.**
+- **Cursor .mdc:** embed contracts inline (files get copied into foreign projects).
+- **e2e npx from a NON-repo cwd** (inside the repo it resolves the local package →
+  false "command not found").
+
+## Distribution
+
+Claude Code plugin (`claude plugin marketplace add` → `install <name>@<name>`),
+vercel skills CLI (`npx skills add <owner>/<repo>`, discovers via marketplace.json),
+npx (`npx github:<owner>/<repo>`, or the registry after publish), Cursor (global via
+`npx skills add … --agent cursor --global`, or per-project `.cursor/rules/*.mdc`).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ssheleg/make-skill",
+  "version": "0.1.0",
+  "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"
+  },
+  "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",
+    "scaffold",
+    "marketplace",
+    "validator",
+    "distribution",
+    "claude-code",
+    "cursor",
+    "npm"
+  ]
+}

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

@@ -0,0 +1,10 @@
+{
+  "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.1.0",
+  "author": { "name": "ssheleg" },
+  "homepage": "https://github.com/ssheleg/make-skill",
+  "repository": "https://github.com/ssheleg/make-skill",
+  "license": "MIT",
+  "keywords": ["skill", "plugin", "scaffold", "marketplace", "validator", "distribution", "claude-code", "cursor", "npm"]
+}

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

@@ -0,0 +1,16 @@
+---
+description: Create, retrofit, or publish an agent skill / Claude Code plugin the proven ssheleg way — marketplace layout, four-way version sync, validator + CI, multi-channel distribution.
+argument-hint: <what to build/retrofit, 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:
+
+- new skill only for this user's agents → **Create (personal)**
+- new skill others install → **Create (distributable)** → First publish end-to-end
+- existing skill/repo below the standard → **Retrofit** (audit → fix → release)
+- a personal skill that should become installable → **Promote**
+
+Task: $ARGUMENTS
+
+If `$ARGUMENTS` is empty, ask in one line what to create / retrofit / publish
+before starting.

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

@@ -0,0 +1,237 @@
+---
+name: make-skill
+description: Use when creating, upgrading, or publishing agent skills and Claude Code plugins - "ssheleg skill", "ssheleg скилл", "сделай скилл", "новый скилл", "make a skill", "заверни в плагин", "опубликуй скилл", "догони скилл до стандарта", "retrofit/upgrade a skill", "приведи скилл к стандарту". Encodes the proven ssheleg pipeline - marketplace repo layout, version sync x4, validator+CI, multi-agent distribution (Claude Code plugin, vercel skills CLI, npx, Cursor), npm gotchas, end-to-end first publish. References - github.com/ssheleg/super-ux (structure) + github.com/ssheleg/task-pipeline (config-contract + release automation).
+---
+
+# 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.
+
+## Choosing a workflow
+
+| Situation | Workflow |
+|---|---|
+| New skill, only for this user's agents | Create (personal) |
+| New skill, installable by others/other agents | Create (distributable) |
+| Existing skill or repo below this standard | Retrofit |
+| Personal skill should become installable | Promote |
+
+Announce the workflow. Distributable work is a real project: brainstorm →
+spec (`docs/superpowers/specs/`) → plan → build → validate → publish. The
+spec locks target-project file contracts (paths, formats, statuses) FIRST —
+skills and rules are written against that contract, never ad hoc.
+
+## Authoring rules (every workflow)
+
+- 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/…`).
+- 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`
+  (+ `argument-hint`), body = "invoke skill X in mode Y", pass `$ARGUMENTS`.
+- Ship a one-command entry point `/<name>`: idempotent — inspect state →
+  repair missing pieces → status report → suggest exactly ONE next action.
+  Detect mode, never ask. (Pattern: super-ux `/ux`.)
+- Never overwrite user data: seed only when absent; overwrite only behind
+  `--force`.
+
+## Create (personal)
+
+`~/.claude/skills/<name>/SKILL.md` following the authoring rules — done.
+No repo, no versioning. Loads next session. Mention Promote as the upgrade
+path if it proves useful.
+
+## Create (distributable)
+
+### Layout (copy from super-ux)
+
+```
+<repo>/
+├── .claude-plugin/marketplace.json     # root manifest, plugins[0].source: ./plugins/<name>
+├── plugins/<name>/
+│   ├── .claude-plugin/plugin.json
+│   ├── commands/*.md
+│   └── skills/<skill>/SKILL.md  +  skills/references/*.md
+├── cursor/rules/*.mdc                  # if agent-rules make sense for Cursor
+├── templates/*.md                      # skeletons the skills seed into projects
+├── 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
+├── install.sh                          # POSIX fallback
+├── README.md (EN + closing RU section), CHANGELOG.md, LICENSE (MIT)
+└── docs/superpowers/{specs,plans}/
+```
+
+**Version sync (hard rule):** marketplace.json, plugin.json, package.json,
+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.
+Plus a negative self-test (corrupt a copy → expect FAIL) — a validator that
+can't fail is decoration.
+
+### 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.
+
+1. **Preflight before code:** `npm view <name>` (E404 = free);
+   `gh auth status` (may lie — just try repo create later); `npm whoami`
+   (401 → plan the 2FA human step, keep building).
+2. Build per layout; `git init -b main`; conventional commits; set local git
+   identity if `git config user.email` empty.
+3. Validator + functional tests green BEFORE publishing.
+4. **GitHub:** `gh repo create <owner>/<name> --public --source . --push`;
+   then `gh repo edit <owner>/<name> --homepage
+   "https://www.npmjs.com/package/<name>"`.
+5. **Badges day one:**
+   `[![npm](https://img.shields.io/npm/v/<name>)](https://www.npmjs.com/package/<name>)`,
+   CI badge (`actions/workflows/validate.yml/badge.svg`), license badge.
+6. **CI:** poll `gh run list --repo <owner>/<name> --limit 1` until
+   `completed success`. Red = fix now.
+7. **npm:** `npm publish --dry-run` (eye the tarball) → `npm publish`.
+   EOTP/2FA → give the user exactly one command (`cd <repo> && npm publish`),
+   wait, then verify `npm view <name> version` + e2e
+   `npx <name>@<ver> --help` FROM A NON-REPO CWD.
+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.
+
+## Retrofit (bring an existing skill/repo up to standard)
+
+Audit first, fix second, in the same session. Verdict per item: PASS / GAP
+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.
+3. Entry-point command exists, idempotent (inspect → repair → status → one
+   next action).
+4. Layout matches the standard tree; manifests complete; version sync ×4.
+5. Validator present AND green AND able to fail (run the negative test);
+   CI workflow present, last run `success`.
+6. README: badges (npm/CI/license), install matrix documented, RU section.
+7. Distribution live-checks: `npx --yes skills add <repo> --list` finds
+   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.
+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.
+
+**Then:** report the gap table, fix everything fixable now, bump a
+minor/patch version, run the release checklist. For a PERSONAL skill,
+retrofit = items 1–3 only.
+
+## Promote (personal → distributable)
+
+Create the repo per layout, move the skill into
+`plugins/<name>/skills/<skill>/`, extract contracts to `references/`, add
+entry-point command, then run First publish end-to-end. Delete the old
+`~/.claude/skills/<skill>` copy only AFTER the plugin install is verified —
+duplicate skill listings confuse agents.
+
+## Distribution matrix
+
+1. **Claude Code plugin:** `/plugin marketplace add <owner>/<repo>` →
+   `/plugin install <name>@<name>`; non-interactive via `claude plugin …`
+   CLI — use it, don't tell the user to click.
+2. **vercel-labs skills CLI (70+ agents):** `npx skills add <owner>/<repo>`
+   — discovers skills through `.claude-plugin/marketplace.json`
+   automatically; correct manifest = free compatibility. Non-interactive
+   flags: `--agent <name>|'*'`, `--global`, `--yes`, `--all` (= `--skill '*'
+   --agent '*' -y`); update with `npx skills update <name> --global --yes`.
+   Copies land in `~/.agents/skills/<name>`. **Do NOT `--agent '*'` when the
+   skill is also a Claude Code plugin** — it re-creates a `~/.claude/skills`
+   copy that shadows the plugin (see Gotchas).
+3. **npx installer:** package.json (`bin`, `files` whitelist) + zero-dep
+   CLI; works WITHOUT registry publish via `npx github:<owner>/<repo>`;
+   registry publish only buys the short `npx <name>`.
+4. **Cursor:** two routes. **Global** — `npx skills add <owner>/<repo>
+   --agent cursor --global` lands the skill in `~/.agents/skills/<name>`
+   (the shared agents dir Cursor reads). **Per-project** —
+   `.cursor/rules/*.mdc` (front-matter `description`, `alwaysApply`, opt.
+   `globs`); NO relative links inside .mdc (copied into foreign projects —
+   embed contracts inline). Cursor has no native *global rules* dir, so global
+   = skills CLI, per-project = `.mdc`, or paste into Cursor Settings → Rules.
+
+## Gotchas (each cost a debugging round)
+
+- **npm 2FA:** publish throws EOTP; non-interactive impossible without a
+  granular automation token. Plan as the one human step; verify after.
+- **Check npm name FIRST:** `npm view <name>` → E404 means free. But E404 on
+  `view` ≠ publishable: npm's **name-similarity** policy only fires on PUT, so
+  `npm publish` can still 403 "too similar to existing package <x>" (e.g.
+  `make-skill` vs `makeskill`). Fix: a **scoped** name `@<user>/<name>` (scoped
+  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.
+- **npx inside the package's own repo** resolves to the local package →
+  false `command not found`. Always e2e-test from another cwd.
+- **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`).
+- **Interactive pickers:** raw-mode multiselect only when
+  `stdin.isTTY && stdout.isTTY`; restore `setRawMode(false)` on every exit
+  path; delegate agent-matrix pickers to `npx skills add`.
+- **ANSI escapes:** `\x1b[…` literals in source, never raw ESC bytes.
+- **Python drift:** system python3 may be 3.9 — validate.py needs
+  `from __future__ import annotations` for `str | None` annotations; CI's
+  `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.
+- **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.
+
+## Release checklist (every version)
+
+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)`.
+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;
+   `gh release create` from the CHANGELOG section (or let the release workflow
+   below do it).
+5. npm publish if applicable (human 2FA); e2e `npx <name>@<ver>` from
+   non-repo cwd.
+6. **Refresh THIS machine's global installs — always, as DoD** (per global
+   `~/.claude/CLAUDE.md`): `claude plugin marketplace update <name>` →
+   `claude plugin update <name>@<name>` → `npx skills update <name> --global
+   --yes`; remind about the Claude Code restart. Don't leave the user on a
+   stale local copy after shipping a new version.
+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).

package/templates/README.md

@@ -0,0 +1,12 @@
+# templates
+
+Skeletons make-skill seeds when scaffolding a new skill. Copy only when the target
+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 |
+
+Distributable repos also get the full tree (manifests, `bin/`, `test/validate.py`,
+workflows, `install.sh`, README/CHANGELOG/LICENSE) — copy those from a reference
+impl (`ssheleg/task-pipeline` or `ssheleg/super-ux`) per the SKILL.md layout.

package/templates/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: <skill-name>
+description: Use when <concrete triggering conditions and symptoms>. Add trigger phrases in English AND Russian. Describe WHEN to use, not what the skill does.
+---
+
+# <Skill Name>
+
+## Overview
+
+What is this? Core principle in 1–2 sentences.
+
+## When to use
+
+- Symptom / situation 1
+- Symptom / situation 2
+- When NOT to use
+
+## Core pattern / workflow
+
+Imperative, procedural steps or a before/after example. Checklists over prose.
+State non-negotiables as such.
+
+## Quick reference
+
+| Operation | How |
+|---|---|
+| … | … |
+
+## Common mistakes
+
+- What goes wrong → the fix.