@ssheleg/make-skill 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 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 +69,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,184 @@
 [![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.
+
+**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.
 
-Bundled references the skill loads on demand:
+**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
 
-One channel per agent (a plugin plus a plain `~/.claude/skills` copy on the same
-Claude Code install shadow each other).
+**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.
 
-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.
+### Requirements
+
+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
 

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.1",
   "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.1",
   "author": {
     "name": "ssheleg"
   },

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

@@ -5,18 +5,13 @@ description: Use when creating, upgrading, auditing, or publishing agent skills
 
 # 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
 
@@ -110,9 +105,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
@@ -193,7 +195,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 +286,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.

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>`;

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