@ssheleg/make-skill 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## v0.29.0 — the standard now reads a hook key the host ignores
+
+Claude Code 2.1.270 began printing `hooks.json: unknown key "if" in
+hooks.PreToolUse[1] ignored` at every session start. The key had been there since
+agent-sync 0.1.0, and the same shape sat in the hooks template `task-pipeline`
+exports into consumer projects — where the documentation gate then ran on **every**
+Bash call rather than on commits. Nothing caught it: not nine member validators, not
+this auditor, and not `claude plugin validate --strict`, which accepts the file.
+
+- **`HOOKS_SCHEMA`** reads the plugin's `hooks/hooks.json` from a skill at
+  `<plugin>/skills/<name>` and refuses any key outside the set its level accepts —
+  a matcher group takes `matcher` + `hooks`; a `command` handler takes `type`,
+  `command`, `args`, `if`, `shell`, `timeout`, `statusMessage`, `once`, `async`,
+  `asyncRewake` and three `@internal` keys. Both sets are read out of the 2.1.270
+  binary's schema rather than from prose. A manifest that does not parse is a GAP
+  (the host then loads no hooks at all); a plugin with no manifest passes and says
+  so; a `prompt`/`agent`/`http`/`mcp_tool` handler is **declared unchecked**,
+  because only the command handler's key set was measured.
+- **`BUNDLE_NESTED` stops reporting `__pycache__`.** A byte-compile cache appears
+  the moment a test imports a shipped module; it is gitignored and npm-excluded in
+  every member, and three of them were carrying the gap for a directory that never
+  ships.
+- `references/host-capabilities.md` states both key sets, where `if` lives, the
+  loader's exact warning, and that `validate --strict` is not the gate for this.
+
+Every shipped skill in the family passes: 28 of 28 at `0 GAP`, now `19 PASS`.
+
 ## v0.28.0 — the house audit measures the token budget instead of estimating it
 
 Sherlock external-v3 (13 findings) plus the enterprise handoff (PR #18) and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/make-skill",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Create, retrofit, audit, and ship agent skills & Claude Code plugins the proven ssheleg way \u2014 conformance to the Agent Skills open standard AND Anthropic's platform rules (front-matter limits, disclosure budgets, per-surface runtime limits, the Skills API, evals) plus 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, the review checklist for third-party skills, 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, Anthropic's platform rules (surfaces, Skills API, evals) 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, the review checklist for third-party skills, plus MCP / A2A references for protocol-connected skills.",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Authoring works on any agent. The bundled scripts/ need python3. Publishing steps need git, gh, node and npm; the plugin gates need the claude CLI. Not usable on the Claude API surface, which has no network and no runtime package install.
 metadata:
   author: ssheleg
-  version: "0.28.0"
+  version: "0.29.0"
   homepage: https://github.com/ssheleg/make-skill
 ---
 

package/plugins/make-skill/skills/make-skill/references/host-capabilities.md

@@ -83,7 +83,28 @@ an unanchored regex. Tool names are what you match (`Bash`, `Write`,
 `mcp__server__tool`). A plugin's OWN MCP server is matched as
 `mcp__plugin_<plugin>_<server>__<tool>`, and an `mcp_tool` hook names the server
 as `plugin:<plugin>:<server>` — the bare key never fires. Narrow further with
-`if`, a permission rule: `"if": "Bash(git commit *)"`.
+`if`, a permission rule: `"if": "Bash(git commit *)"` — **inside the handler
+object**, beside `type` and `command`.
+
+**Two key sets, and putting a key in the wrong one is silent.** Read out of the
+2.1.270 binary's schema: a matcher group takes `matcher` and `hooks`, nothing
+else; a `command` handler takes `type`, `command`, `args`, `if`, `shell`,
+`timeout`, `statusMessage`, `once`, `async`, `asyncRewake` (plus three
+`@internal` keys). Anything outside its set is **ignored** — the hook still runs,
+with the key doing nothing. Before 2.1.270 nothing said so at all; from it the
+loader prints once per session:
+
+```
+Plugin <name>: hooks.json: unknown key "if" in hooks.PreToolUse[1] ignored
+```
+
+`claude plugin validate --strict` accepts the file either way, so a skill audit
+is the only gate that catches this before a session starts — `HOOKS_SCHEMA` in
+`scripts/audit_skill.py` reads both sets. The family paid for that check: `if`
+sat beside `matcher` in `agent-sync` from 0.1.0 to 1.20.0 (harmless — its guard
+narrowed to a commit with its own parser), and in the hooks template
+`task-pipeline` tells projects to paste into `settings.json`, where the
+documentation gate then ran on **every** Bash call instead of on commits.
 
 **Exit codes are the contract:**
 
@@ -245,6 +266,8 @@ what the agent reads at the exact moment something is missing.
 - [ ] Hook scripts exit 0 silently on "not mine" and on a missing interpreter
 - [ ] `PostToolUse` advises (`systemMessage`), `PreToolUse` blocks — not the reverse
 - [ ] Hook commands quote `"${CLAUDE_PLUGIN_ROOT}"` and set a `timeout`
+- [ ] Every key is in the set its level accepts — a filter goes on the handler,
+      never beside `matcher`, where the host ignores it without failing
 - [ ] Hook scripts are executable, have a shebang, and need no `jq`
 - [ ] No command named after a skill — or the collision is on a recorded, dated
       exception list (see *Commands*); every `argument-hint` quoted

package/plugins/make-skill/skills/make-skill/scripts/audit_skill.py

@@ -247,6 +247,26 @@ TIME_BRANCH_RE = re.compile(
     r"(?:january|february|march|april|may|june|july|august|september|october|"
     r"november|december|\d{4})\b", re.I)
 BUNDLE_DIRS = ("references", "scripts", "assets")
+# A byte-compile cache is not a bundled directory: `__pycache__` appears the moment a
+# test imports a shipped module, is gitignored and npm-excluded in every member, and
+# three of them were reporting BUNDLE_NESTED for a directory that never ships.
+BUNDLE_IGNORE = ("__pycache__",)
+
+# Claude Code's hooks schema, read out of the 2.1.270 binary rather than from the
+# documentation: `Rt()` is the matcher GROUP and `Td()` the handler union. A key outside
+# these sets is IGNORED — silently before 2.1.270, and from it announced once per session
+# as `Plugin <name>: hooks.json: unknown key "<k>" in hooks.<Event>[<i>] ignored`. It is
+# not a syntax error, `claude plugin validate --strict` passes the file, and the hook goes
+# on running with the filter absent. agent-sync shipped `"if"` beside `"matcher"` from
+# 0.1.0 to 1.20.0 and task-pipeline exported the same shape in the template it tells
+# projects to paste into `settings.json`, where the gate then ran on every Bash call.
+HOOK_GROUP_KEYS = {"matcher", "hooks"}
+# The `command` handler. `if` is HERE — beside `type` and `command`, never beside
+# `matcher`. The last three are marked `@internal` in the schema and are accepted.
+HOOK_COMMAND_KEYS = {
+    "type", "command", "args", "if", "shell", "timeout", "statusMessage", "once",
+    "async", "asyncRewake", "rewakeMessage", "rewakeSummary", "cloud",
+}
 
 # A file in a publishable payload whose name reads as a credential. Fixtures and
 # test data are the common carriers; the auditor names it rather than shipping it.
@@ -447,6 +467,7 @@ def audit(skill_dir, house=False):
     _check_keys(a, fm, fm_lines, rel)
     _check_body_budget(a, body, rel, house)
     _check_bundle(a, skill_dir, text, name_on_disk)
+    _check_plugin_hooks(a, skill_dir)
     _check_links(a, skill_dir, text, rel)
     _check_distribution(a, skill_dir, name_on_disk)
     _check_prose(a, body, rel)
@@ -741,6 +762,8 @@ def _check_bundle(a, skill_dir, skill_text, dir_name):
         for entry in sorted(os.listdir(d)):
             full = os.path.join(d, entry)
             rel = os.path.join(dir_name, sub, entry)
+            if entry in BUNDLE_IGNORE:
+                continue
             if os.path.isdir(full):
                 a.gap("BUNDLE_NESTED", "%s/%s/ is nested — keep bundled files one level "
                       "deep, or the agent previews them instead of reading them"
@@ -762,6 +785,84 @@ def _check_bundle(a, skill_dir, skill_text, dir_name):
         a.ok("BUNDLE_LAYOUT", "bundled directories present and checked")
 
 
+def _check_plugin_hooks(a, skill_dir):
+    """The plugin's `hooks.json` carries only keys the host evaluates.
+
+    A skill inside a Claude Code plugin sits at `<plugin>/skills/<name>`, so the hooks
+    manifest is two levels up. This runs once per skill, which means a defective manifest
+    is reported once per skill of that plugin — a repetition, never a miss.
+
+    Reported as a GAP rather than a note because the failure is silent in both
+    directions: the key does nothing, and nothing said so for six weeks across two
+    repositories. `claude plugin validate --strict` accepts the file, so a skill audit is
+    the only gate this class can be caught by before a session start.
+    """
+    d = os.path.abspath(skill_dir.rstrip("/"))
+    parent = os.path.dirname(d)
+    if os.path.basename(parent) != "skills":
+        a.ok("HOOKS_SCHEMA", "not a plugin skill layout (<plugin>/skills/<name>) — no "
+             "hooks manifest to read from here")
+        return
+    plugin = os.path.dirname(parent)
+    path = os.path.join(plugin, "hooks", "hooks.json")
+    rel = os.path.join(os.path.basename(plugin), "hooks", "hooks.json")
+    if not os.path.isfile(path):
+        a.ok("HOOKS_SCHEMA", "the plugin ships no hooks/hooks.json — nothing to read", rel)
+        return
+    try:
+        data = json.load(open(path, encoding="utf-8"))
+    except Exception as e:
+        a.gap("HOOKS_SCHEMA", "hooks.json does not parse (%s) — Claude Code loads no "
+              "hooks at all from a manifest it cannot read" % e, rel)
+        return
+    events = data.get("hooks")
+    if not isinstance(events, dict):
+        a.gap("HOOKS_SCHEMA", "hooks.json has no `hooks` object — the manifest declares "
+              "nothing the host can run", rel)
+        return
+    bad = []
+    unchecked = set()
+    for event, groups in sorted(events.items()):
+        if not isinstance(groups, list):
+            bad.append("hooks.%s is not a list of matcher groups" % event)
+            continue
+        for i, group in enumerate(groups):
+            if not isinstance(group, dict):
+                bad.append("hooks.%s[%d] is not an object" % (event, i))
+                continue
+            for k in sorted(set(group) - HOOK_GROUP_KEYS):
+                bad.append('hooks.%s[%d]: %r sits beside `matcher`, where a matcher group '
+                           'takes only matcher+hooks — the host ignores it (a filter '
+                           'belongs inside the handler)' % (event, i, k))
+            handlers = group.get("hooks")
+            if not isinstance(handlers, list):
+                bad.append("hooks.%s[%d].hooks is not a list of handlers" % (event, i))
+                continue
+            for j, h in enumerate(handlers):
+                if not isinstance(h, dict):
+                    bad.append("hooks.%s[%d].hooks[%d] is not an object" % (event, i, j))
+                    continue
+                if h.get("type") != "command":
+                    unchecked.add(str(h.get("type")))
+                    continue
+                for k in sorted(set(h) - HOOK_COMMAND_KEYS):
+                    bad.append("hooks.%s[%d].hooks[%d]: %r is not a key the command-hook "
+                               "schema knows — the host ignores it" % (event, i, j, k))
+    for msg in bad:
+        a.gap("HOOKS_SCHEMA", msg, rel)
+    if not bad:
+        note = ""
+        if unchecked:
+            # Say what was NOT read. The command handler's key set was measured; the
+            # prompt/agent/http/mcp_tool handlers were not, and claiming them clean would
+            # be a verdict about something this check never looked at.
+            note = " (handler type(s) %s not checked — only the command handler's key "
+            note %= ", ".join(sorted(unchecked))
+            note += "set is measured here)"
+        a.ok("HOOKS_SCHEMA", "every hooks.json key is one Claude Code evaluates%s" % note,
+             rel)
+
+
 def _check_links(a, skill_dir, skill_text, rel):
     """A relative link that escapes the skill directory arrives broken everywhere.