@ssheleg/make-skill 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # 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

package/cursor/rules/make-skill.mdc

@@ -17,7 +17,8 @@ every contract inline and uses **absolute URLs only — never a relative link**
 - `description`: ≤1024 chars (that cap is on the field, not the whole front-matter).
 - Portable front-matter keys: `name`, `description`, `license`,
   `compatibility` (≤500), `metadata` (string→string map), `allowed-tools`
-  (space-separated string, experimental). Claude Code additionally reads
+  (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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.7.0",
+  "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",

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

@@ -3,7 +3,7 @@
   "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 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.0",
+  "version": "0.7.1",
   "author": {
     "name": "ssheleg"
   },

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

@@ -8,15 +8,15 @@ license: MIT
 
 Copy from a working repo (usually `~/DATA/<name>`): **`ssheleg/super-ux`**
 (multi-skill suite, Cursor rules, templates) or **`ssheleg/task-pipeline`**
-(single-skill orchestrator, JSON config-contract + jsonschema in the validator,
-release automation). **make-skill itself** is built to this canon.
+(single-skill orchestrator, JSON config-contract, release automation).
+**make-skill itself** is built to this canon.
 
 ## References — load on demand
 
 | Read | When |
 |---|---|
 | `references/agent-skills-spec.md` | authoring or auditing ANY `SKILL.md` — the open standard's hard limits, optional fields, budgets, description-eval loop |
-| `references/claude-code-plugin.md` | anything shipping as a **Claude Code plugin/marketplace** — `plugin.json` + `marketplace.json` schemas, component layout, path variables, `claude plugin validate` failures |
+| `references/claude-code-plugin.md` | anything shipping as a **Claude Code plugin/marketplace** — both manifest schemas, component layout, LSP/monitors, path variables, `claude plugin validate` failures |
 | `references/distribution.md` | publishing, adding a channel, or auditing distribution |
 | `references/mcp.md` | the skill calls/wraps/documents an **MCP** server, or you're choosing skill vs server |
 | `references/a2a.md` | the skill spans two autonomous agents (**A2A**): Agent Cards, task lifecycle, delegation |
@@ -42,8 +42,8 @@ detect, ask in one line what to create.
 
 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.
+target-project file contracts FIRST; skills and rules are written against that
+contract, never ad hoc.
 
 ## Authoring rules (every workflow)
 
@@ -294,12 +294,14 @@ Non-negotiables for any such skill:
   CLI discovers every one in the tree, so `templates/SKILL.md` lands in every
   agent as a placeholder (seen live: a skill named `<skill-name>`). Name
   skeletons `SKILL.template.md`, have the validator reject any `SKILL.md`
-  outside `plugins/*/skills/*/`, verify with `npx skills add <repo> --list`.
-- **Writing the npx installer or the validator?** Four more traps (piped-stdin
-  readline, raw-mode pickers, ANSI literals, python 3.9 drift) are in
+  outside the skill dirs, verify with `npx skills add <repo> --list`. (A
+  plugin-root `SKILL.md` is legal in Claude Code alone; multi-channel makes the
+  rule.)
+- **Writing the installer or validator?** Four more traps (piped-stdin readline,
+  raw-mode pickers, ANSI literals, python 3.9 drift) are in
   `references/distribution.md` → *Installer implementation traps*.
-- **gh auth status may lie** (invalid-token report while git+ssh path
-  works): attempt the operation before declaring it blocked.
+- **gh auth status may lie** (invalid-token report while git+ssh works): attempt
+  the operation before declaring it blocked.
 - **Duplicate-shadow: one channel per agent — and the shadow regrows.** A plugin
   install AND a plain `~/.claude/skills/<name>` copy = two listings, and the
   plain (usually STALE) one wins. Not just `install.sh`: `npx skills
@@ -311,7 +313,8 @@ Non-negotiables for any such skill:
   <name>@<name>`. Same for install.
 - **A pinned `version` you forget to bump freezes every user.** The version is
   the update cache key: twenty commits under `0.6.1` and `/plugin update` still
-  says "already at the latest version".
+  says "already at the latest version". (Omitting `version` from both manifests
+  is legal — then the git SHA drives updates. This canon pins and bumps.)
 
 ## Release checklist (every version)
 
@@ -321,7 +324,7 @@ Non-negotiables for any such skill:
    `claude plugin validate ./plugins/<name> --strict` and
    `claude plugin validate . --strict` → both exit 0.
 3. Functional tests: installer against a scratch dir (fresh / rerun-skip /
-   `--force`), `node --check` on the CLI, pipe-driven menu tests.
+   `--force`), `node --check` on the CLI, piped-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).

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

@@ -46,7 +46,9 @@ Notes that bite:
   block. Adding `license`/`metadata` does not eat the description budget.
 - `metadata` values are **strings** — quote versions (`version: "1.0"`), or YAML
   turns `1.0` into a float.
-- `allowed-tools` is a single space-separated **string**, not a YAML list.
+- `allowed-tools` is a single space-separated **string**, not a YAML list. Claude
+  Code additionally accepts a comma-separated string or a YAML list — write the
+  spec form anyway, since it is the only one every host reads.
 - Nothing in the spec versions a skill. If you want the version visible to agents
   that never see `plugin.json`, put it in `metadata.version` — then it joins the
   version-sync rule.

package/plugins/make-skill/skills/make-skill/references/claude-code-plugin.md

@@ -35,6 +35,12 @@ Both must exit 0. Rules that decide the outcome:
 - Wrong **types** always fail (`keywords` as a string, not an array).
 - It runs offline and needs no auth, so it belongs in CI:
   `npm i -g @anthropic-ai/claude-code && claude plugin validate … --strict`.
+- **It validates the MANIFEST, whatever the docs promise.** The troubleshooting
+  table says the command checks "`plugin.json`, skill/agent/command frontmatter,
+  and `hooks/hooks.json`"; on 2.1.212 a `SKILL.md` carrying an invented
+  front-matter key passed `--strict` untouched, and the output names only the
+  manifest it read. Keep front-matter rules in your own validator — this gate
+  does not cover them.
 
 ## `plugin.json` — `.claude-plugin/plugin.json`
 
@@ -50,7 +56,7 @@ nothing to validate. **`name` is the only required field.**
 | `version` | string | semver. **Set it and you must bump it** — CC uses the version as the cache key, so new commits under an unchanged version never reach users. Omit it entirely and the git SHA is the version (every commit ships) |
 | `description`, `author{name,email,url}`, `homepage`, `repository`, `license`, `keywords[]` | | metadata |
 | `defaultEnabled` | boolean | `false` = installs disabled until the user opts in (CC ≥ 2.1.154). The marketplace entry's copy wins over this one; an existing `enabledPlugins` entry wins over both |
-| `skills` | string\|array | extra skill dirs — **adds to** the default `skills/` scan |
+| `skills` | string\|array | extra skill dirs — **adds to** the default `skills/` scan. One exception: in a marketplace entry whose `source` resolves to the marketplace ROOT, the listed subdirectories REPLACE that scan (if none of them exist, the default scan runs after all) |
 | `commands`, `agents`, `workflows`, `outputStyles` | string\|array | **replace** the default folder. To keep it, list it: `["./commands/", "./extras/"]` |
 | `hooks`, `mcpServers`, `lspServers` | string\|array\|object | path(s) or inline config; own merge rules |
 | `experimental.themes`, `experimental.monitors` | string\|array | still moving; top level warns today, will be required under `experimental` |
@@ -106,7 +112,7 @@ marketplace-only `source`, `category`, `tags`, `strict`, `relevance`,
 | `github` | `{"source":"github","repo":"owner/repo","ref?":"main","sha?":"…"}` |
 | `url` | `{"source":"url","url":"https://…​.git","ref?":…,"sha?":…}` |
 | `git-subdir` | `{"source":"git-subdir","url":"…","path":"packages/x","ref?":…,"sha?":…}` — sparse clone |
-| `npm` | `{"source":"npm","package":"@scope/pkg","version?":…,"registry?":…}` — version resolves to `unknown`, so no update detection |
+| `npm` | `{"source":"npm","package":"@scope/pkg","version?":…,"registry?":…}` — no git SHA to fall back on, so set `version` in the manifest or the entry, else it resolves to `unknown` and updates never fire |
 
 `sha` beats `ref` when both are set. **Marketplace source ≠ plugin source**: the
 first says where `marketplace.json` lives (supports `ref` only), the second where
@@ -133,12 +139,17 @@ Version resolution order: `plugin.json` → marketplace entry → git SHA →
 | MCP | `.mcp.json` |
 | LSP | `.lsp.json` |
 | monitors | `monitors/monitors.json` |
+| themes | `themes/*.json` — `base` preset + sparse `overrides` |
 | executables | `bin/` — on the Bash tool's PATH while enabled |
 | defaults | `settings.json` (only `agent` and `subagentStatusLine` keys) |
 
-**Only `plugin.json` goes inside `.claude-plugin/`.** Every component directory
-sits at the plugin root; components buried in `.claude-plugin/` load as nothing
-and the plugin still "works", which is why this one costs an afternoon.
+**Only `plugin.json` goes inside `.claude-plugin/`.** Those are the DEFAULT
+locations, all at the plugin root — a manifest path field may point anywhere
+else inside the plugin (`"commands": ["./specialized/deploy.md"]`), and from
+2.1.140 Claude Code warns in `claude plugin list` when a manifest key leaves a
+default folder unscanned. What never works is burying components in
+`.claude-plugin/`: they load as nothing while the plugin still "works", which is
+why that one costs an afternoon.
 
 A plugin-root `CLAUDE.md` is **not** loaded as context. Ship instructions as a
 skill.
@@ -151,7 +162,11 @@ string that changes on every update.
 ## Skill frontmatter — host extensions
 
 Portable floor (`name`, `description`, `license`, `compatibility`, `metadata`,
-`allowed-tools`) is in `references/agent-skills-spec.md`. Claude Code also reads:
+`allowed-tools`) is in `references/agent-skills-spec.md`. **`allowed-tools` is
+looser here than in the spec**: Claude Code takes a space- OR comma-separated
+string OR a YAML list, the spec takes only the space-separated string. Write the
+spec form — a list works here and breaks everywhere else. Claude Code also
+reads:
 
 | Field | Effect |
 |---|---|
@@ -194,6 +209,39 @@ there.
   hook's `server` takes `plugin:<plugin>:<server>`. A matcher on the bare server
   key never fires.
 
+## LSP servers and monitors
+
+The load condition above promises both; here is the whole of each.
+
+**LSP** — `.lsp.json` at the plugin root, or `lspServers` inline. Required per
+server: `command` (binary must be on PATH — the plugin does NOT ship it) and
+`extensionToLanguage`. Optional: `args`, `transport` (`stdio` default or
+`socket`), `env`, `initializationOptions`, `settings`, `workspaceFolder`,
+`startupTimeout`, `shutdownTimeout`, `restartOnCrash` (default `true`),
+`maxRestarts`, `diagnostics` (default `true`). `restartOnCrash` and
+`shutdownTimeout` need CC ≥ 2.1.205 — before that, setting either made Claude
+Code skip the server silently, visible only under `claude --debug`. When two
+enabled servers claim the same extension, the first registered wins and the
+other never starts; an invalid server is skipped and no longer blocks a valid
+one (also 2.1.205).
+
+```json
+{ "go": { "command": "gopls", "args": ["serve"],
+          "extensionToLanguage": { ".go": "go" } } }
+```
+
+**Monitors** — `monitors/monitors.json`, or `experimental.monitors` inline (a
+path string there loads from a custom location). Array of `{name, command,
+description, when?}`; `when` is `"always"` (default) or
+`"on-skill-invoke:<skill>"`. Each runs as a background process for the session
+and every stdout line reaches Claude as a notification. Interactive CLI only,
+unsandboxed at hook trust level, skipped where the Monitor tool is unavailable,
+and never loaded from a project-scope `@skills-dir` plugin. `${CLAUDE_PLUGIN_ROOT}`,
+`${CLAUDE_PLUGIN_DATA}`, `${CLAUDE_PROJECT_DIR}` and `${ENV_VAR}` substitute;
+`${user_config.*}` is rejected outright (it would reach a shell), and monitor
+processes get no `CLAUDE_PLUGIN_OPTION_*` either — read the value from a config
+file. Disabling a plugin mid-session does not stop a running monitor.
+
 ## Path variables
 
 | Variable | Resolves to |
@@ -248,7 +296,7 @@ need `/reload-plugins`. Disable with `claude plugin disable <name>@skills-dir`.
 | `claude plugin validate <path> [--strict]` | the conformance gate, offline |
 | `claude plugin init <name> [--with …]` | scaffold a `@skills-dir` plugin |
 | `claude plugin install <name>@<marketplace> [-s user\|project\|local] [--config k=v]` | install |
-| `claude plugin update <name>@<marketplace>` | update — the **full `name@marketplace` form is mandatory** |
+| `claude plugin update <name>@<marketplace>` | update. Docs accept a bare `<name>`; **2.1.212 does not** — `claude plugin update make-skill` answers `Plugin "make-skill" not found`, exits 0, changes nothing. Always pass `name@marketplace` |
 | `claude plugin enable\|disable <name>@<marketplace>` | toggle without uninstalling |
 | `claude plugin uninstall <name>@<marketplace> [--keep-data] [--prune]` | remove (deletes the data dir unless `--keep-data`) |
 | `claude plugin list [--json]` | installed plugins, versions, source, state |