@ssheleg/make-skill 0.6.6 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # Changelog
 
+## v0.7.1 — 2026-07-31
+
+Re-read the plugin reference against what the canon actually says, and against
+what Claude Code 2.1.212 actually does. Six corrections, two of them places
+where the docs and the binary disagree.
+
+### Fixed
+- **`claude plugin validate` validates the manifest, not front matter.** The
+  docs' troubleshooting table says it checks "`plugin.json`, skill/agent/command
+  frontmatter, and `hooks/hooks.json`"; a `SKILL.md` carrying an invented
+  front-matter key passes `--strict` untouched. The canon said this gate
+  "catches a class your validator cannot see" — true for manifests, misleading
+  for front matter, which is exactly where the house validator earns its place.
+- **`claude plugin update <bare-name>` does not work**, though the docs list a
+  bare name as accepted: it answers `Plugin "make-skill" not found` **and exits
+  0**, so a release script sees success and ships nothing. The reference now
+  records both the documented form and the observed one.
+- **`skills` adds to the default scan — except at a marketplace root.** When a
+  plugin entry's `source` resolves to the marketplace root, the listed
+  subdirectories replace the default `skills/` scan (and if none exist, the
+  default runs after all). The reference stated the rule without its exception.
+- **"Every component directory sits at the plugin root" was too absolute.** That
+  is the default; a manifest path field may point anywhere inside the plugin,
+  and since 2.1.140 Claude Code warns when a manifest key leaves a default
+  folder unscanned. Only `.claude-plugin/` is genuinely off-limits.
+- **`allowed-tools`: Claude Code is looser than the spec.** It accepts a
+  space- or comma-separated string or a YAML list; the open standard accepts
+  only the space-separated string. Canon, Cursor rule and the validator's own
+  error message now say which form travels and why, instead of calling a legal
+  Claude Code skill invalid.
+- **npm plugin sources** resolve to `unknown` only when no `version` is set
+  anywhere — the entry or manifest version still wins.
+
+### Changed
+- The stray-`SKILL.md` rule is scoped honestly: a plugin-root `SKILL.md` is a
+  legal single-skill plugin in Claude Code (2.1.142+). It is multi-channel
+  distribution — the skills CLI shipping every `SKILL.md` in the tree — that
+  makes the rule, and the validator says so.
+- Version pinning: omitting `version` from both manifests is legal and hands
+  updates to the git SHA. This canon pins and bumps by choice, which the gotcha
+  now states rather than implies.
+
+### Added
+- **LSP and monitor fields in `references/claude-code-plugin.md`.** Its own load
+  condition promised "adding agents / hooks / MCP / LSP / monitors", and the
+  file had a table row for each and nothing else: now the required and optional
+  LSP keys with the 2.1.205 `restartOnCrash` / `shutdownTimeout` trap and the
+  same-extension race, and the monitor entry schema with its trust,
+  `${user_config.*}` rejection and session-lifetime rules. Plus the missing
+  `themes/` row.
+
+## v0.7.0 — 2026-07-30
+
+Conformance to Anthropic's own plugin reference
+(<https://code.claude.com/docs/en/plugins-reference>), checked with Anthropic's
+own checker. The canon already matched the Agent Skills open standard; the
+Claude Code layer on top of it — manifest schemas, component layout, path
+variables, the CLI — was folk knowledge until now. Everything stays
+multi-agent: the host layer is documented as host-specific and never
+load-bearing for skills that also run on Cursor, Codex, or the skills CLI.
+
+v0.6.5 wired the upstream gate into CI and fixed the two failures it caught;
+this release is the rulebook behind it — so the next repo passes `--strict`
+before anyone runs it, not after.
+
+### Added
+- **`references/claude-code-plugin.md`** — the Anthropic layer: full
+  `plugin.json` and `marketplace.json` schemas, plugin sources, strict mode,
+  reserved marketplace names, component locations, skill front-matter host
+  extensions, plugin-agent restrictions, scoped MCP hook names,
+  `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PLUGIN_DATA}` / `${CLAUDE_SKILL_DIR}`,
+  cache and symlink behavior, skills-directory plugins, the whole
+  `claude plugin` CLI, and a conformance checklist. Dated against Claude Code
+  2.1.212.
+- `$schema` in both manifests (schemastore), so the next edit gets autocomplete
+  and inline validation.
+- The upstream gate now also covers the **retrofit audit** and the **release
+  checklist**, and CI runs it as **its own job** so an upstream CLI outage
+  cannot mask a house-validator failure.
+- Validator rules, each with a negative self-test: recognized-fields-only for
+  both manifests, `$schema` present, reserved marketplace names, `./`-relative
+  component paths that never escape the plugin root, source directory name ==
+  plugin name, and nothing but the manifest inside `.claude-plugin/`.
+- Skill front-matter now accepts the **Claude Code extension keys**
+  (`when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`,
+  `user-invocable`, `disallowed-tools`, `model`, `effort`, `context`, `agent`,
+  `background`, `hooks`, `paths`, `shell`) alongside the spec set. Previously a
+  conformant Claude Code skill failed this repo's own audit.
+- `templates/plugin.template.json` and `templates/marketplace.template.json` —
+  annotated, schema-linked skeletons for the two manifests.
+- Personal workflow: a `~/.claude/skills/<name>/` folder with
+  `.claude-plugin/plugin.json` loads as `<name>@skills-dir` with hooks, agents,
+  and MCP servers — no marketplace, no install step (`claude plugin init`).
+- Gotchas: unknown manifest fields load fine and mean nothing (only `--strict`
+  surfaces them); a pinned `version` you forget to bump freezes every user,
+  because the version is the update cache key.
+- `displayName` in both manifests, and the v0.6.6 canon on `claude plugin
+  details`, folded in from the parallel release.
+
+### Removed
+- **`plugins/make-skill/commands/make-skill.md`.** `claude plugin details`
+  reported `Skills (2) make-skill, make-skill`: a command and a skill of the
+  same name register `/make-skill` twice, the skill wins, and the command was
+  ~100 always-on tokens per session for something unreachable. Its workflow
+  detection now lives in the skill body, where it was always going to be read.
+  The validator rejects any `commands/<x>.md` that collides with `skills/<x>/`
+  and any unquoted `argument-hint`, with negative tests for both; the npx
+  installer and `install.sh` no longer write `~/.claude/commands/make-skill.md`
+  (an existing copy from an older install is harmless and can be deleted).
+
+### Changed
+- **Progressive disclosure applied to the body itself.** The four installer
+  implementation traps (piped-stdin readline, raw-mode pickers, ANSI literals,
+  Python 3.9 annotation drift) and the 11-step **First publish** sequence moved
+  out of `SKILL.md` into `references/distribution.md`, each under a stated load
+  condition: they matter only while writing the CLI or actually publishing,
+  while the body's token budget is paid by every session. `SKILL.md` ends this
+  release under both caps — 347 lines, ~5k tokens — despite everything added
+  here and in v0.6.2–v0.6.5.
+
 ## v0.6.6 — 2026-07-30
 
 ### Added

package/README.md

@@ -60,6 +60,16 @@ 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.
 
+**Plugins Anthropic's own tooling accepts.** The
+[Claude Code plugin reference](https://code.claude.com/docs/en/plugins-reference)
+is a second rulebook on top of the standard: which fields `plugin.json` and
+`marketplace.json` actually recognize, where components must sit, which paths
+survive installation. Unknown fields load silently and do nothing, so the repo is
+checked with Anthropic's own gate — `claude plugin validate <path> --strict` on
+both manifests, in CI as its own job. That check is what caught this repo's own
+`marketplace.json` shipping `homepage` and `repository` at a level where Claude
+Code ignores them.
+
 **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
@@ -95,12 +105,15 @@ 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, the description trigger-eval loop |
+| `claude-code-plugin.md` | the [Claude Code layer](https://code.claude.com/docs/en/plugins-reference) — `plugin.json` / `marketplace.json` schemas, plugin sources, component locations, host-only front-matter, path variables, cache and symlink rules, the `claude plugin` CLI |
 | `distribution.md` | every install channel, exact CLI flags, npm publishing traps |
 | `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 |
 
-Plus `templates/SKILL.template.md`, a spec-legal skeleton with the limits written
-into it.
+Plus three skeletons in `templates/`: `SKILL.template.md` with the spec limits
+written into it, and `plugin.template.json` / `marketplace.template.json`, which
+carry only fields Claude Code recognizes so a seeded repo passes
+`claude plugin validate --strict` on day one.
 
 ## Install
 
@@ -177,12 +190,11 @@ The skill itself is plain Markdown and needs nothing.
 .claude-plugin/marketplace.json
 plugins/make-skill/
 ├── .claude-plugin/plugin.json
-├── commands/make-skill.md            # the /make-skill entry point
-└── skills/make-skill/
+└── skills/make-skill/                # the skill IS /make-skill — no command file
     ├── 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
+templates/                            # SKILL.template.md + the two manifest skeletons
 bin/make-skill.js + package.json      # zero-dep npx installer
 test/validate.py                      # structural validator
 .github/workflows/{validate,release}.yml

package/bin/make-skill.js

@@ -2,8 +2,9 @@
 /*
  * 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).
+ * Installs the make-skill skill into ~/.claude/skills/make-skill, which is what
+ * provides /make-skill (same layout as install.sh). No separate command file:
+ * a command sharing a skill's name registers the same slash command twice.
  * Idempotent: existing installs are skipped unless --force. Zero dependencies.
  *
  * For other agents (Cursor, Codex, 70+) use: npx skills add ssheleg/make-skill
@@ -29,7 +30,7 @@ function usage() {
   console.log(`make-skill installer v${version()}
 
 Usage:
-  npx @ssheleg/make-skill [--force]   install skill + /make-skill command into
+  npx @ssheleg/make-skill [--force]   install the make-skill skill into
                                       ~/.claude (skip existing unless --force)
   npx @ssheleg/make-skill --version
   npx @ssheleg/make-skill --help
@@ -81,29 +82,19 @@ function main(argv) {
   }
 
   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;
-    }
+  if (!fs.existsSync(skillSrc)) {
+    console.error(`error: skill sources missing at ${skillSrc} — corrupted package?`);
+    return 1;
   }
 
   const home = os.homedir();
   installOne(
-    'make-skill skill  ',
+    '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;
 }
 

package/cursor/rules/make-skill.mdc

@@ -1,5 +1,5 @@
 ---
-description: "make-skill: create, retrofit, audit, or publish an agent skill / plugin the proven ssheleg way — the Agent Skills open standard (front-matter limits, progressive-disclosure budgets), marketplace repo layout, four-way version sync, validator + CI, multi-channel distribution (Claude Code plugin, skills CLI, npx, Cursor), npm gotchas, and the MCP / A2A rules for protocol-connected skills. Apply when creating a new skill, upgrading one to standard, checking one against the spec, or wrapping one into a plugin."
+description: "make-skill: create, retrofit, audit, or publish an agent skill / plugin the proven ssheleg way — the Agent Skills open standard (front-matter limits, progressive-disclosure budgets), the Claude Code plugin reference (manifest schemas, component layout, claude plugin validate --strict), marketplace repo layout, four-way version sync, validator + CI, multi-channel distribution (Claude Code plugin, skills CLI, npx, Cursor), npm gotchas, and the MCP / A2A rules for protocol-connected skills. Apply when creating a new skill, upgrading one to standard, checking one against the spec, or wrapping one into a plugin."
 alwaysApply: false
 ---
 
@@ -15,9 +15,14 @@ every contract inline and uses **absolute URLs only — never a relative link**
 
 - `name`: 1–64 chars, `a-z0-9` + single internal hyphens, == directory name.
 - `description`: ≤1024 chars (that cap is on the field, not the whole front-matter).
-- Only these front-matter keys exist: `name`, `description`, `license`,
+- Portable front-matter keys: `name`, `description`, `license`,
   `compatibility` (≤500), `metadata` (string→string map), `allowed-tools`
-  (space-separated string, experimental).
+  (space-separated string — Claude Code also takes a comma-list or YAML list, but
+  only the space form is portable). Claude Code additionally reads
+  `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`,
+  `user-invocable`, `disallowed-tools`, `model`, `effort`, `context`, `agent`,
+  `background`, `hooks`, `paths`, `shell` — legal, ignored elsewhere, never
+  load-bearing. Anything outside both sets is a typo.
 - Body < 500 lines and < 5000 tokens. Overflow goes to `references/` (docs),
   `scripts/` (code), `assets/` (templates) INSIDE the skill dir, one level deep,
   each with a stated load trigger ("read X when Y"). Gotchas stay in SKILL.md.
@@ -39,8 +44,8 @@ every contract inline and uses **absolute URLs only — never a relative link**
 ```
 .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/, scripts/, assets/)
+plugins/<name>/commands/*.md               # only under a name no skill uses
 cursor/rules/*.mdc                         # self-contained, NO relative links
 templates/*.md                             # skeletons — NEVER name one SKILL.md
 bin/<name>.js + package.json               # zero-dep npx installer
@@ -51,6 +56,36 @@ CONTRIBUTING.md + SECURITY.md              # required once the repo is public
 docs/superpowers/{specs,plans}/
 ```
 
+## Claude Code plugin conformance (Anthropic's own reference)
+
+<https://code.claude.com/docs/en/plugins-reference> — the gate is Anthropic's
+checker, not a house opinion:
+
+- `claude plugin validate ./plugins/<name> --strict` **and**
+  `claude plugin validate . --strict` (marketplace) must both exit 0. Unknown
+  fields are warnings that `--strict` turns into errors; wrong types always fail.
+  It runs offline, so it belongs in CI.
+- `$schema` in both manifests:
+  `https://json.schemastore.org/claude-code-plugin-manifest.json` and
+  `https://json.schemastore.org/claude-code-marketplace.json`.
+- Marketplace level takes ONLY `name`, `owner`, `plugins`, `$schema`,
+  `description`, `version`, `metadata`, `allowCrossMarketplaceDependenciesOn`,
+  `renames`. `homepage`/`repository`/`license` are plugin-entry fields; the
+  project URL goes in `owner.url`. Plugin entry needs `name` + `source`.
+- Only `plugin.json` lives in `.claude-plugin/`; `skills/`, `commands/`,
+  `agents/`, `hooks/`, `.mcp.json` sit at the plugin ROOT. Buried components
+  load as nothing and the plugin still appears to work.
+- Every component path is relative and starts `./`; nothing outside the plugin
+  root survives install (the plugin is copied into a version cache).
+  `skills` ADDS to the default scan, `commands`/`agents`/`workflows`/
+  `outputStyles` REPLACE it.
+- A pinned `version` is the update cache key — bump it or nobody ever receives
+  the change. Marketplace names like `agent-skills`/`anthropic-*` are reserved
+  and stop loading.
+- Bundled scripts resolve through `${CLAUDE_PLUGIN_ROOT}`, state through
+  `${CLAUDE_PLUGIN_DATA}` — both Claude-Code-only, so keep relative paths as the
+  portable contract.
+
 ## Hard rules
 
 - **Version sync:** marketplace.json, plugin.json, package.json (if npm), and the
@@ -64,6 +99,9 @@ docs/superpowers/{specs,plans}/
 - **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.**
+- **Commands ARE skills now:** a `commands/<x>.md` beside `skills/<x>/` registers
+  `/<x>` twice — the skill wins, the command is unreachable always-on cost. Check
+  with `claude plugin details <name>@<marketplace>`; quote every `argument-hint`.
 - **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").

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.6.6",
-  "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.",
+  "version": "0.7.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) and the Claude Code plugin reference (manifest schemas, component layout, claude plugin validate --strict), marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, and MCP / A2A rules for protocol-connected skills. This package is the installer CLI.",
   "keywords": [
     "skill",
     "plugin",

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

@@ -1,8 +1,9 @@
 {
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "make-skill",
   "displayName": "Make Skill",
-  "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way: conformance to the Agent Skills open standard, marketplace repo layout, version sync, validator + CI, multi-channel distribution (plugin, vercel skills CLI, npx, Cursor), npm gotchas, end-to-end first publish, plus MCP / A2A references for protocol-connected skills.",
-  "version": "0.6.6",
+  "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way: conformance to the Agent Skills open standard and the Claude Code plugin reference, 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.7.1",
   "author": {
     "name": "ssheleg"
   },